agent-wiki-workspace 0.1.2

Contract-driven Markdown knowledge bases for PDF-aware agents

agent-wiki-workspace

agent-wiki-workspace builds persistent, searchable Markdown knowledge bases from local PDFs and source-code repositories. It uses agent-pdf-workspace for local extraction and OCR, and optional semantic code providers for evidence-bound architecture wikis. The core package contains no LLM, vision, embedding, or network client; an explicit code-generation command can invoke the user's installed OpenCode runtime.

What it creates

An existing Markdown or Obsidian vault can be adopted in place, or a new empty directory can be initialized:

wiki/
├── Sources/ Concepts/ Entities/ Syntheses/
├── raw/<source-id>/                  # complete agent-pdf-workspace output
└── .agent-wiki/
    ├── manifest.json
    ├── profile.{json,md}
    ├── jobs/{curation,query,visual}/
    ├── changesets/
    └── cache/search.sqlite

Existing notes, .obsidian/, AGENTS.md, and symlinks are not rewritten or followed. Curated claims retain PDF page/block evidence or exact code revision/path/line/target evidence. Agent changes are staged first and are applied only by an explicit host/user action.

Install

Python 3.11 through 3.14 is supported. A permanent tool environment is recommended because the generated OpenCode tool records its exact Python virtual-environment launcher:

uv tool install agent-wiki-workspace
wikiws --help

Install the semantic providers for source-code wikis with:

uv tool install 'agent-wiki-workspace[code]'

For repository development, use the pinned pyenv version and lockfile:

pyenv install -s 3.11.14
uv sync --frozen --group dev

Quick start

# A new wiki must be new or empty.
wikiws init /absolute/path/to/wiki --mode create --json

# Existing Markdown/Obsidian content is adopted without modifying existing files.
wikiws init /absolute/path/to/vault --mode adopt --json

# Extraction and OCR are local. The original PDF stays under raw/<source-id>/.
wikiws source add /absolute/path/to/wiki report.pdf --ocr auto --language deu+eng --json

# Explore locally.
wikiws search /absolute/path/to/wiki "specific phrase" --json
wikiws read /absolute/path/to/wiki --note "Sources/report.md" --json

# Agent-authored changes remain pending until explicitly approved.
wikiws curate prepare /absolute/path/to/wiki --source-id src-... --json
wikiws curate submit /absolute/path/to/wiki --input changeset.json --json
wikiws changes apply /absolute/path/to/wiki --changeset-id chg-... --json

wikiws lint /absolute/path/to/wiki --json
wikiws verify /absolute/path/to/wiki --json

Source-code architecture wikis

Code-wiki orchestration belongs to this package because it owns the Markdown layout, evidence contracts, staged changes, OpenCode agents, and quality evaluation. agent-codinglanguage-mapper remains the cross-language semantic provider; python-delphi-lsp adds Delphi-specific semantics and metrics.

Register a repository without copying its source into the wiki. The metadata snapshot ignores VCS, cache, build, OpenCode, and agent-integration directories and is checked again before a generated ChangeSet is accepted:

wikiws source add-code /absolute/path/to/wiki /absolute/path/to/repository --json

Pass one important semantic anchor per detected language. The bounded generator creates an overview, architecture synthesis, navigation guide, and one entity page per anchor. It uses the exact OpenCode/OpenRouter model shown below, stages one strict ChangeSet, applies it only because --apply is explicit, and then requires all five deterministic quality categories to pass (100/100):

wikiws code generate /absolute/path/to/wiki \
  --source-id src-... \
  --anchor python=BaseEventLoop \
  --anchor rust=OpenOptions \
  --anchor csharp=LanguageParser \
  --anchor delphi=TSynLogVoid \
  --anchor cpp=getClangFormatStyle \
  --model openrouter/google/gemma-4-31b-it \
  --apply --json

The builder denies raw file, shell, write, web, task, and generic LSP tools. It uses agent-codinglanguage-mapper for every language and additionally uses python-delphi-lsp for the Delphi anchor. Code evidence is rejected if the source changes, a path escapes the repository, a line is out of range, or the exact quote is absent. The evaluator scores evidence (40), language coverage (25), required structure (15), internal links (10), and useful bounded density (10). Evaluation happens against the staged ChangeSet before any page is applied. Every generated page must contain a resolvable internal link.

Provider skills, plugins, and agents are installed transactionally into the selected trusted OpenCode configuration directory, never into the repository. Generation rejects repositories that contain project-local OpenCode, Claude, or agent instruction controls because OpenCode could load those files before tool permissions take effect. The provider Python processes also run in isolated mode, and the OpenCode child receives only an allowlisted environment.

Machine-readable mode writes JSON only to stdout and diagnostics to stderr. Exit codes are 0 (success), 2 (input/contract error), 3 (incomplete state), 4 (resource limit), and 5 (integrity/security failure).

OpenCode integration

Register one router, one curator per wiki, a shared vision agent, the packaged skill, and native tools with:

wikiws opencode sync

OpenCode also receives the primary agent agent-wiki-manager. Select it and ask it to initialize a Wiki at an absolute path; the directory must be new or empty. The manager can only call the package's create tool. It cannot adopt existing content, use shell or web tools, or apply curated changes.

The router and shared vision agent are installed as primary agents. Per-Wiki curators are restricted to their bound tools, can be selected directly for auditable E2E queries, and communicate through persisted versioned contracts.

The command discovers the configuration through OPENCODE_CONFIG_DIR or opencode debug paths. It never edits opencode.json and refuses collisions with files it does not own. Interactive sync asks which vision-capable provider/model to use. The default is openrouter/google/gemma-4-31b-it; automation can choose any valid OpenCode model identifier:

wikiws opencode sync --vision-model openrouter/google/gemma-4-31b-it --json
wikiws doctor --json

The generated TypeScript tool starts exactly [absolute-venv-python, "-m", "agent_wiki_workspace", ...] without a shell or PATH lookup. Running sync again updates that binding after moving or reinstalling the environment.

Visual jobs remain pending if the selected agent/model cannot inspect images. Text curation and search continue with visual_coverage: pending; no description is fabricated. A capable external agent reads only a registered crop, then persists a matching VisualResult. Whether an image may be sent to a remote model is the calling system's privacy decision.

Python API

from agent_wiki_workspace import KnowledgeBase, KnowledgeRegistry

kb = KnowledgeBase.init("/absolute/path/to/wiki", mode="create")
source = kb.add_pdf("report.pdf", ocr="auto", languages=("deu", "eng"))
job = kb.prepare_curation(source.source_id)
hits = kb.search("specific phrase")

registry = KnowledgeRegistry.open()
registry.register(kb)
registry.install_opencode(vision_model="openrouter/google/gemma-4-31b-it")

All public agent contracts are Pydantic models using schema 1.0, reject unknown fields, and fail closed on wrong wiki/job IDs, expired jobs, unsafe paths, stale updates, or unverifiable evidence. A source changeset copies job.job_id and cites every claim with a block_id or page-bounded bbox from the PDF layout sidecar. Block quotes are normalized and checked against block text.

Trust boundary

PDF text, source code/comments, OCR, Markdown, metadata, links, attachments, QR codes, and images are untrusted content. They are never executed or fetched. Package-generated agents deny web and shell tools and receive only role-specific wiki tools. PDF passwords are accepted through Python parameters or stdin and are never persisted.

See the release procedure and verification status for reproducible builds, critical coverage, neutral clean-environment evidence, and the explicitly networked OpenRouter/OpenCode multi-wiki release gate.