EvidenceWiki

Answers you can audit. EvidenceWiki gives agents persistent research workspaces with provenance, controlled question lifecycles, evidence checks and structured exports. Agents supply research judgment; scripts enforce the configured rules and retain explicit gaps when evidence is missing.

Quick start · Manual tour · Documentation · Worked example · PyPI

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

Originals stay in raw/, normalized records in sources/, research knowledge in wiki/, and durable run state in runs/. Retrieved content is evidence data; it cannot authorize commands or change policy.

Start with your agent

Use Python 3.10 or newer and an isolated environment:

python3 -m venv .research-env
.research-env/bin/python -m pip install evidence-wiki
source .research-env/bin/activate
evidence-wiki agent --format json
evidence-wiki agent summary --format json \
  --require strict-evidence/v1 --require declarative-computation/v1

On Windows, create the environment with py -3 -m venv .research-env, use .\.research-env\Scripts\python.exe to install, and activate with .\.research-env\Scripts\Activate.ps1. Subsequent examples assume the selected environment is active; its executable is evidence-wiki.exe on Windows.

You can select the interpreter explicitly without activating the environment:

.research-env/bin/python -B -m evidence_wiki agent --format json

The evidence-wiki console command and -B -m evidence_wiki.cli module form remain supported. Generated commands include the selected Python executable; retain that interpreter and its arguments. For affected installations missing the package entry point, see the same-environment workaround and recovery boundaries.

Give your current agent the installed executable, original questions, source locations, writable directory and access limits. Ask it to read agent first, preserve every question, and return a controlled research export or precise blockers. Bootstrap is read-only; another model runner is optional. Use the installed versions and instructions together: older packages can refuse a capability or request field they do not support.

Have the agent prepare a complete request from the installed planning guide, including scope, evidence criteria, strict policy, authority and budgets:

evidence-wiki agent plan-guide --format text
evidence-wiki agent plan --from-file request.json --output setup-plan.json
evidence-wiki agent plan-check --from-file setup-plan.json
evidence-wiki agent apply --from-file setup-plan.json
evidence-wiki agent --target WORKSPACE --format json
evidence-wiki agent research-guide --format text

Planning validates without creating the workspace; --output saves a new plan file outside the target. Apply rechecks identities, creates the workspace and records owned effects. Reapplying the same plan supports conservative recovery; unexplained partial writes or user changes require inspection. Setup readiness is separate from evidence completeness and research acceptance. See planning, application and recovery, and research with the current caller.

After research and required reviews, request the original-question export:

evidence-wiki agent research-export --target WORKSPACE --format json

Unresolved questions, source gaps and review requirements remain explicit. Partial output does not report complete research.

Hosts with their own acquisition tools

A saved request can select an external acquirer in decisions:

{
  "orchestration": {
    "acquisition": "delegated",
    "acquirer_agent_id": "external-acquirer"
  },
  "acquisition": []
}

This is a decision fragment; the planning guide supplies a complete request and agent plan-schemas exposes the installed schema. Omission or null retains starter/pack inheritance. Native initialization profiles also preserve orchestration declarations. Conflicting package-acquisition choices refuse before workspace writes.

Delegation assigns responsibility without granting connector access, credentials or execution authority. Drive it through the external protocol below; managed orchestrate run and resume refuse delegated workspaces.

Five-Minute Tour

This direct-initialization example creates a basic scientific workspace. Without an explicit strict policy it uses legacy QA; its export command reports answers without strict review assurance. Use the agent-led strict setup above for controlled release. Research duration depends on sources and the runner.

Inspect a pack's scope, exclusions and review requirements before selecting it:

evidence-wiki pack list
evidence-wiki pack show bundled:general-science
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 share the initializer; --dry-run previews without workspace writes. Provider flags explicitly configure separate discovery and acquisition permissions. Domain packs never enable providers on their own.

Add a question (on PowerShell, create batch.yaml in an editor):

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

Install a supported managed runner separately, check the environment, then run:

evidence-wiki doctor --format json

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

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

The controller coordinates discovery, selected acquisition, normalization and verification. Unavailable evidence remains blocked_on_sources. Use resume for a retained managed session after runner failure; see orchestration.

For offline work, omit provider flags and deliver reviewed originals with provenance sidecars under configured raw roots. From the workspace, using its selected Python environment:

python -B scripts/source_inventory.py --report
python -B scripts/normalize_sources.py --all

Inventory writes sources/manifest.jsonl; normalization writes evidence records. Use --dry-run to preview either operation, but normalization previews still require a written manifest; inventory dry-run output cannot replace it. Keep raw evidence immutable and continue with the research workflow.

Drive It With An Agent

Managed execution refuses with RUNNER_ISOLATION_UNAVAILABLE when its required boundary is unavailable. The parent owns runs/orchestrations/; workers follow bounded work orders and never invoke the parent controller or write its state. AGENTS.md and the selected skill define worker instructions; CLAUDE.md points to the same contract.

External protocol

Replace placeholders with the workspace and IDs returned by the controller:

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; submit checks workspace postconditions before advancing. External hosts own isolation, single-driver coordination, authorization and crash replay. Read the handoff contract and retrieve the packaged playbook with evidence-wiki orchestrator-guide --print.

Use agent frameworks for the installed Pi, OpenCode and Gemini version/mode matrix, and agent bundle --target NEW_DIRECTORY for a portable bundle. Bundle export changes no global agent settings or trust decisions. Transport support does not establish model behavior or host isolation. See frameworks.

For MCP, serve-mcp --target WORKSPACE exposes the workspace read/append interface. serve-onboarding-mcp --allow-root ROOT --allow-operation apply exposes scoped onboarding with host-selected roots and explicit mutation grants. These interfaces share the canonical owners.

Drive It From Python

Open an existing workspace through the library:

from evidence_wiki import Workspace

with Workspace.open("/path/to/workspace") as ws:
    status = ws.status()

Workspace operations reuse CLI owners and return plain dictionaries, with typed exceptions carrying stable error codes. Onboarding.open covers setup and lifecycle work through explicit roots and operation grants. Discover the current surface with evidence-wiki contract; see the library API for operation effects, lifetime and thread-safety rules. Orchestration retains the workspace's deployed controller subprocess. The package supplies no HTTP server.

Evidence, Permissions and Assurance

Discovery proposes candidates; acquisition retrieves selected evidence. Their permissions and credentials are independent. A token, installed runner, pack recommendation or discovered URL does not grant access. Use provider configuration and source inspection to distinguish capability, authorization, capture completeness and usable evidence.

evidence-wiki env check --service openalex --format json
evidence-wiki agent inspect --target WORKSPACE

env check reports names and presence only. env run --prompt reads missing credentials without terminal echo and passes them only to the selected command and its children; it saves nothing and does not change the parent shell. Select only needed services or --require-env NAME, and use your host secret manager for persistence. Initialization and offline work require no credentials; agent runners may use their own login. See environment setup.

Host-delivered captures retain declared origin, rights, scope and completeness. A local observation timestamp is neither a publication date nor a license grant. Native DOCX recipes are available through agent recipes. External normalizers can supply contract-conforming records, checked by normalize verify; source truth and fitness still require review.

For accepted research exports, the assurance modes require distinct boundaries:

Quote matching and exact arithmetic do not prove semantic support, correct scope/units or complete research. Contested and insufficient evidence stay explicit. Read strict evidence, computation, and prompt-injection boundaries.

Requirements and Diagnostics

Python 3.10+ is required. Installation includes PyYAML, ruamel.yaml, pypdf and tzdata; package metadata owns their supported version bounds. pypdf provides portable PDF extraction. Poppler is optional unless explicitly selected as the PDF backend; Git snapshots and managed model CLIs are optional. Run evidence-wiki doctor --format json for available capabilities and evidence-wiki status --target WORKSPACE --format json for workspace health. See workspace validation for lower-level checks and completion.

Native Windows supports local captures, protected publication, pack catalogs and setup through anchored handles and private ACLs. Reparse points, network shares and filesystems lacking required guarantees refuse. Restrict protected host state and trust files to the current account and SYSTEM. Framework qualification and host_enforced isolation remain separate; see platform and authority boundaries.

Create and Maintain a Workspace

Choose domain guidance by scope and evidence requirements. When no pack fits, retain the gap or explicitly author, assess and register local guidance using pack guide --topic authoring. Pack selection and authoring describe the decisions; agent extensions covers identity migration, composition, fleet proposals and host transitions.

Installing a newer package does not migrate existing workspaces. Preview and apply starter-managed updates explicitly:

evidence-wiki upgrade --target WORKSPACE --dry-run
evidence-wiki upgrade --target WORKSPACE

Upgrade preserves research.yml, raw/, sources/, wiki/, index.md and prior log history. Write mode uses .locks/, may update starter metadata, and appends to log.md only when material changes occur. --dry-run writes nothing. Pending orders or an active orchestration driver block both modes with UPGRADE_PENDING_ORDER; drain them first. Optional docs/skills have separate conflict rules. See upgrade and adoption.

Packs have their own lifecycle. pack revision-plan, revision-apply and revision-status retain conflicts/history and identify research requiring coverage reevaluation. Legacy adoption/refresh and identity changes remain explicit; unresolved conflicts prevent workspace writes. See pack revisions and domain packs.

Saved plans bind installation and input identities. Recompile after upgrades; preserve partial workspaces for owned recovery instead of silently adopting them or repairing frozen configuration by hand.

Documentation

The repository separates the reusable starter, optional domain packs, external orchestrator playbook and worked examples built from synthetic evidence.

License and Authorship

EvidenceWiki is available under the MIT License. It was authored entirely with AI coding agents, primarily OpenAI Codex (GPT-5.5 and GPT-5.6), with Anthropic Claude also contributing.