{
  "markdown": "<!-- mcp-name: io.github.vassiliylakhonin/agenda-intelligence-md -->\n\n# Agenda Intelligence MD\n\n[![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)\n\n**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)**.\n\n---\n\n## Core concepts\n\nAgenda Intelligence MD is a deterministic evidence-packet linter for claim-backed AI output.\n\nGive 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.\n\nIt reports **packet completeness**, not whether a claim is true:\n\n- not a factuality verifier;\n- no autonomous live source retrieval;\n- no authorization, approval, or compliance decision;\n- human review is required for every result.\n\n---\n\n## First run\n\nRun the canonical synthetic packet from a source checkout:\n\n```bash\ngit clone https://github.com/vassiliylakhonin/agenda-intelligence-md\ncd agenda-intelligence-md\npython -m venv .venv\n.venv/bin/python -m pip install -e .\n.venv/bin/agenda-intelligence check examples/evidence-packet/request.json\n```\n\nExpected shape:\n\n```text\npacket_status=packet_complete claims=2 sources=1 factuality=not_assessed\n  c1: packet_complete (lexical_support=supported, coverage=1.0)\n  c2: packet_complete (lexical_support=supported, coverage=1.0)\n```\n\nUse JSON for an agent loop or CI pipeline:\n\n```bash\n.venv/bin/agenda-intelligence check examples/evidence-packet/request.json --format json\n.venv/bin/agenda-intelligence check examples/evidence-packet/request.json --strict\n```\n\n`--strict` exits non-zero unless every claim is `packet_complete`.\n\nFind where a claim could be supported, before deciding what it cites:\n\n```bash\n.venv/bin/agenda-intelligence discover examples/evidence-review/manifest.json\n```\n\n`discover` derives literal patterns from each claim — figures and quoted spans\nfirst, then content terms, rarest first — and matches every one against every\nsource, reporting the line that matched. Nothing is sampled and no model is\ncalled, so it behaves the same on 40 sources and on 4,000. It names the sources\na claim's own figures reach but it does not cite, and the ones it cites where\nnot one pattern occurs. Candidates are places to look: nothing here verifies a\nclaim, and a source that supports one in different words does not appear at all.\n\nReview local source files without copying their full text into JSON:\n\n```bash\n.venv/bin/agenda-intelligence review examples/evidence-review/manifest.json \\\n  --out evidence-review.md --strict\n```\n\nThe manifest keeps claims explicit and points to local UTF-8, Markdown, DOCX,\nor PDF sources. Paths are resolved inside the manifest directory. DOCX support\nuses the Python standard library; PDF extraction requires\n`pip install -e \".[documents]\"`. The command makes no network or model call and\ndoes not include source text in its JSON or Markdown result. See\n[`docs/evidence-review.md`](docs/evidence-review.md).\n\nInstall the pinned release without cloning the source and check your own packet:\n\n```text\npip install \"agenda-intelligence-md==1.8.0\"\nagenda-intelligence check /path/to/evidence-packet.json --strict\n```\n\nGenerate an interactive standalone HTML reviewer report from local documents:\n\n```bash\n.venv/bin/agenda-intelligence review examples/evidence-review/manifest.json --format html\n```\n\n---\n\n## The evidence-packet contract\n\nThe request has two required collections:\n\n- `claims`: a claim ID, claim text, declared `source_ids`, and optional verbatim quotes;\n- `sources`: a source ID and the text supplied by the caller.\n\nRequest schema: [`schemas/v1/evidence-packet-request.schema.json`](schemas/v1/evidence-packet-request.schema.json)\n\nResponse schema: [`schemas/v1/evidence-packet-response.schema.json`](schemas/v1/evidence-packet-response.schema.json)\n\nRunnable example: [`examples/evidence-packet/request.json`](examples/evidence-packet/request.json)\n\nThe response has three packet statuses:\n\n| Status | Meaning |\n|---|---|\n| `packet_complete` | References resolve and the named source text has strong lexical overlap with the claim. |\n| `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. |\n| `packet_incomplete` | A source is missing, a quote is absent, or the claim has no source reference. |\n\n`factuality_status` is always `not_assessed`. A complete packet can still rely on a wrong, stale, biased, or irrelevant source.\n\n### What term overlap can and cannot see\n\nLexical support is the share of a claim's content terms that appear in the source it names. That ratio is blind to two things, so both are handled separately.\n\n**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.\n\n**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.\n\n**Unicode text is tokenized, but language understanding is not claimed.**\nCyrillic and Arabic words are no longer discarded, and common English,\nRussian, and Arabic negation cues are checked. The deterministic check still\ndoes not resolve morphology, translation, cross-language support, paraphrases,\nor semantic roles. Those remain model or reviewer tasks.\n\n---\n\n## Agent Guardrail & Self-Correction Loop\n\nValidate packets and automatically run agent self-correction feedback loops in LangChain, LlamaIndex, CrewAI, DSPy, or vanilla LLM loops:\n\n```python\nfrom agenda_intelligence.integrations import EvidencePacketGuardrail\n\nguardrail = EvidencePacketGuardrail(strict=True, max_repair_attempts=2)\n\n# Direct check\nresult = guardrail.check(packet_json)\nif not guardrail.is_complete(result):\n    repair_prompt = guardrail.get_repair_prompt(packet_json, result)\n    # Provide repair_prompt back to LLM to revise output\n\n# Automated retry loop with custom LLM generation function\nfinal_packet, success, repair_history = guardrail.validate_or_repair(\n    packet_json,\n    llm_repair_fn=lambda prompt: my_llm_chain.invoke({\"prompt\": prompt}),\n)\n```\n\n---\n\n## Concurrency & A2A Demos\n\nThe repository includes runnable end-to-end demonstrations of the agent-first architecture:\n\n- **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.\n- **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.\n- **Profile scaffolder ([`scripts/agent-factory.py`](scripts/agent-factory.py))**: Creates starter files for a proposed vertical profile. Generated files are inactive until schemas, implementation, tests, and review are added.\n\n---\n\n## GitHub Action CI Integration\n\nAdd deterministic evidence linting to your repository CI workflow (`.github/workflows/evidence-lint.yml`):\n\n```yaml\nname: Evidence Lint\non: [push, pull_request]\n\njobs:\n  lint-evidence:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Validate evidence packet\n        uses: vassiliylakhonin/agenda-intelligence-md@main\n        with:\n          path: 'evidence/packet.json'\n          command: 'check'\n          strict: 'true'\n```\n\n---\n\n## Python API\n\n```python\nimport json\nfrom pathlib import Path\n\nfrom agenda_intelligence.services import check_evidence_packet, build_repair_prompt\n\npacket = json.loads(Path(\"examples/evidence-packet/request.json\").read_text())\nresult = check_evidence_packet(packet)\nprint(result[\"response\"][\"packet_status\"])\n\n# Generate actionable markdown repair instructions for an agent\nif result[\"response\"][\"packet_status\"] != \"packet_complete\":\n    prompt = build_repair_prompt(packet, result[\"response\"])\n    print(prompt)\n```\n\nThe service layer is stateless. It does not persist packet contents or fetch missing sources.\n\n---\n\n## What this is\n\n- A small JSON contract for claim-backed AI output.\n- A deterministic preflight before human review.\n- A CLI and Python service suitable for local and CI use.\n- A local-file review adapter that returns a reviewer-facing Markdown or JSON result.\n- An inspectable base for domain-specific compatibility profiles.\n\n## What this is not\n\n- A general LLM evaluation platform.\n- A GRC, vendor-management, or document-storage system.\n- An agent authorization or policy-enforcement layer.\n- Legal, compliance, sanctions, financial, investment, insurance, or trading advice.\n- Proof that a source or claim is factually correct.\n\n---\n\n## Why a repo full of markdown?\n\nThe repository predates the evidence-packet focus and also packages agent reasoning instructions. Files under `skills/` are executable instructions for compatible agent runtimes, not ordinary prose documentation. They remain available for compatibility, but they are not the primary product interface.\n\n---\n\n## MCP\n\nThe packaged MCP server exposes the same evidence-packet preflight to agent clients:\n\n```json\n{\n  \"mcpServers\": {\n    \"agenda-intelligence\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"agenda-intelligence-md\", \"agenda-intelligence-mcp\"]\n    }\n  }\n}\n```\n\nRun a focused stdio example against an editable install:\n\n```bash\n.venv/bin/python examples/evidence-packet/mcp_client.py \\\n  --command \".venv/bin/agenda-intelligence-mcp\"\n```\n\nThe example initializes the MCP server, calls `check_evidence_packet` with the\nsynthetic packet, and prints only the review summary. See\n[`examples/evidence-packet/mcp_client.py`](examples/evidence-packet/mcp_client.py)\nand [`MCP.md`](MCP.md).\n\nBefore using the result for an irreversible or high-stakes action, record the\ngoal, supplied evidence, suspected unreliable evidence, assumptions, intended\naction, and stop/escalation conditions. The tool checks packet structure, not\nwhether a claim is true or an action is authorized.\n\nExisting MCP tools such as `audit_claims`, `verify_quotes`, `grounded_check`,\nand `verify_claims` remain compatible; no tool was removed or renamed.\n\n`pre_action_check` adds a stateless action boundary on top of the existing\nclaim audit. It returns `continue`, `request_evidence`, `require_approval`, or\n`stop` from caller-supplied evidence, risk, policy-check results, and an\noptional external approval reference. The caller still authenticates the\nactor, stores approvals, enforces the result, and performs the action. The\nrequest and response contracts are\n[`pre-action-check-request.schema.json`](schemas/v1/pre-action-check-request.schema.json)\nand\n[`pre-action-check-response.schema.json`](schemas/v1/pre-action-check-response.schema.json).\nTwenty illustrative replay cases are in\n[`examples/pre-action-check/replay-cases.json`](examples/pre-action-check/replay-cases.json).\n\nTwo authoring tools, `create_brief` and `append_evidence`, let an agent assemble a brief or an evidence pack step by step inside the contract instead of hand-building JSON and validating it afterwards. Both are deterministic and stateless: they validate on every call and return the document to the caller. They do not write files, retrieve sources, draft prose, or assess factual truth, and `append_evidence` never infers a `supported` claim status on its own.\n\nClaude Code plugin installation also remains available:\n\n```text\n/plugin marketplace add vassiliylakhonin/agenda-intelligence-md\n/plugin install agenda-intelligence@agenda-intelligence\n```\n\n---\n\n## Compatibility profiles and adapters\n\nThe strategic-intelligence shell, HTTP API, A2A adapter, Cloudflare Workers, and five domain profiles remain in the repository. They demonstrate how the same service layer can be wrapped for different transports and domains. They represent active prototypes and technical wedges for vertical domains.\n\n| Compatibility surface | Reference |\n|---|---|\n| Strategic agenda analysis | [`Agenda-Intelligence.md`](Agenda-Intelligence.md) |\n| HTTP API | [`docs/deployment/http-api.md`](docs/deployment/http-api.md) |\n| A2A adapter | [`docs/deployment/a2a-adapter.md`](docs/deployment/a2a-adapter.md) |\n| Middle Corridor example | [`docs/use-cases/kazakhstan-middle-corridor.md`](docs/use-cases/kazakhstan-middle-corridor.md) |\n| CIS secondary-sanctions example | [`docs/use-cases/cis-secondary-sanctions.md`](docs/use-cases/cis-secondary-sanctions.md) |\n| Agentic interaction example | [`docs/use-cases/agentic-interaction-trust.md`](docs/use-cases/agentic-interaction-trust.md) |\n| Gulf maritime example | [`docs/use-cases/gulf-maritime-exposure.md`](docs/use-cases/gulf-maritime-exposure.md) |\n| Kazakhstan market-entry example | [`docs/use-cases/kazakhstan-market-entry-readiness.md`](docs/use-cases/kazakhstan-market-entry-readiness.md) |\n| Live A2A demo pack | [`docs/agenstry/demo-pack.md`](docs/agenstry/demo-pack.md) |\n\nThe compatibility profiles are evidence-routing examples only. They do not provide legal, compliance, sanctions, financial, investment, insurance, or trading advice. Human review is required before any commercial action.\n\n---\n\n## Verification Contract\n\nThe repository keeps three checks separate:\n\n1. `check` reports packet completeness and lexical-support diagnostics.\n2. `grounded-check` performs the older claim-to-corpus lexical diagnostic.\n3. `verify-claims` applies declared freshness, authority, independence, jurisdiction, and identifier rules to caller-supplied evidence.\n\nNone discovers the right sources for the caller. `verified` in the bounded Claim Verdict contract means the supplied evidence meets that declared contract; it is not absolute truth.\n\n---\n\n## Schemas\n\nCanonical schemas live under [`schemas/v1/`](schemas/v1/). Packaged copies under `src/agenda_intelligence/data/schemas/v1/` must remain byte-equivalent; CI checks this invariant.\n\nStart with:\n\n- [`evidence-packet-request.schema.json`](schemas/v1/evidence-packet-request.schema.json)\n- [`evidence-packet-response.schema.json`](schemas/v1/evidence-packet-response.schema.json)\n- [`evidence-review-request.schema.json`](schemas/v1/evidence-review-request.schema.json)\n- [`evidence-audit.schema.json`](schemas/v1/evidence-audit.schema.json)\n- [`claim-verification-request.schema.json`](schemas/v1/claim-verification-request.schema.json)\n\nThe full registry is in [`agent-manifest.json`](agent-manifest.json).\n\n---\n\n## Before / after and benchmarks\n\nThe older agenda-analysis evaluation surface remains available for regression and compatibility work:\n\n- [`examples/before-after/eu-ai-act.md`](examples/before-after/eu-ai-act.md)\n- [`examples/before-after/red-sea-shipping.md`](examples/before-after/red-sea-shipping.md)\n- [`examples/before-after/sanctions-routing.md`](examples/before-after/sanctions-routing.md)\n- [`examples/source-backed/eu-ai-act.md`](examples/source-backed/eu-ai-act.md)\n\nThese are evaluation fixtures, not customer evidence or production benchmarks.\n\n---\n\n## AnalysisBank\n\n[`analysis-bank/`](analysis-bank/) contains compatibility fixtures for reasoning-memory retrieval and failure-pattern regression. It is not part of the primary evidence-packet workflow.\n\n---\n\n## Status\n\n| Surface | Status |\n|---|---|\n| Evidence-packet request/response schemas | Implemented |\n| `check_evidence_packet` Python service | Implemented |\n| `agenda-intelligence check` packet auto-detection | Implemented |\n| `agenda-intelligence review` local-file workflow | Implemented for UTF-8, Markdown, DOCX, and optional PDF input |\n| `agenda-intelligence review --format html` | Implemented (Generative UI) |\n| `check_evidence_packet` MCP tool | Implemented |\n| AI Fleet (Vertical Workers) | Active (10 profiles deployed) |\n| Live Source Retrieval | Optional per profile; currently unconfigured in the hosted fleet |\n\nCurrent classification: `Ecosystem Expansion & R&D`.\n\n---\n\n## Documentation\n\n| Topic | File |\n|---|---|\n| Pitch Deck (12 Slides) | [`docs/pitch/PITCH_DECK.md`](docs/pitch/PITCH_DECK.md) |\n| Case Studies | [`docs/pitch/CASE_STUDIES.md`](docs/pitch/CASE_STUDIES.md) |\n| Unit Economics | [`docs/pitch/UNIT_ECONOMICS.md`](docs/pitch/UNIT_ECONOMICS.md) |\n| Adoption | [`ADOPTION.md`](ADOPTION.md) |\n| Quickstart | [`docs/quickstart.md`](docs/quickstart.md) |\n| Evidence audit | [`docs/evidence-audit.md`](docs/evidence-audit.md) |\n| Local evidence review | [`docs/evidence-review.md`](docs/evidence-review.md) |\n| Factuality boundary | [`docs/factual-verification.md`](docs/factual-verification.md) |\n| Evaluation | [`docs/evaluation.md`](docs/evaluation.md) |\n| Source policy | [`SOURCE_POLICY.md`](SOURCE_POLICY.md) |\n| Security | [`SECURITY.md`](SECURITY.md) |\n| Threat model | [`docs/threat-model.md`](docs/threat-model.md) |\n| Roadmap | [`ROADMAP.md`](ROADMAP.md) |\n\n---\n\n## Repository layout\n\n```text\nschemas/v1/                    public JSON contracts\nsrc/agenda_intelligence/       Python service and transport adapters\nexamples/evidence-packet/      canonical packet example\ntests/                         contract and regression tests\nskills/                        compatibility agent instructions\ndeploy/cloudflare-worker/      compatibility Worker implementation\ndocs/                          reference and compatibility documentation\n```\n\n---\n\n## Development\n\n```bash\npip install -e \".[dev]\"\nmake ci\nmake verification-report\n```\n\n`make verify-local` also runs the compatibility Cloudflare Worker tests.\n`make verification-report` runs both verification surfaces and writes\n`.verification/results.json`: a deterministic, machine-readable record of the\nchecks and hashed contracts. It uses no paid APIs and deliberately makes no\nclaim about factual truth, live deployment health, adoption, or market value.\n\n---\n\n## Roadmap\n\nThe current phase focuses on **Product-Led Growth & Ecosystem Expansion**. \nWe are rapidly iterating on Generative UI for interactive evidence dashboards, deploying new vertical AI workers for adjacent domains (e.g., ESG, supply chain), and registering capabilities with agent catalogs (Agenstry).\n\nSee [`ROADMAP.md`](ROADMAP.md) for the active expansion initiatives.\n\n---\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 19556,
  "sha": "f83e523c837f7aca9b9ed64c80559d5189d2e4afc9b166b8bbe5ad8412db5142",
  "repo_slug": "vassiliylakhonin/agenda-intelligence-md",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vassiliylakhonin_agenda_intell_fc6d771f/readme"
}