agenda-intelligence-md

<!-- mcp-name: io.github.vassiliylakhonin/agenda-intelligence-md -->

# Agenda Intelligence MD

[![PyPI version](https://img.shields.io/pypi/v/agenda-intelligence-md?style=flat-square)](https://pypi.org/project/agenda-intelligence-md/) [![CI](https://github.com/vassiliylakhonin/agenda-intelligence-md/actions/workflows/ci.yml/badge.svg)](https://github.com/vassiliylakhonin/agenda-intelligence-md/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Agenda Intelligence MD** is a deterministic evidence-packet linter and compliance orchestration engine for claim-backed AI output. It provides verifiable trust boundaries, guardrail enforcement, and evidence-readiness triage across **A2A (Agent-to-Agent)**, **MCP (Model Context Protocol)**, **CLI / Python API**, and **Serverless Edge Workers (Cloudflare)**.

---

## Core concepts

Agenda Intelligence MD is a deterministic evidence-packet linter for claim-backed AI output.

Give it claims, the source IDs each claim relies on, optional quotations, and the supplied source text. It returns broken references, quote mismatches, lexical-support gaps, unmatched numbers, claims that negate the source they cite, and the next reviewer actions.

It reports **packet completeness**, not whether a claim is true:

- not a factuality verifier;
- no autonomous live source retrieval;
- no authorization, approval, or compliance decision;
- human review is required for every result.

---

## First run

Run the canonical synthetic packet from a source checkout:

```bash
git clone https://github.com/vassiliylakhonin/agenda-intelligence-md
cd agenda-intelligence-md
python -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/agenda-intelligence check examples/evidence-packet/request.json
```

Expected shape:

```text
packet_status=packet_complete claims=2 sources=1 factuality=not_assessed
  c1: packet_complete (lexical_support=supported, coverage=1.0)
  c2: packet_complete (lexical_support=supported, coverage=1.0)
```

Use JSON for an agent loop or CI pipeline:

```bash
.venv/bin/agenda-intelligence check examples/evidence-packet/request.json --format json
.venv/bin/agenda-intelligence check examples/evidence-packet/request.json --strict
```

`--strict` exits non-zero unless every claim is `packet_complete`.

Find where a claim could be supported, before deciding what it cites:

```bash
.venv/bin/agenda-intelligence discover examples/evidence-review/manifest.json
```

`discover` derives literal patterns from each claim — figures and quoted spans
first, then content terms, rarest first — and matches every one against every
source, reporting the line that matched. Nothing is sampled and no model is
called, so it behaves the same on 40 sources and on 4,000. It names the sources
a claim's own figures reach but it does not cite, and the ones it cites where
not one pattern occurs. Candidates are places to look: nothing here verifies a
claim, and a source that supports one in different words does not appear at all.

Review local source files without copying their full text into JSON:

```bash
.venv/bin/agenda-intelligence review examples/evidence-review/manifest.json \
  --out evidence-review.md --strict
```

The manifest keeps claims explicit and points to local UTF-8, Markdown, DOCX,
or PDF sources. Paths are resolved inside the manifest directory. DOCX support
uses the Python standard library; PDF extraction requires
`pip install -e ".[documents]"`. The command makes no network or model call and
does not include source text in its JSON or Markdown result. See
[`docs/evidence-review.md`](docs/evidence-review.md).

Install the pinned release without cloning the source and check your own packet:

```text
pip install "agenda-intelligence-md==1.9.0"
agenda-intelligence check /path/to/evidence-packet.json --strict
```

Generate an interactive standalone HTML reviewer report from local documents:

```bash
.venv/bin/agenda-intelligence review examples/evidence-review/manifest.json --format html
```

---

## The evidence-packet contract

The request has two required collections:

- `claims`: a claim ID, claim text, declared `source_ids`, and optional verbatim quotes;
- `sources`: a source ID and the text supplied by the caller.

Request schema: [`schemas/v1/evidence-packet-request.schema.json`](schemas/v1/evidence-packet-request.schema.json)

Response schema: [`schemas/v1/evidence-packet-response.schema.json`](schemas/v1/evidence-packet-response.schema.json)

Runnable example: [`examples/evidence-packet/request.json`](examples/evidence-packet/request.json)

The response has three packet statuses:

| Status | Meaning |
|---|---|
| `packet_complete` | References resolve and the named source text has strong lexical overlap with the claim. |
| `source_review_required` | References resolve, but lexical support is weak, a numeric value is not present, or the claim and its closest source sentence disagree on negation. |
| `packet_incomplete` | A source is missing, a quote is absent, or the claim has no source reference. |

`factuality_status` is always `not_assessed`. A complete packet can still rely on a wrong, stale, biased, or irrelevant source.

Numeric support is format-aware but deliberately conservative. Equivalent scaled values, percentages, and common date
forms are compared canonically (`$10M` ↔ `10,000,000 USD`, `62%` ↔ `62 percent`, and `12 May 2024` ↔ `2024-05-12`).
Currency is part of the comparison: `10M USD` does not support `10M EUR`, and the linter performs no currency conversion
or approximate-value inference.

Quote presence remains strict after Unicode, typography, whitespace, ellipsis, soft-hyphen, and PDF line-break
hyphenation normalization. When an otherwise absent quote has a typo-level candidate at 95% similarity or higher,
the quote check may include a bounded `near_miss` diff for the reviewer. It still reports `status: absent` and keeps the
packet incomplete. Candidates whose numeric facts or negation cues differ are not presented as harmless near misses.

### What weighted term overlap can and cannot see

Lexical support is an IDF-weighted share of a claim's content terms that appear in the source it names. Terms that occur
throughout the supplied corpus carry less weight than rare entities, while a single-document packet preserves the original
plain-overlap scale. Corpus text, sentences, numeric facts, and term sets are indexed once per check run and reused across
claims.

**Negation is checked.** `not` and `no` are stopwords and never reach the ratio, so "the board approved it" and "the board did not approve it" score the same against the same source. Where a claim and its closest sentence in the cited source disagree on negation or denial, the claim is downgraded to `weak` and carries `lexical_support_polarity_mismatch`. Polarity is read at sentence scope: a negation elsewhere in the same document does not flag an unrelated claim.

**Reversed roles are not checked, and are not claimed to be.** "A approved a facility for B" and "B approved a facility for A" contain the same terms and both score `supported`. Deciding who did what to whom is not something term overlap can do, and no heuristic here pretends otherwise. A reviewer still has to read the sentence. The limit is pinned by a test (`test_polarity_check_does_not_claim_to_catch_reversed_roles`) so it stays visible.

**Unicode text is tokenized, but language understanding is not claimed.**
Cyrillic and Arabic words are no longer discarded, common Russian and Arabic
function words are excluded from lexical coverage, and common English, Russian,
and Arabic negation cues are checked. A conservative deterministic fold covers
common English plurals/verb suffixes and Russian noun/adjective inflections. It
is not a full morphological analyzer and does not resolve translation,
cross-language support, paraphrases, or semantic roles. Those remain model or
reviewer tasks.

---

## Agent Guardrail & Self-Correction Loop

Validate packets and automatically run agent self-correction feedback loops in LangChain, LlamaIndex, CrewAI, DSPy, or vanilla LLM loops:

```python
from agenda_intelligence.integrations import EvidenceClaim, EvidencePacket, EvidencePacketGuardrail, EvidenceSource

guardrail = EvidencePacketGuardrail(strict=True, max_repair_attempts=2)

# Optional zero-dependency typed input; plain dictionaries remain supported.
packet = EvidencePacket(
    claims=(EvidenceClaim("c1", "The board approved the budget.", ("s1",)),),
    sources=(EvidenceSource("s1", "The board approved the budget after review."),),
)

# Direct check
result = guardrail.check(packet)
if not guardrail.is_complete(result):
    repair_prompt = guardrail.get_repair_prompt(packet_json, result)
    # Provide repair_prompt back to LLM to revise output

# Automated retry loop with custom LLM generation function
final_packet, success, repair_history = guardrail.validate_or_repair(
    packet_json,
    llm_repair_fn=lambda prompt: my_llm_chain.invoke({"prompt": prompt}),
)

# Event-loop pipelines can await check_async(...) or validate_or_repair_async(...).
# LangGraph can use the dependency-free async node returned by:
node = guardrail.as_langgraph_node(packet_key="evidence_packet", result_key="evidence_check")
```

---

## Concurrency & A2A Demos

The repository includes runnable end-to-end demonstrations of the agent-first architecture:

- **Bounded concurrency example ([`examples/infinite-swarm-batch.py`](examples/infinite-swarm-batch.py))**: Sends 250 synthetic requests and reports transport latency and actual task states. It is a load demonstration, not a capacity benchmark or comparison with staff.
- **A2A step-up simulation ([`examples/agent-to-agent-negotiation.py`](examples/agent-to-agent-negotiation.py))**: Demonstrates a synthetic request being stopped until operator-authorization evidence is supplied. No real transaction is authorized.
- **Profile scaffolder ([`scripts/agent-factory.py`](scripts/a