diff --git a/docs/accordproject-ai.md b/docs/accordproject-ai.md new file mode 100644 index 00000000..ef57c58e --- /dev/null +++ b/docs/accordproject-ai.md @@ -0,0 +1,157 @@ +--- +id: accordproject-ai +title: AI & Agent Workflows +--- + +## Computable Contracts as Agent Infrastructure + +Most contracts today are word-processed documents. The key provisions and data-points within that text are challenging for machines to extract reliably, and the underlying logic is even harder to automate — meaning significant overhead falls on manual human processes to manage, perform, and enforce contractual terms. + +The 2024 Accord Project whitepaper, [*An Introduction to Computable Contracts*](https://accordproject.org/whitepaper-2024/), frames this as the "contract gap" — and identifies structured, computable contract formats as both the complement to, and the grounding for, large language model (LLM) based workflows: + +> *"Accord Project data formats are useful to have as the output from ML processes so that we can more easily ingest the documents into other tools. Similarly, structured data formats (called Schemas or Domain Models) can also be used to complement the input for some ML processes."* + +Accord Project's three-component template architecture — **Text**, **Model**, and **Logic** — maps directly onto how modern AI agents operate. Each component is a format that agents can reliably read, write, validate, and reason over. + +--- + +## Why Markdown? + +Accord Project template text is written in **TemplateMark**, a minimal extension of [CommonMark Markdown](markup-commonmark.md). Markdown was chosen deliberately: + +- It is a lightweight, textual format focused on semantics rather than layout. +- It has broad cross-platform adoption and an [open specification](https://commonmark.org). +- It is the lingua franca of LLMs — the vast majority of training data for modern language models is Markdown or plain text. Agents that draft, review, or summarise a TemplateMark document are working in a format they already understand at training-data scale. + +TemplateMark extends Markdown minimally: `{{variable}}` placeholders for data, and `{{% expression %}}` for computed values. An agent encountering a TemplateMark document needs almost no specialised knowledge to work with it — the additions are self-explanatory in context. + +TemplateMark also round-trips cleanly between its Markdown text form and a JSON object form (AgreementMark). This means agents can output structured JSON that the template engine renders to rich text, or they can work directly with the Markdown and have it parsed to JSON downstream. + +```tem +## Fixed Rate Loan + +This is a *fixed interest* loan to the amount of {{loanAmount}} +at the yearly interest rate of {{rate}}% +with a loan term of {{loanDuration}}, +and monthly payments of {{% monthlyPaymentFormula(loanAmount,rate,loanDuration) %}}. +``` + +An agent can read this, understand the variables, fill values, and produce a rendered agreement — all using formats it already knows. + +--- + +## Why TypeScript? + +Contract logic in Accord Project is written in **TypeScript**. From the 2024 whitepaper: + +> *"Accord Project templates are therefore strongly-typed. The logic in templates is expressed in TypeScript. TypeScript is a strongly-typed, general purpose programming language, supported by a vibrant Open Source and enterprise community. TypeScript compiles to JavaScript for easy execution on most platforms."* + +For agent workflows, TypeScript's strong typing provides a critical safety guarantee: + +- **Agents can generate TypeScript logic** for contract calculations and the compiler will catch type errors before execution. +- **Concerto auto-generates TypeScript interfaces** from the schema, so the types the agent codes against are derived directly from the contract's data model — not guessed. +- **Templates compile to TypeScript programs** statically, enforcing type-safety and ensuring no unsafe runtime `eval()` is required. +- **The compiler acts as a verification step** between agent output and deployment — errors in agent-generated logic surface as compile failures, not silent runtime bugs in payment calculations or clause conditions. + +```typescript +import { PaymentObligation } from '@accordproject/cicero-core'; +import { LoanModel } from '../model/LoanModel'; + +export class LoanLogic extends TemplateLogic { + monthlyPaymentFormula(loanAmount: number, rate: number, loanDuration: number): number { + const monthlyRate = rate / 1200; + return (loanAmount * monthlyRate) / (1 - Math.pow(1 + monthlyRate, -loanDuration)); + } +} +``` + +See the [Template Logic guide](logic-typescript.md) for full documentation. + +--- + +## Why Concerto Schema? + +**Concerto** is the schema DSL Accord Project uses to describe the structure of contract data. It is the critical layer that grounds agent output and prevents hallucinations from propagating into contract terms. + +When an agent populates template variables, the Concerto schema enforces that: +- `{{rate}}` receives a `Double` — not the string `"January"` +- `{{loanDuration}}` receives an `Integer` — not a floating-point number +- `{{partyAddress}}` receives a structured `Address` object — not free-form text + +Invalid values fail at schema validation, not at runtime during contract execution. This is the same principle as JSON Schema for APIs — structured contracts reduce hallucination risk structurally, not just by prompt instruction. + +```concerto +namespace org.accordproject.loan + +concept LoanModel { + o Double loanAmount // floating-point dollar amount + o Double rate // annual interest rate as a percentage + o Integer loanDuration // term in months + o Double monthlyPayment // computed or supplied monthly payment +} +``` + +Concerto models convert to a wide variety of platform-specific formats, so agent output validated against a Concerto model can be re-validated in any downstream runtime: + +| Target | Use case | +|---|---| +| **JSON Schema** | REST API validation, OpenAPI specs | +| **TypeScript** | Contract logic, frontend type safety | +| **Java** | Enterprise backend integration | +| **Go** | High-performance services | +| **C#** | .NET integrations | + +Concerto also enables **Schema Inference**: LLMs can create data models from sample contracts or natural language descriptions. See the experimental [Finchbot](https://finchbot.net/) service and Dan Selman's [blog on text-oriented programming](https://blog.selman.org/2023/08/07/text-oriented-programming/) for examples. + +See [Concerto documentation](https://concerto.accordproject.org/docs/intro) for full details. + +--- + +## APAP & MCP: Calling Contracts from Agents + +The **Agreement Protocol API (APAP)** is a REST interface that exposes Accord Project contract templates as callable services. Any AI assistant or agent orchestration framework can interact with templates over APAP as tool calls. + +APAP includes a **Model Context Protocol (MCP) endpoint**, making Accord Project templates directly accessible to MCP-compatible AI clients — including Claude, Cursor, and other tools that support the MCP standard. + +Through APAP, an agent can: + +- **Draft** a contract by supplying deal terms to a template +- **Validate** that supplied data conforms to the Concerto schema +- **Execute** contract logic against incoming events (e.g. a payment received, a delivery confirmed) +- **Render** the agreement to HTML, PDF, or DOCX + +``` +POST /triggers/{templateId} +{ + "request": { "loanAmount": 100000, "rate": 2.5, "loanDuration": 15 }, + "state": {}, + "contractData": { ... } +} +``` + +See the [APAP tutorial](tutorial-apap.md) and [APAP reference](ref-apap.md) for full documentation. + +--- + +## LLM-Assisted Template Authoring + +Several tools support human-AI collaboration in template authoring: + +- **[Template Playground](https://playground.accordproject.org)** — Browser-based editor for authoring and testing templates. Search existing templates, modify text, and execute logic interactively. +- **[Accord Studio](tutorial-studio.md)** — Full web-based authoring environment with preview and integrated testing. +- **[VS Code Extension](tutorial-vscode.md)** — Syntax highlighting, validation, and execution of templates directly in your editor. + +Academic research has validated LLM-to-template pipelines in production scenarios: + +- A joint team from National Taiwan Normal University, UCL, and HSBC Business School demonstrated automated [conversion of natural language contracts to Accord Project templates using NLP](https://arxiv.org/abs/2210.08954). +- Northwestern University and Adobe Research published a pipeline using AI-extracted [Obligation Logic Graphs (OLGs)](https://doi.org/10.1145/3594536.3595162) mapped to Accord Project templates, presented at ACM ICAIL 2023. + +--- + +## Further Reading + +- [2024 Whitepaper: *An Introduction to Computable Contracts*](https://accordproject.org/whitepaper-2024/) — the full case for computable contracts as agent infrastructure (also available as [Markdown on GitHub](https://github.com/accordproject/whitepaper-2024/blob/main/whitepaper.md)) +- [Smart Legal Contracts](accordproject-slc.md) — how machine-readable and machine-executable contracts work +- [APAP Reference](ref-apap.md) — full API specification including MCP endpoint +- [Template Logic in TypeScript](logic-typescript.md) — writing strongly-typed contract logic +- [Concerto Documentation](https://concerto.accordproject.org/docs/intro) — schema DSL reference diff --git a/docs/accordproject-slc.md b/docs/accordproject-slc.md index da9f9f88..b5b757ac 100644 --- a/docs/accordproject-slc.md +++ b/docs/accordproject-slc.md @@ -75,3 +75,17 @@ This is a simple example of the benefits of Machine-Executable contract, here ad More complex examples, (e.g., how to add post-signature logic which responds to data sent to the contract or which triggers operations on external systems) can be found in the rest of this documentation. +### Machine-Legible to AI Agents + +Smart Legal Contracts are not just executable by traditional software — they are legible and generatable by AI agents. The 2024 whitepaper [*An Introduction to Computable Contracts*](https://accordproject.org/whitepaper-2024/) identifies several properties that make the three-component template architecture particularly well-suited to AI-assisted workflows: + +- **Markdown text** is the lingua franca of LLMs. An agent that drafts or reviews a TemplateMark document is working in a format it already understands at training-data scale. +- **Concerto schemas** act as a type contract for agent output. When an agent populates template variables, the schema enforces that `{{rate}}` receives a `Double`, not the string `"January"` — catching hallucinations structurally, not just by prompt instruction. +- **TypeScript logic** allows agents to generate contract calculation code that is statically verified by the TypeScript compiler before execution. Type errors surface before they can cause incorrect payment calculations or clause misfires. + +Academic research has demonstrated AI-to-template pipelines in practice. NLP pipelines at [Northwestern University / Adobe Research](https://doi.org/10.1145/3594536.3595162) and [National Taiwan Normal University / UCL / HSBC](https://arxiv.org/abs/2210.08954) have demonstrated automated extraction of contract obligations directly into Accord Project templates from natural language source documents. + +The [Agreement Protocol API (APAP)](ref-apap.md) exposes templates over a REST interface — including a Model Context Protocol (MCP) endpoint — so AI assistants and orchestration frameworks can author, fill, validate, and execute contracts as tool calls. + +See the [AI & Agent Workflows](accordproject-ai.md) guide for a full walkthrough. + diff --git a/docs/accordproject.md b/docs/accordproject.md index a07f863a..c557601d 100644 --- a/docs/accordproject.md +++ b/docs/accordproject.md @@ -26,9 +26,11 @@ If this interests you, please visit our [Lifecycle and Industry Working Groups]( ### For Lawyers -The Legal world is changing and Legal Tech is growing into a billion dollar industry. The modern lawyer has to be at home in the digital world. Law Schools now teach courses in coding for lawyers, computational law, blockchain and artificial intelligence. Legal Hackers is a world wide movement uniting lawyers across the world in a shared passion for law and technology. Lawyers need to move beyond the written word on paper. +The legal world is changing and Legal Tech is a [billion dollar industry](https://fortune.com/2023/10/02/global-trade-4-billion-paper-documents-daily-uk-document-act-law-finance-geraldine-mcbride/). The modern lawyer must be at home in the digital world. [Legal Hackers](https://legalhackers.org/) is a worldwide movement uniting lawyers across the world in a shared passion for law and technology. Increasingly, AI tools are being used to draft, review, and negotiate contracts — and the Accord Project gives legal professionals a path to digitize contract knowledge in a structured way that AI can reliably work with. -The template in an Accord Project Contract is pure legal text that can be drafted by lawyers and interpreted by courts. An existing contract can easily be transformed into a template by adding data points between curly braces that represent the Concerto model, and contract logic can be added as an integral part of the contract. The template language is subject to judicial interpretation and the Concerto model and contract logic can be interpreted by a computer, creating a bridge between the two worlds. +The template in an Accord Project Contract is pure legal text that can be drafted by lawyers and interpreted by courts. An existing contract can easily be transformed into a template by adding data points between curly braces that represent the Concerto model, and contract logic can be added as an integral part of the contract. The template language is subject to judicial interpretation, and the Concerto model and contract logic can be interpreted by a computer, creating a bridge between the two worlds. + +In November 2021, the Law Commission of England and Wales [concluded](https://lawcom.gov.uk/project/smart-contracts/) that the current legal framework is sufficiently robust and adaptable to support the use of smart legal contracts — confirming they are legally binding and enforceable agreements. As a lawyer, contributing to the Accord Project would be a great opportunity to learn about smart legal contracts. Through the Accord Project, you can understand the foundations of open source technologies and learn how to develop smart agreements. @@ -40,12 +42,14 @@ The Accord Project provides a universal format for smart legal contracts, and th The Accord Project is developing tools including a [Visual Studio Code plugin](https://marketplace.visualstudio.com/items?itemName=accordproject.cicero-vscode-extension), the [APAP agreement server API](https://github.com/accordproject/apap), and a command line interface for working with Accord Project Contracts. You can integrate contracts into existing applications, create new applications, or write contract logic in TypeScript. +If you are building AI agents or LLM-powered applications, Accord Project templates provide a structured, validated, and legally meaningful data layer. Templates can be invoked via the [APAP REST API](ref-apap.md) — including a **Model Context Protocol (MCP) endpoint** — so your agent can author, validate, and execute contracts as tool calls. The Concerto schema language provides a type-safe wire format that significantly reduces hallucination risk in agent-generated contract data. See the [AI & Agent Workflows](accordproject-ai.md) guide for details. + There is a welcoming community on Discord that is eager to help. [Join our Community](https://discord.com/invite/Zm99SKhhtA) ## About this documentation -If you are new to Accord Project, you may want to first read about the notion of [Smart Legal Contracts](accordproject-slc.md) and about [Accord Project Templates](accordproject-template.md). We also recommend taking the [Online Tour](accordproject-tour.md). +If you are new to Accord Project, you may want to first read about the notion of [Smart Legal Contracts](accordproject-slc.md) and about [Accord Project Templates](accordproject-template.md). We also recommend taking the [Online Tour](accordproject-tour.md). For AI and agent integration, see the [AI & Agent Workflows](accordproject-ai.md) guide. To start using Accord Project templates, follow the [Install Cicero](https://docs.accordproject.org/docs/next/started-installation.html) instructions in the _Getting Started_ Section of the documentation. diff --git a/docs/tutorial-hyperledger.md b/docs/tutorial-hyperledger.md index 3ceb3911..5c49cd7a 100644 --- a/docs/tutorial-hyperledger.md +++ b/docs/tutorial-hyperledger.md @@ -3,7 +3,9 @@ id: tutorial-hyperledger title: With Hyperledger Fabric --- -> **Deprecated:** Blockchain integrations (Hyperledger Fabric, Corda, QLDB) are no longer actively maintained by Accord Project. +> **Archived:** Blockchain integrations (Hyperledger Fabric, Corda, QLDB) are no longer actively maintained by Accord Project. This page is preserved for historical reference only. +> +> For modern integrations — including AI agent workflows — use the [Agreement Protocol API (APAP)](ref-apap.md), which exposes contract templates over a REST interface with a Model Context Protocol (MCP) endpoint. ## Hyperledger Fabric 2.2 diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 1a21a9e9..bf553e89 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -55,7 +55,7 @@ const config = { /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ navbar: { - title: 'Accord Project', + title: '', logo: { alt: 'Accord Project Logo', src: 'img/A-MARK-ACCORDPROJECT-ONELINE-white.svg', diff --git a/website/sidebars.js b/website/sidebars.js index 2d4f22f5..9a8af475 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -6,7 +6,7 @@ const sidebars = { { type: 'category', label: 'Introduction', - items: ['accordproject', 'accordproject-slc', 'accordproject-template', 'accordproject-tour', 'accordproject-faq'], + items: ['accordproject', 'accordproject-slc', 'accordproject-ai', 'accordproject-template', 'accordproject-tour', 'accordproject-faq'], }, { type: 'category', diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 7cf2e89e..b5aa66bb 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -88,7 +88,7 @@ } #features .blockContent > div { - color: #adb5bd; + color: #f0f4f8; font-size: 0.95rem; } diff --git a/website/src/pages/index.js b/website/src/pages/index.js index fe64a0d9..d1e9adf3 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -36,6 +36,10 @@ function HomeSplash() {

Smart Legal Contracts, Open Source

+

+ Legal text drafted by lawyers, interpreted by courts, and executable by software — + from the same open source template. +

@@ -56,15 +60,15 @@ function Features() { const coreTools = [ { title: Cicero, - content: 'Create templates for human-readable and machine-executable contracts using Open Source Cicero.', + content: 'Create templates where lawyers write the contract text in Markdown and software executes the logic. Use open source Cicero to render, validate, and run them — or call them from an AI agent.', }, { title: TypeScript, - content: 'Write executable business logic for legal contracts using TypeScript, with types generated from your Concerto model.', + content: 'Write TypeScript logic that precisely captures what the legal text says — strongly typed, so the compiler enforces intent before a contract is signed. Types are generated directly from your Concerto data model.', }, { title: Concerto, - content: 'Model the data for your contracts in a platform neutral format with the Concerto schema language.', + content: 'Model the deal terms in your contracts with the Concerto schema language — portable across JSON Schema, TypeScript, Java, Go, and more, so the data means the same thing everywhere. Learn more.', }, ]; @@ -79,6 +83,11 @@ function Features() { label: 'Model Repository', content: 'Reuse shared Concerto data models', }, + { + href: 'https://accordproject.org/whitepaper-2024/', + label: 'Whitepaper', + content: 'An Introduction to Computable Contracts', + }, ]; return ( @@ -101,12 +110,12 @@ function Features() { textAlign: 'center', lineHeight: '2', }}> - Ecosystem + Ecosystem {ecosystemLinks.map((link, i) => ( - {i > 0 && ·} - - {link.label} — {link.content} + {i > 0 && ·} + + {link.label} — {link.content} ))} @@ -122,7 +131,7 @@ function ContentBlock({ id, background, imageAlign, title, content, image, image const imageAlignClass = imageAlign === 'right' ? 'imageAlignRight' : 'imageAlignLeft'; const elementClass = hasImage ? `blockElement ${imageAlignClass} twoByGridBlock imageAlignSide` - : 'blockElement twoByGridBlock'; + : 'blockElement twoByGridBlock alignCenter'; return (
@@ -154,26 +163,6 @@ function Showcase() { const pinnedUsers = users.filter(u => u.pinned); return null; // Disable while this section is rebuilt - // if (pinnedUsers.length === 0) return null; - // return ( - //
- // - //

{"Who's"} {"Using This?"}

- //

This project is used by the following companies

- //
- // {pinnedUsers.map((user, i) => ( - // - // {user.caption} - // - // ))} - //
- // - //
- // ); } export default function Home() { @@ -202,7 +191,7 @@ export default function Home() { id="accord" background="dark" title="Text" - content='
CiceroMark lets you capture the data in a natural language clause or contract text through template variables. And it supports rich text markdown to ensure that your contracts look professional.
' + content='
CiceroMark lets you capture the data in a natural language clause or contract text through template variables. And it supports rich text markdown to ensure that your contracts look professional — and are natively legible to large language models.
' image="/img/grammar.png" imageAlt="An example of an Accord Project template text. There are 3 paragraphs of a contract with variables in each paragraphs and markdown annotations for formatting" imageAlign="left" @@ -210,7 +199,7 @@ export default function Home() { + +

Accord Project's three-component template architecture maps directly onto how modern AI agents operate.

+

The natural language text (TemplateMark/Markdown) is the format agents read and write fluently. The Concerto schema provides the structured type contract that constrains agent output. The TypeScript logic lets agents generate verifiable, type-safe business rules, with the compiler catching errors before they reach production.

+

The Agreement Protocol API (APAP) exposes contract templates over a REST interface — including a Model Context Protocol (MCP) endpoint — so any AI assistant or orchestration framework can author, fill, validate, and execute contracts as tool calls.

+

Learn more about AI & Agent Workflows →  ·  Read the Whitepaper →

+
`} + />
diff --git a/website/static/css/main.css b/website/static/css/main.css index 006f90cb..a07ba2a4 100644 --- a/website/static/css/main.css +++ b/website/static/css/main.css @@ -1172,6 +1172,7 @@ input::placeholder { .darkBackground code { color: #d6b3b8; + background-color: #1b2540; } .container.darkBackground .wrapper h1, @@ -3506,6 +3507,34 @@ a:hover { margin-top: 35px; } +/* ========================================================================== + Section > agent-workflows + ========================================================================== */ + +#agent-workflows .blockContent { + padding-left: 40px; +} + +@media only screen and (min-device-width: 360px) and (max-device-width: 736px) { + #agent-workflows .blockContent { + padding-left: 0px; + } +} + +#agent-workflows h2 { + color: #fff; + font-size: 40px; + line-height: 48px; + font-weight: 400; + letter-spacing: -1.5px; +} + +#agent-workflows .typeset { + color: #fff9; + text-align: left; + margin-top: 35px; +} + /* ========================================================================== Section > Nav Footer ========================================================================== */