Metadata-Version: 2.4
Name: patent-evidence-dkg
Version: 0.2.0
Summary: Source-grounded research agents with OriginTrail DKG working memory
License-Expression: AGPL-3.0-only
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn<1,>=0.30
Requires-Dist: pymupdf<2,>=1.24
Requires-Dist: httpx<1,>=0.27
Requires-Dist: cryptography>=43
Requires-Dist: mcp<3,>=2.2
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: psutil<8,>=6
Requires-Dist: jsonschema<5,>=4
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: jsonschema>=4; extra == "test"
Provides-Extra: ocr
Requires-Dist: rapidocr-onnxruntime==1.4.4; extra == "ocr"
Dynamic: license-file

# Patent Evidence · 0.2.0

A research desk where an agent can leave, another can arrive with no research history, and the investigation can continue from source-checked DKG memory.

The demonstration follows **Fable Fern Labs**, a fictional company developing **WickRail**, a fictional self-watering planter. Its specifications are invented. Three unrelated, real US patent publications provide the research sources. No client material is included in the release tree.

## What works

- **A fresh agent resumes through DKG.** A source-only ZIP transfers originals and project identity, with zero findings. A separately registered agent retrieves SWM, re-extracts those originals, checks citation hashes and quotations, and records its own new finding. The recorded MCP run recovered 16 findings; the later three-trial retrieval benchmark recovered 17 with 61 checked citations per trial.
- **Research survives source changes.** An engineering update flagged ten dependent findings. Another real agent revisited two and saved its reasoning; eight remained explicitly unresolved. An open-question queue supports bounded follow-up research. Rechecks do not invent human approval.
- **Evidence can be prepared for a proceeding.** A signed, selected-evidence candidate separates source content, attributed historical publication dates, legal interpretation and unresolved checks. An offline oracle consumer verifies the package before returning cited answers. No VM publication, funded wallet or TRAC spend occurs.
- **Other agents can use it.** Fifteen project-scoped MCP tools expose search, cited findings, recovery, source changes, questions, reviews and promotion previews. An actual Codex MCP client was exercised. Other MCP clients have configuration examples, not claimed execution tests.

The application checks source and quotation integrity. It does not establish legal correctness, exhaustive FTO coverage, patent validity or current legal status. Recording something today does not prove that it was publicly available years ago.

## Start from the source release

Requirements: Python 3.11+, Node.js 22+ and an existing Codex sign-in for live built-in research. Manual evidence work and MCP do not require Codex. Tested with Python 3.12, Node 24.11 and DKG 10.0.18 on Windows.

```sh
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[test]"
npm install --prefix .runtime --ignore-scripts @origintrail-official/dkg@10.0.18
npm rebuild --prefix .runtime better-sqlite3
python scripts/start_isolated_dkg.py --cli .runtime/node_modules/@origintrail-official/dkg/dist/cli.js --home .node --port 19421
python scripts/register_dkg_agent.py --home .node
python scripts/bootstrap_demo.py --state .state
patent-evidence --state .state --dkg-home .node serve --port 18767
```

Open **http://localhost:18767**. The bootstrap prints the new project ID and initial question. Select the company brief and concept v1 for the first run; introduce clarification v2 for the second. The UI preserves original citations and records objections.

This uses a real DKG node and public WM/SWM HTTP calls, on a mock-chain profile with no configured peers or relays. It demonstrates durable **same-node** collaboration, not remote-peer replication. No TRAC or gas is needed. Read [SECURITY.md](SECURITY.md): upstream advisories remain unresolved and the peer listener is not an air gap.

## Connect an independent agent

```sh
patent-evidence --state .state source-kit PROJECT_ID sources.zip
patent-evidence --state .fresh import-sources sources.zip
patent-evidence --state .fresh --dkg-home .node --project PROJECT_ID connect-agent --name "Independent researcher" --profile .reader --output mcp-config.json
patent-evidence --state .fresh --dkg-home .node --agent-profile .reader --project PROJECT_ID doctor
```

Give the generated configuration to an MCP client. It uses a separately registered identity and limits the connection to one project. Keep state, node homes, profiles and configuration files private. Start with `get_research_context`: the fresh workspace has no findings. Call `recover_shared_research`, inspect `get_passage`, then `record_finding` and `share_finding`. Imported human-review labels are not trusted.

For a bounded Codex MCP run with an existing sign-in:

```sh
python scripts/run_codex_mcp.py --config mcp-config.json --prompt task.txt --output agent-run
```

This runner uses automatic approval review, enables only the configured MCP surface, and preserves the event log and final handoff. It changes no global settings. The three built-in roles share one integration identity; they are not independent cryptographic witnesses.

Installers may supply `DKG_API_URL`, `DKG_AUTH_TOKEN`, `PATENT_EVIDENCE_STATE` and `PATENT_EVIDENCE_PROJECT` to `patent-evidence mcp`. The endpoint must be loopback and the scoped identity is checked. Environment credentials alone do not establish isolation; private sharing requires the explicit local-node profile. See [client configuration](registry/CLIENTS.md).

## Continue research and prepare evidence

**Research notebook** preserves questions, registers old/new source pairs and shows dependent findings. It follows direct citations and explicit transitive dependencies; unrecorded assumptions remain outside its coverage.

```sh
patent-evidence --state .state --dkg-home .node research-next PROJECT_ID --max-runs 1
```

The next eligible question is selected automatically. Completion does not close it: a cited answer and reason are required. Runs are bounded to one, two or three passes and stop when a pass produces no supported finding.

**Evidence package** prepares a local candidate for review or a fictional proceeding. The ZIP includes selected findings, source snapshots, memory lineage, review issues and an Ed25519 signature.

```sh
patent-evidence verify-candidate candidate.zip
patent-evidence oracle candidate.zip "What is known about the moisture dial?"
# If the signer's fingerprint is independently authenticated:
patent-evidence verify-candidate candidate.zip --trusted-key FINGERPRINT
```

The recorded opposition candidate includes a separately cited B2 front-page publication date. It remains an attributed assertion requiring review. A proceeding never authorizes disclosure. All candidates report publication false and a null on-chain UAL, anchor date and trust tier. [The evidence design](VERIFIABLE-EVIDENCE.md) describes a future authorized VM path.

## Private work, tests and release status

```sh
patent-evidence --state .private create-project "My research"
patent-evidence --state .private ingest PROJECT_ID ./working-copy
python -m pytest
# Optional node tests: set DKG_TEST_HOME to the isolated development node home.
```

PDF, Word, Excel, UTF-8 text and patent-publication HTML are supported. Use a working copy. Imports are private by default. Public exports/source kits refuse private projects. This is a single-user loopback app without encryption at rest. Optional OCR creates a separate derivative with explicitly labelled machine transcription: install `.[ocr]` and see `scripts/ocr_scans.py --help`.

This is a **local release candidate**, not a submitted or awarded bounty entry. Public repository/package release, demo hosting and a maintainer's six-month commitment remain release steps. Proposed code license: AGPL-3.0-only, consistent with its PDF dependency. Publications retain their own legal status.

[Design](DESIGN.md) · [Validation](TESTING.md) · [Demonstration](demo-fable-fern/WALKTHROUGH.md) · [Dependency notices](THIRD-PARTY.md) · [Release checklist](submission/RELEASE-CHECKLIST.md)

