Uwazi

Evidence-first tender review for African procurement teams.

Uwazi turns tender and bid documents into a cited review pack designed for a roughly 20-minute committee review. It never awards the tender: the AI proposes and the procurement committee decides.

Built for the Agentic AI for Africa Innovation Challenge — Governance track, Bid Box Challenge, Digital economy / Open contracting theme.

Demo video

A 63-second end-to-end walkthrough of the deployed platform running against a Neon Postgres database on Vercel. Shows every step — ingestion state (via /api/v1/admin/seed-status), the rendered tenders list, ranked report with citations, a live "Run agentic evaluation" click that runs the LangGraph workflow in real time, the audit trail, and the citizen-facing Open Notices layer. The video lives in video/uwazi-demo.mp4 (1.1 MB, H.264, no audio) — see video/README.md for the scene-by-scene breakdown.

Live deployment: https://uwazi-rose.vercel.app

Related MCP server: caseware-ai-procurement-knowledge-platform

Problem statement

Public procurement in African institutions is slow, opaque, and expensive. The challenge brief itself states the number: a single tender evaluation takes 26 days of committee work today — sorting bids, ticking off mandatory documents, checking each bidder, comparing prices, and writing the report. Across the continent, that is billions of USD in deferred decisions, locked-up supplier cash, and lost opportunities for small suppliers who cannot navigate the bureaucracy.

The status quo has three structural failures:

1. Time. 26 days of committee work per tender. Procurement offices are bottlenecked; small suppliers wait months to be paid; capital sits idle.

2. Opacity. A small supplier cannot easily find an active tender, understand the eligibility, or prepare the mandatory documents. The pipeline is legible only to insiders — exactly the constituency that doesn't need it.

3. Auditability. When a tender is contested — by a losing bidder, by an audit office, by a journalist — the procurement office's defence rests on a Word document edited by hand and signed by one person. There is no machine-readable audit trail.

Solution overview

Uwazi is an agentic AI on the Model Context Protocol that turns the 26-day evaluation into a 30-minute officer-reviewed exercise. The agent ingests a tender document and N bid documents, extracts the evaluation criteria, scores every bid against every criterion with paragraph-level citations, flags compliance risks (missing mandatory documents, abnormally low financials), and produces a ranked report with a per-bid recommendation. A procurement officer then records accept / reject / needs_review decisions — the only entity that can write the decision field.

For the Digital economy / Open contracting theme, Uwazi also exposes a citizen-facing layer: an open_notices tool that returns every active tender in plain English (eligibility checklist, mandatory documents, deadlines) — making the procurement pipeline legible to citizens and small suppliers, not just to insiders.

The hard architectural rule, enforced at three layers (SQL CHECK + trigger, MCP tool, test suite):

The agent may propose scores, risk flags, and recommendations. The agent may NEVER record a decision.

Target users

One command

git clone https://github.com/Roy-Wanyoike/uwazi.git
cd uwazi
./run-demo.sh

That's it. The script creates a venv, installs Uwazi, seeds a synthetic Makueni County water-procurement scenario with three bids, runs the LangGraph agent, demonstrates the human-in-the-loop boundary, and opens the review UI at http://localhost:8000.

A live deployment is also running on Vercel (Next.js + FastAPI multi-service) backed by a Neon Postgres database: https://uwazi-rose.vercel.app

Architecture

The diagram above shows the full system: users (procurement teams + suppliers/citizens) → MCP interface (FastMCP server, 10 tools, borrowed mcp-server-fetch) → LangGraph agents (5-node pipeline) → models & persistence (LLM gateway, document processing, SQLite/Postgres) → human-in-the-loop accountability gate at the bottom (AI output is draft-only → authorization enforced twice → human final decision + audit trail).

For the one-page architectural contract, see ARCHITECTURE.md. For the deep-dive (rules, ADRs, schema), see docs/architecture-deep-dive.md.

Setup & installation instructions

Prerequisites

• Python 3.11+

• Node.js 22+ (for the Next.js frontend)

• Internet access for the initial pip install and npm install

One-command setup (recommended)

git clone https://github.com/Roy-Wanyoike/uwazi.git
cd uwazi
./run-demo.sh

The script does everything: creates a Python virtualenv, installs Python + Node deps, seeds the sample Makueni tender + 3 bids, runs the LangGraph agent, demonstrates the human-in-the-loop boundary, and opens the review UI at http://localhost:8000.

Manual setup (if you'd rather see what's happening)

git clone https://github.com/Roy-Wanyoike/uwazi.git
cd uwazi

# Python side
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # set OPENAI_API_KEY for real Qwen scores; leave blank for STUB

# Frontend side (optional — the Python-only review UI at /web/index.html works too)
cd apps/web && npm install && cd ..

# Seed + run
python scripts/seed.py
python -m uwazi.cli evaluate --tender-id makueni-water-2026
python -m uwazi.cli serve    # → http://localhost:8000

Configuration (.env)

Every setting has a sensible default — the demo runs without any configuration. For real LLM scores (instead of STUB mode), set:

OPENAI_API_KEY=<your-modelscope-inference-token>  # NOT the read-only Studio token — needs inference scope
OPENAI_BASE_URL=https://api-inference.modelscope.ai/v1
OPENAI_MODEL=Qwen-Ambassador/Qwen3.7-Max

Usage instructions

As a procurement officer (via the review UI)

1. Open http://localhost:8000 (or the Vercel deployment URL).

2. Click Tenders in the header → select the Makueni County Water Reticulation Project.

3. If no report is shown, click Run agentic evaluation — the LangGraph orchestrator runs the 5-node workflow (extract criteria → analyze bids → score → flag risks → compose report).

4. Review the ranked bids. Each card shows the AI recommendation (award / shortlist / reject), weighted score, risk flags with citations, and an expandable list of scores with paragraph-level citations back to the tender and bid documents.

5. Click Accept / Needs review / Reject on each bid, enter a rationale (≥10 chars), and submit. The decision is persisted with decided_by='officer-web' and added to the audit trail.

6. Click View audit trail to see every AI proposal and human decision, timestamped and attributable.

As a citizen or small supplier (via the Open Notices page)

1. Open http://localhost:8000 (or the Vercel deployment URL).

2. Click Open Notices in the header.

3. Every active tender is shown in plain English: eligibility checklist, mandatory documents to prepare, and apply instructions. No legalese.

As an MCP client (Claude Desktop, custom agent, etc.)

python -m uwazi.cli mcp      # starts the FastMCP server on stdio

Connect from any MCP-compatible client. All 10 tools are listed below in the MCP tools / servers section.

Via the CLI

python -m uwazi.cli evaluate --tender-id makueni-water-2026        # run the agent
python -m uwazi.cli report   --tender-id makueni-water-2026         # fetch the ranked report
python -m uwazi.cli audit    --tender-id makueni-water-2026         # fetch the audit trail
python -m uwazi.cli demonstrate-human-in-the-loop --tender-id ...  # show the SQL trigger refusing an agent principal
python -m uwazi.cli serve                                         # start the FastAPI review UI
python -m uwazi.cli mcp                                          # start the MCP server (stdio)

Technology stack

Agent architecture

Uwazi is a LangGraph state machine with 5 nodes and 1 conditional edge. The agent plans, calls tools, recovers from failure, and stops at a hard human-in-the-loop gate.

                    ┌──────────────────────────────────────────┐
                    │           UWAZI LANGGRAPH GRAPH          │
                    └──────────────────────────────────────────┘

START → extract_criteria → analyze_bids → score_bids → flag_risks → compose_report → END
            │                  │              │             │              │
            └── (no criteria) ──────────────────────────────→ compose_report

Nodes (each is an async function of state):
  extract_criteria  ExtractorAgent     over tender paragraphs (LLM call)
  analyze_bids      BidAnalyzerAgent   per bid (LLM call)
  score_bids        ScorerAgent        per (bid, criterion) pair (LLM call)
  flag_risks        RiskAgent          per bid (LLM call)
  compose_report    OrchestratorAgent  pure Python (no LLM)

State is a single TypedDict (UwaziState) that flows through every node. Each node returns a partial dict that LangGraph merges. The graph is compiled with MemorySaver checkpointer — an interrupted evaluation can be resumed from the last checkpoint (not yet wired into the UI; see Limitations below).

Recovery path: if extract_criteria returns an empty list (the LLM found no criteria), the conditional edge skips analyze_bids → score_bids → flag_risks and jumps to compose_report, which produces a report with errors=["extractor: no criteria"] rather than crashing. Per-bid failures in analyze_bids / score_bids / flag_risks are caught, logged to state["errors"], and the bid is short-circuited — the rest of the bids continue.

Why LangGraph over a hand-rolled loop: it is a state machine. Each node is a function. The edges are conditional. The graph can be visualised (graph.get_graph().draw_*). State persists to SQLite (langgraph-checkpoint-sqlite), so an interrupted evaluation can be resumed. It is the de-facto open-source orchestrator for agent workflows with named-tool calls — strangers reading the code recognise the shape immediately.

MCP implementation

Uwazi is MCP-native. Every capability — ingesting documents, extracting criteria, scoring bids, recording decisions, fetching external tender notices — is exposed as an MCP tool. The orchestrator agent is an MCP client that calls the tools through the protocol.

This means:

• Any MCP-compatible client (Claude Desktop, the MCP CLI, a custom agent) can drive Uwazi.

• The procurement office can swap the LLM (Qwen, GPT, Claude, local Llama) without touching the agent code.

• The human-in-the-loop boundary is enforced at the MCP tool layer: record_officer_decision is the only tool that writes to the decision table, and it requires a human principal. The SQL CHECK + trigger is the second line of defense.

The MCP server is implemented in src/uwazi/mcp_server.py using the official mcp Python SDK's FastMCP class. The server runs on stdio transport by default (python -m uwazi.cli mcp), or as part of the FastAPI service on Vercel.

MCP servers built vs borrowed

MCP tools / servers

Uwazi's FastMCP server exposes 10 tools:

Human-in-the-loop workflow

The single most important architectural rule:

The agent may propose scores, risk flags, and recommendations. The agent may NEVER record a decision.

Enforced at three layers:

1. SQL — CHECK (decided_by <> 'agent') + BEFORE INSERT trigger on decisions. A reviewer can verify this in 60 seconds:

   sqlite3 uwazi.db "INSERT INTO decisions (id, tender_id, bid_id, decision, rationale, decided_by, decided_at) VALUES ('hack', 't', 'b', 'accept', 'agent hack', 'agent', datetime('now'));"
   # → Parse error: agent may not record decisions — human-in-the-loop rule (ARCHITECTURE.md §5)

   On Postgres (Vercel/Neon), the trigger is split into a CREATE OR REPLACE FUNCTION refuse_agent_decision_writer() RETURNS TRIGGER + CREATE TRIGGER — the same rule, dialect-appropriate syntax.

2. MCP tool — record_officer_decision refuses any request where principal_kind='agent'. Verified by tests/test_human_in_the_loop.py::test_tool_refuses_agent_principal.

3. Verification — focused tests exercise both the tool-layer refusal and the database constraint. The suite runs on every commit.

The workflow in practice

1. The agent runs the 5-node LangGraph workflow and produces a ranked report with scores, risk flags, and recommendations — all stamped ai_generated=True.

2. The procurement officer opens the report in the review UI. Every score is one click from the source paragraph it was derived from.

3. The officer records accept / reject / needs_review per bid, with a rationale (≥10 chars). The decision is persisted with decided_by='officer-demo' (or the OIDC principal in production).

4. The audit trail captures every AI proposal and every human decision, timestamped and attributable. Exportable as a signed PDF for the procurement archive.

Limitations

Uwazi is honest about what's unfinished. The brief rewards honesty about this.

• Run-to-run variance on the real open-weights model is not measured. STUB mode is deterministic; the real Qwen endpoint should be near-deterministic at temperature=0.0 but I have not measured σ per criterion. See EVALS.md — this is the one failure I did not fix, with a concrete next-step plan.

• LangGraph checkpoint resume is not yet wired into the UI. The graph is compiled with MemorySaver, so an interrupted evaluation can in principle be resumed, but the review UI does not yet expose the resume button.

• PDF ingestion is tested only via the Markdown path. pdf.py supports PDFs via pdfplumber, but the test suite covers Markdown only. Committing a binary PDF would bloat the repo. To verify manually: python -c "from uwazi.pdf import ingest_pdf; print(len(ingest_pdf('/path/to/real.pdf')))".

• The external mcp-server-fetch is only tested manually. The test suite verifies the fallback path (server not available → graceful degradation). The happy path (real URL fetch) requires a running subprocess.

• The /api/debug endpoint leaks env var names + safe values. Disable in production by deleting apps/web/app/api/debug/route.ts or guarding behind process.env.NODE_ENV !== 'production'.

• No real LLM API key set in the deployed demo. The current Vercel deployment uses STUB mode (no OPENAI_API_KEY) so every bid scores 0.0 — the workflow runs end-to-end but scores aren't differentiated. Set a real ModelScope inference token to see non-zero scores.

• No production auth. The deployment uses OFFICER_PRINCIPAL_ID=officer-demo. In production, this should come from OIDC (Keycloak) — the code is structured to accept it, but not wired up.

• No multi-tenant isolation. Single-tenant per deployment. A procurement office runs their own instance.

Future improvements

Project structure

uwazi/
├── README.md                  ← you are here
├── ARCHITECTURE.md            ← one-page architectural contract 
├── EVALS.md                   ← 42 tests + 1 known unfixed failure
├── DEMO_SCRIPT.md             ← 20-minute live review walkthrough
├── run-demo.sh                ← one-command demo
├── pyproject.toml
├── .env.example
├── docs/
│   ├── architecture.png       ← the architecture diagram shown above
│   └── architecture-deep-dive.md  ← the full ADR + schema contract
├── src/uwazi/
│   ├── config.py              ← env-driven settings
│   ├── models.py              ← Pydantic domain models
│   ├── db.py                  ← dual-backend (SQLite/Postgres) schema + trigger
│   ├── pdf.py                 ← PDF + Markdown ingestion, paragraph-level citations
│   ├── citation.py            ← 5-check citation validator (fails closed)
│   ├── gateway.py             ← provider-agnostic LLM gateway (STUB mode + real)
│   ├── prompts.py             ← every system + user prompt in one module
│   ├── agents.py              ← ExtractorAgent, BidAnalyzerAgent, ScorerAgent, RiskAgent
│   ├── orchestrator.py        ← LangGraph StateGraph (5 nodes, 1 conditional edge)
│   ├── external_mcp.py        ← integration with official mcp-server-fetch
│   ├── mcp_server.py          ← FastMCP server: 10 tools
│   ├── api.py                 ← FastAPI review UI + lifespan auto-seed
│   └── cli.py                 ← CLI driver
├── apps/web/                  ← Next.js 16 frontend (Vercel-deployed)
│   ├── app/                   ← App Router pages: /, /tenders, /notices, /audit
│   ├── lib/api.ts             ← typed API client (reads UWAZI_API_URL binding)
│   └── public/                ← logo, brand, favicon SVGs
├── samples/
│   ├── tender-makueni-water.md      ← synthetic tender (real-shape)
│   ├── tender-makueni-water.ocds.json ← same tender in OCDS (Open Contracting Data Standard)
│   ├── bid-aquaforce.md             ← clean bid
│   ├── bid-hydrotech.md             ← missing mandatory ISO 9001 (RiskAgent flag)
│   └── bid-sahara.md                ← anomalous-low financial (RiskAgent flag)
├── scripts/
│   ├── seed.py                ← seeds the sample tender + 3 bids
│   └── demo-video-script.md   ← 3-minute unedited video script
└── tests/
    ├── test_citation.py
    ├── test_pdf.py
    ├── test_human_in_the_loop.py
    └── test_mcp_tools.py

License

MIT. See LICENSE.

AI recommends. The procurement officer decides.