FIDICcharts
FIDICbot - a text-prompt interface for FIDIC contracts
 

VIEW DEMO VIDEO


Web app (mobile and desktop)


Messenger

  • mobile: using the Messenger mobile app, search for "fidicbot"
  • mobile: using a camera, scan the QR code below to open FIDICbot in Messenger
  • mobile or desktop: using a browser, click the QR code below to open FIDICbot in Messenger
     
    Add FIDICbot to Messenger chat


Telegram

  • mobile: using the Telegram mobile app, search for "fidicbot"
  • mobile: using a camera, scan the QR code below to to open FIDICbot in Telegram
  • mobile or desktop: using a browser, click the QR code below to open FIDICbot in Telegram
     
  • Add FIDICbot to Telegram chat


LINE

  • mobile: using the LINE mobile app, search for "@ovs8540y" in Official Accounts
  • mobile: using the LINE mobile app, scan the QR code below to add the FIDICbot Official Account
  • mobile: using a camera, scan the QR code below to add the FIDICbot Official Account
  • mobile: using a browser, click the QR code below to add the FIDICbot Official Account
  • desktop: app cannot be opened by clicking a web link. Instead, install and open the LINE desktop app (a mobile account is needed), and under Search for friends -> LINE Id enter "@ovs8540y"
     
    LINE FIDICbot Official Account add to chat


Viber
December 2019: please Viber to +41792989666 so that admin can share the FIDICbot as a follower (FIDICbot can be found as a Viber Official Account once there are enough followers).

  • mobile: using the Viber mobile app, search for "fidicbot" in Viber's Official Accounts (pending more followers).
  • mobile: using the Viber mobile app, scan the FIDICbot QR code.
  • desktop: app cannot be opened by clicking a web link. Instead, install and open the Viber desktop app (a mobile account is needed), and under Select contracts -> search for FIDICbot (activated once there are enough followers)
     
    Viber FIDICbot


Skype
Use FIDICchatbot version (also available on Messenger, Telegram, Viber, and WhatsApp)

  • mobile and desktop: using a browser, click the QR code below to open in Skype
     
    Add FIDICbot to Skype chat


Versions

FIDICbot has two versions:

  • Smooch version
    RECOMMENDED since advanced search is available.
    Smooch version for Telegram, Messenger, Viber, and LINE (and SMS via Twilio, if activated) with a web interface here, via the icon at the bottom-right of this page and at FIDIC.pw.
  • MBF version
    REQUIRED for Skype and WhatApp, but advanced search is not available.
    Microsoft Bot Framework version for Skype (and WhatsApp via Twilio if activated) and available on Telegram and Messenger (LINE performs badly).

Smooch

The Smooch version of FIDICbot uses Smooch multichannels that serve Twitter Telegram, Facebook Messenger, Viber, and Line as well as a web channel and SMS.

The Microsoft Both Framework (MBF) version of FIDICbot uses MBF multichannels that primarily serve Skype and WhatsApp, but also serve Twitter Telegram, Facebook Messenger, and Line as well as a web channel and SMS. This MBF version is described separately under FIDICchatbot and is not recommended as it does not offer advanced searching of the FIDIC documents.

This page describes the Smooch version. The MBF version is described on FIDIC.tips/chatbot.


Introduction

We use the Smooch version to serve the web, Telegram, Messenger, LINE, and Viber channels (and SMS if Twilio is activated). This is the preferred and most complete FIDICbot.


Sources

Applications and source files for the FIDIC contracts, indexes and guides are stored on GitHub. They are served using Heroku that is integrated into Smooch and Azure bot channels. Applications are served under node.js and written in Javascript and Express.


Limitations

For the Smooch version of FIDICbot we are using smooch.io as the multi-channel integration platform so that we can have a single bot app that is accessed through several of the most important messenger channels (Smooch offers a web app as well as messenging through Facebook Messenger, Twitter Telegram, WeChat, LINE, Viber, Slack in an interactive mode and SMS via Twilio). Dexter seems to have a more advanced, but more complicated, offering. We deployed the app to Heroku and have the files on GitHub (the set-up is well explained by EstherBot on Github).

Smooch uses standard formats for messages integrated into SMS, Messenger, Telegram, etc. which cannot be adjusted (apart from some minor adjustments for things like the avatar that is displayed and colours). One is therefore reduced to having the bot work with the lowest common denominator, which is Messenger where Smooch limits the number of characters in the message and the number of buttons for links (i.e., Smooch uses Messenger's Structured Message Generic Template). So we have to break up long clauses into several parts and for a long list of link buttons, have separate messages (saying "....") each with three link buttons.

Recently, by serving the Smooch libraries and styles separately we can modify extensively the message style. This helps overcome some of the limitations. The Smooch Web Messenger (Version 4) files are server from a public github respository.


Background

FIDIC1, the International Federation of Consulting Engineers, publishes standard forms of contracts for works projects and professional services. The most widely used are:

  • WORKS CONTRACTS
    • Construction Contract (1st Edition 1999) for building and engineering works designed by the Client, with the 2nd Edition published and incorporated in FIDICbot,
    • Plant and Design-Build Contract(1st Edition 1999) for electrical and mechanical plant and for building and engineering works designed by the Contractor, with the 2nd Edition 2017 now published but not yet included in the FIDICbot,
    • EPC/Turnkey Contract (1st Ed 1999) for building and engineering works designed by the Contractor, with the 2nd Edition 2017 now published but not yet included in the FIDICbot.
  • SERVICES AGREEMENTS
    • Client-Consultant Model Services Agreement (5th Ed 2017) - White Book for professional services supplied to a Client by a Consultant.


Approach - Codes

Remembering that a bot must work on every media ranging from small smartphones to full-screen computer monitors and TVs, we need a simple and short way to specify the type of search in a FIDIC Contract. Currently we use a one-letter code for the contract (e.g. "c1" for the Construction Contract, 1st Edition 1999). WolframAlpha does something similar, but as an app and not as a bot.

Why? Having a one-letter contract code allows us to have clauses from the various FIDIC contracts displayed together (rather then attempting to somehow integrate separate bots for each contract). Having the various contracts allows comparisons of clauses (this will be implemented at some stage).

Search codes also serve as shortcuts. If one submits a clause number or a keyword without a code, the bot offers two options: a) a default scope (a search in the Construction Contract 1st Ed 1999 index); b) select a contract code. But if one types in a contract code (e.g., "c1" for Construction Contract) before a keyword (e.g., "c1 payment") one searches the Construction Contract 1st Ed 1999 index immediately without first accessing the Construction Contract.

Contract codes are stored so once a contract is selected, subsequent searches use the code without the need to submit a code for each search. For instance, with "c1" set as the contract code for the Construction Contract 1st Ed 1999, one can then submit say 1.2 to display Clause 1.2. Submiting "payment" will search the Construction Contract's index for the word 'payment'.

We like the idea of not simply a search for a clause within all clauses using a keyword or keywords but a more intelligent search that takes a topic scope (e.g. adjudication or anti-corruption) and allows clauses to be selected that refer to the topic. Ultimately artificial intelligence could be used here, even with user feedback, to guide the selection of clauses that are relevant for a given topic. We have tested this approach using two- and three-character search codes combined with indexes for specific topics. The results are unconvincing. Simple indexes to identify contract clauses that relate to specific issues concerning, for example, corruption do not work.

For index searches, the default keyword search is in a contract's index. For the indexes we use expanded indexes. For works contracts, they are based on the official FIDIC index that is published in the works contracts. For services agreements we use our own indexes.

For advanced searches, we display thenumber of clauses that corresopond to a standard set of 15 categories. Users then select the category that is likely to be the most relevant to obtain the final list of the most relevant clauses. We have asked FIDIC to maintain a standard set of clause categories to facilitate this type of advannced search.


Button prompts

We feel that having text entries is cumbersome. After all we are dealing with standard forms of contracts with 90-odd percent of text the same between some contracts. So we have many standard words apart for the defined terms. We use buttons as prompts as well as text.

One could envisage a mix of the two - a button prompt enters text in the text entry so that the text could be modified. We might have a look at this one day.

For searches, we feel that on a small screen it is impractical to have a running list of the clauses that contain a certain keyword. One can do it but we feel it is better to limit the number of clauses that are displayed using a clause type and reference with a keyword (and/or maybe modifiable keywords).

A multi-word free-text search using some sort of algorithm à la Google et al may be interesting possibility, along with artificial intelligence. The latter would probably be overkill for searches in an index but maybe interesting for topic-clause scopes, especially if user-feedback is incorporated. That is enough for the speculation. Now the codes.


Codes

The FIDICbot currently uses the codes given below. When we say "clause" we mean a clause or a sub-clause in the General Conditions of each contract, or in the Guidance for Particular Conditions that FIDIC publshes with the General Conditions. The annexed Dispute Adjudication Agreement (DAA) and the procedural rules are also included, and for services agreements, the appendices are included.

Codes are chosen that can be easily typed and understood by word recognition by most mobile phone messenger clients. There are two types of codes, namely:

  • Contract
    • Contract (a keyword searches the index of all the contract's clauses; contracts are currently only the 1st Ed 1999):
      • c1 = Construction Contract (Construction). The 2nd Edition 2017 is being loaded as contact code "c2".
      • p1 = Plant and Design-Build Contract (Plant)
      • e1 = EPC/Turnkey Contract (EPCT)
      • w = Client/Consultant Agreement (White Book)


Examples of codes

Contract codes

Here are some examples of searches using contract codes:

  • "c1": sets the Construction Contract, 1st Edition 1999, so that subsequent searches such as "1.2" take you to Clause 1.2 or "payment" takes you to clauses with "payment" in the Construction Contract 1st Ed 1999 index.
  • "c1 2.1": go to clause 2.1 of the Construction Contract 1st Ed 1999 .
  • "p1 1.1.9": go to clause 1.1.9 of the Plant Contract 1st Ed 1999 .
  • "c1 contract": gives clauses with the word "contract" in the index of the Construction Contract 1st Ed 1999.

Most chatbot messenger platforms provide buttons. In some cases it is necessary however to say or type in a code or keyword. These can be in upper or lower case. This is the case for LINE.


Standard prompts

There are some standard prompt keywords (we do not want too many and they must be short):

  • HELLO
  • BEGIN
  • START
  • HELP
  • CODES
  • SELECT
  • c1, c2 or p1 or e1 or w - very common starting points (the search scope is the index of all clauses in the FIDIC Construction 1st and 2nd Editions, Plant 1st Edition, EPC/Turnkey 1st Edition contracts, and the Client-Consultant Agreement).


DEvelopments

The current limitations in order of ease of correcting at some stage (we wont say which we plan to sort out) are:

  • guidance: we have started adding a link for each clause to guidance (see the GUIDE buttons);
  • changes: we are evaluating whether we can display changes between two editions of a contract;
  • we are unsure if we shall include links to links to sample letters, case law, user comments, etc.;
  • Multilateral Development Bank edition of the Construction Contract should be included, and indeed other FIDIC forms of contract such as the Design-Build-Operate Contract;
  • probably need to process possibly redundant characters (e.g., typing "non-compliant" gives the same as "noncompliant", and vice-versa);
  • no translations (obviously easy to overcome provided publishers agree).


Status

Coding the text of the contracts is obviously a simple task. As with our other visualisation strategy for complex, structured documents (namely charts, and in the case of FIDIC contracts, FIDIC Charts) we are using json files instead of a database (because for charts we want an offline app). We have considerable experience for the charts in manipulating and combining json files. We can build upon this expertise for the bots, and ideally use the same json base files, but with different manipulations.

The pilot phase will tell us if large json files lead to the bot being too slow.


Acknowledge

While the FIDIC contracts could be construed as being in the public domain owing to their legal status and the way they are proposed to users, we firmly believe that the General Conditions are copyrighted, as indicated by FIDIC. Users are invited by FIDIC to modify other parts of the published contracts (except the Dispute Adjudication Agreement) so these parts are not subject copyright.

FIDIC's general principle in according the right to other parties to publish text from General Conditions is that the length of excepts should be relatively short and there should be no realistically feasible way to combine excepts to produce the complete, authentic text. The bot approach clearly meets these conditions.


Technology

Bots seem to be taking off after a long gestation because smartphones are becoming the dominant media for Internet activity, especially for tracking, customer feedback, transactions, and payments. The messaging platforms feel that they can offer developers and indeed normal users ways to integrate advanced capabilities (voice, artificial intelligence, payments, etc.) across all media using bots instead of apps.

Currently, as mentioned, FIDICbot is deployed from Github to Heroku with channel integration by Smooch.

We plan to make the Smooch version of FIDICbot available publically on Github.


INFORMATION

If you are interested in exploring text-prompt bots for advanced user interfaces to complex, structured documentation, please contact Peter Boswell. Peter is the former FIDIC General Manager and is now working as a consultant with Bricad Associates, see peterboswell.com.

Bricad Associates Sàrl, is based in Coppet on the outskirts of Geneva, Switzerland (website).

Bricad groups all its management information and user support platforms under Bricad.online.