EvidenceWiki

Answers you can audit. EvidenceWiki creates persistent research workspaces where agents investigate questions and deterministic scripts enforce provenance, lifecycle state, and export validation. A validated research outcome is either a cited, auditable answer or a structured request for missing evidence.

Quick start · Documentation · Worked example · PyPI · Contributing

How This Project Was Built

EvidenceWiki was planned, written, and tested entirely with AI coding agents. Most of the work was done with OpenAI Codex using GPT-5.5 and GPT-5.6, with Anthropic Claude also used for parts of the project. No code in this repository was manually authored by a human.

Why EvidenceWiki

• Traceable answers. Every citation resolves through a stable source ID to a normalized record and its provenance-tracked original.
• Evidence-aware failure. Configured coverage requirements block weakly supported answers and produce machine-readable source requests.
• Deterministic control. Scripts own critical question-lifecycle transitions, validation, and export; agents supply research judgment.
• Reusable workspaces. The starter, domain packs, agent skills, and orchestration protocol work across research domains and agent harnesses.

question → discover/acquire → inventory/normalize → answer/verify → export
                       ↘ missing evidence → structured source request

The workspace keeps original evidence in raw/, generated evidence records in sources/, and maintained research knowledge in wiki/. Source content is treated as data, never as agent instructions; see prompt-injection hardening.

Five-Minute Tour

These commands set up the workflow; research time varies with the question, providers, and agent runner. The examples use a POSIX-compatible shell; on Windows, create batch.yaml in an editor or adapt that one heredoc step for PowerShell. Python 3.10 or newer is required.

Install the package and create a provider-enabled scientific workspace:

python3 -m pip install evidence-wiki
evidence-wiki deploy \
  --target solid-state-batteries \
  --project-name solid-state-batteries \
  --project-description "Survey of solid-state battery electrolyte research" \
  --domain-pack general-science \
  --discovery-provider arxiv \
  --discovery-provider openalex \
  --acquisition-provider arxiv \
  --acquisition-provider openalex
cd solid-state-batteries

init and deploy invoke the same workspace initializer. The repeated provider flags explicitly authorize network-backed discovery and acquisition; a domain pack never enables providers by itself. arXiv needs no credential, while OpenAlex can use OPENALEX_API_KEY from the process environment. See workspace initialization, source discovery, and acquisition for the full contracts.

Add a question using the question API:

cat > batch.yaml <<'EOF'
schema_version: "1.0"
questions:
  - question: "Which solid electrolyte families report room-temperature ionic conductivity above 1 mS/cm?"
    id: electrolyte-conductivity
    priority: high
EOF
evidence-wiki questions add --target . --from-file batch.yaml

Codex CLI 0.138 or newer must already be installed for the managed Codex adapter. Check the environment before launching it:

evidence-wiki doctor --format json

Run the managed orchestrator:

evidence-wiki orchestrate run \
  --target . \
  --runner codex \
  --agent-id battery-demo

Use --runner claude for the managed Claude Code adapter. Then inspect the durable parent session and export the answer:

evidence-wiki orchestrate status --target . --format json
evidence-wiki export --target . --format json

The orchestrator can discover candidate sources, ask an agent to select them, acquire and normalize the selected evidence, reopen a blocked question, and verify the final artifacts. If allowed providers cannot satisfy the request, the session ends as blocked_on_sources instead of inventing an answer. The orchestration guide covers execution, recovery, and security boundaries.

Local-files-only alternative

Discovery and acquisition are optional. Omit provider flags, deliver reviewed files with provenance sidecars under the configured raw/ roots, then run:

python3 scripts/source_inventory.py --report
python3 scripts/normalize_sources.py --all

Inventory and normalization process only files already present. Continue with the research-run skill, or use the external protocol described below. The source-delivery contract defines provenance sidecars and atomic delivery.

Drive It With An Agent

EvidenceWiki supports agent harnesses at three levels:

• Managed adapters: Codex and Claude Code are the registered runners for package-owned run and resume execution.
• External protocol: OpenCode, Pi, Aider, Gemini CLI, and other harnesses can drive start, next, submit, and status from an operator-controlled host. They are not package-managed runners.
• Instruction compatibility: any worker can follow the workspace AGENTS.md, selected skill, and bounded work order. CLAUDE.md points Claude-style agents to the same contract.

Managed Codex execution requires Codex CLI 0.138 or newer. Managed Claude execution is unavailable on native Windows; use macOS, Linux, WSL2, a container, or the external protocol. If the required isolation boundary cannot be enforced, the host returns RUNNER_ISOLATION_UNAVAILABLE before starting a worker. The parent exclusively owns runs/orchestrations/; workers never write that tree or invoke the parent controller. Use resume for a retained session after a runner failure. See parent orchestration for isolation, leases, tamper recovery, and upgrade rules.

External protocol

A PM, planner, or custom host can drive the model-neutral protocol directly:

evidence-wiki orchestrate start --target PATH --agent-id parent-agent --format json
evidence-wiki orchestrate next --target PATH --orchestration-id ORCH_ID --format json
evidence-wiki orchestrate submit --target PATH --orchestration-id ORCH_ID \
  --action-id ACTION_ID --result-file result.json --format json
evidence-wiki orchestrate status --target PATH --orchestration-id ORCH_ID --format json

next is idempotent, and submit verifies workspace postconditions before advancing. External hosts must provide process isolation, single-driver coordination, and crash replay; see the orchestrator handoff contract. The packaged research-orchestrate playbook lives under orchestrator/skills/ and can be located without a source checkout:

evidence-wiki orchestrator-guide
evidence-wiki orchestrator-guide --print

For MCP clients, an optional stdio server exposes status, retrieval, question intake, answer export, and source-request listing:

evidence-wiki serve-mcp --target /path/to/workspace

See the MCP server contract for its tool list and read/append-only boundary.

Drive It From Python

A host that embeds EvidenceWiki — an ASGI service, a scheduler, a batch worker — can call the package in-process instead of spawning the CLI per operation:

from evidence_wiki import Workspace

with Workspace.open("/path/to/workspace") as ws:
    report = ws.coverage.evaluate("electrolyte-conductivity")

Twenty-six operations return the same documents the matching --format json commands print, and refuse with typed exceptions carrying the same stable error codes. Both doors render from one seam per operation, so they cannot disagree. Orchestration keeps a subprocess to the workspace's own deployed controller, which is version-matched to the session state it owns. The package ships no HTTP server; hosts build their own. See the library API for the full surface, the error families, thread-safety guarantees, and a worked embedding example.

Requirements and Diagnostics

Required:

• Python 3.10 or newer.
• PyYAML 6.0 or newer, ruamel.yaml 0.19.1 or newer within the 0.19 series, and pypdf 6.14 or newer within major version 6. All are installed with evidence-wiki; ruamel.yaml preserves live YAML comments and quoting during pack refresh, while the portable pypdf backend requires no separate PDF tool.

Optional capabilities include Codex CLI or Claude Code for managed runs, Git for snapshots, and the Poppler compatibility backend for explicitly configured pdftotext extraction. Platform installation is covered by workspace initialization; managed-runner sandbox requirements are covered by parent orchestration.

Check dependencies and optional capabilities from any directory:

evidence-wiki doctor --format json

An initialized workspace includes the same preflight:

python3 scripts/doctor.py --format json

Missing pypdf is a required failure. Missing Poppler is informational unless the workspace explicitly selects the Poppler compatibility backend.

Create and Maintain a Workspace

Create a generic workspace from explicit fields:

evidence-wiki init \
  --target ../my-research-workspace \
  --project-name my-research-workspace \
  --project-description "Research workspace for a specific topic" \
  --owner-goal "Build a source-grounded knowledge base for decisions"

Add --dry-run to preview without writing files. For minimal-preparation, agent-assisted setup, ask an agent to follow the research-init skill; it can prepare a reviewable workspace init profile.

After upgrading the package, preview and apply starter-managed script updates:

evidence-wiki upgrade --target ../my-research-workspace --dry-run
evidence-wiki upgrade --target ../my-research-workspace

Write-mode upgrade refreshes only starter-managed tooling, may update workspace-system.yml, uses .locks/, and conditionally appends one audit entry to log.md when it applies material changes. It preserves prior log history, research.yml, raw/, sources/, wiki/, index.md, and other user data. --dry-run writes nothing. Both modes refuse with UPGRADE_PENDING_ORDER while an orchestration session holds a pending work order or an active driver, naming the session and order: drain orchestration before upgrading. Optional skills and docs have additional conflict rules documented in workspace initialization.

Domain packs have a separate, explicit lifecycle. Preview and apply a new revision of the already-installed pack with:

evidence-wiki pack refresh \
  --target ../my-research-workspace \
  --path general-science \
  --dry-run
evidence-wiki pack refresh \
  --target ../my-research-workspace \
  --path general-science

An older workspace whose pack predates lifecycle state must first run evidence-wiki pack adopt --target ../my-research-workspace --dry-run, review the result, and repeat without --dry-run. Refresh never switches pack names, and an unresolved local/pack conflict produces zero writes. See domain packs for adoption, path-specific conflict resolution, and transaction recovery.

Validate A Created Workspace

For manual or operator-level validation, the copied workspace exposes its lower-level checks directly. Run these commands from the workspace root:

python3 scripts/doctor.py --format json
python3 scripts/smoke_validate_workspace.py --format text
python3 scripts/source_inventory.py --report
python3 scripts/normalize_sources.py --all --dry-run
python3 scripts/normalize_verify.py --format text
python3 scripts/lint.py --format text

source_inventory.py --report writes sources/manifest.jsonl, so normalize_sources.py --all --dry-run reads sources/manifest.jsonl and can preview normalized records without writing them. For aggregate health and a machine-readable completion verdict, run:

python3 scripts/workspace_status.py --format json
python3 scripts/workspace_status.py --check-complete --format json

Question intake and structured answer export are also available inside a workspace:

python3 scripts/intake_questions.py --from-file batch.yaml --dry-run
python3 scripts/intake_questions.py --from-file batch.yaml --format json
python3 scripts/export_answers.py --format json

The installed equivalents are evidence-wiki status, evidence-wiki questions add, and evidence-wiki export; see workspace status and the question API.

To preview inventory records without writing the manifest:

python3 scripts/source_inventory.py --dry-run --report

Evidence and Provider Permissions

Discovery and acquisition are separate permissions. Discovery providers (arxiv, openalex, github, search, and standards) propose metadata; candidates are not evidence until selected, acquired into raw/, and recorded with provenance. Acquisition providers (arxiv, openalex, github, and allow-listed web) retrieve selected evidence under configured limits.

Three controls remain independent:

1. integrations.discovery authorizes candidate lookup.
2. integrations.acquisition authorizes retrieval.
3. Environment credentials authenticate an already-authorized provider.

A token, installed runner, domain-pack recommendation, or discovered URL never grants provider permission. See source discovery, acquisition, and the workspace init profile for provider configuration. For reviewed local evidence, follow the source-delivery contract, keep raw files immutable, then inventory and normalize them.

Evidence is not limited to the source kinds this package extracts. Normalized records are a versioned public contract, so an external normalizer can supply records for evidence the package does not read itself — structured API payloads, instrument output — and those records count on exactly the same terms as records the package wrote. The terms are enforced, not assumed: evidence-wiki normalize verify checks a record against the contract and names each breach with a stable code, and lint accepts an externally written record only when it conforms.

Repository Layout

• workspace-template/ is copied into each research workspace and contains its scripts, skills, and operator documentation.
• domain-packs/ contains optional, reusable domain guidance.
• examples/ includes a complete public-safe workspace built from synthetic evidence.
• orchestrator/ contains the external parent-agent playbook.
• tests/ contains regression tests and synthetic fixtures with documented usage rights.

Documentation

• Start a workspace: new project guide, workspace initialization, setup profile schema, research.yml configuration, domain packs, and the worked example.
• Research and evidence: question API, source discovery, acquisition, source delivery, source manifest, normalized records, coverage manifests, evidence policies, and citation verification.
• Agents and integrations: parent orchestration, orchestrator handoff, workspace status, run controller, library API, MCP server, and orchestrator playbooks.
• Safety and operations: prompt-injection hardening, human editing and snapshots, codebase analysis, production readiness, and publication readiness.
• Project development: contributing, changelog, publishing workflow, third-party notices, and license. Architecture notes live in the workspace documents above, starting with workspace initialization and orchestration.

Development setup, repository boundaries, style rules, and the full verification suite are documented in CONTRIBUTING.md.

License

EvidenceWiki is available under the MIT License.