Data Navigator

Data Navigator discovers, assesses, and executes versioned operations on individual structured public-record sources. It is intentionally narrower than a general answer engine: unsupported and partially supported questions are expected outcomes, and arbitrary cross-source joins are not available.

See SPEC.md for the durable product and execution contract.

Quick start

uv sync
uv run uvicorn app.main:app --reload --port 8000

uv run navigator data list --json
uv run navigator data find "Norwegian company lookup" --json
uv run navigator data assess "Find Norwegian companies named Equinor" --json
uv run navigator data show no/brreg/enheter:search-companies
uv run navigator query no/brreg/enheter --operation search-companies \
  --input '{"navn":"Equinor","size":5}'

Use find for a short capability phrase and assess for a full question. Query only a fully supported, explicitly selected operation. Unknown fields are rejected before keys, quota, adapter import, or network access.

Repository layout

app/
  main.py                 HTTP and web surface
  discovery.py            shared list/find/assess/show implementation
  runner.py               canonicalization, strict validation, execution
  contracts.py            shared result and error envelopes
  skills_registry.py      strict operation registry v2
  catalogue_client.py     authenticated, content-addressed CLI cache
  static/navigator-skill.md
  static/navigator-release.json
skills/<jurisdiction>/<source>/
  meta.yaml               operation contracts and claims
  SKILL.md                source playbook
  adapter.py              source adapter
tests/corpora/             frozen semantic and capability regressions

The skill tree is authoritative. Generated source and operation counts, registry versions, bundle hashes, and agent artifact hashes live in app/static/navigator-release.json; do not copy counts into prose.

Agent setup

The public parent skill teaches the product boundary and workflow. Correctness does not depend on it being loaded: service, CLI, and MCP contracts still reject unknown fields and unsupported execution.

# Claude Code project/user skill
navigator skill install --target claude-code
navigator skill doctor --target claude-code
navigator skill update --target claude-code

# Cowork upload archive
navigator skill package --format cowork --out navigator-cowork.zip

Install and update preserve unmanaged edits unless --force is explicit. Public downloads are available at /api/meta-skill, /api/meta-skill/manifest, and /api/meta-skill/cowork.zip; registry and query access remain member-gated.

For Claude Code, run skill install from the intended project or pass --root, restart Claude Code so it reloads .claude/skills/navigator/SKILL.md, reconnect Navigator, then run skill doctor.

For Cowork, download /api/meta-skill/cowork.zip (or build the identical ZIP with skill package), open Cowork's Skills settings, upload the ZIP, enable the navigator skill, and start a new task. Verify it by asking Cowork to assess— not execute—the unsupported EU company-revenue/GDP join example. The correct answer is partial or unsupported with no data query tool call.

Source bundles

Remote executable bundles are accepted only when their exact meta.yaml, SKILL.md, and adapter.py bytes match both the server digest and the hash pinned in the installed CLI release manifest. Cache entries are keyed by that digest and staged, verified, then moved atomically. Unpinned, partial, corrupt, or mismatched code is never imported.

Any source metadata, playbook, or adapter change requires regenerating the release manifest:

uv run python scripts/build_release_artifacts.py
uv run python scripts/build_release_artifacts.py --check

Validation

uv run python scripts/validate_skills.py
uv run pytest
uv run python scripts/smoke_public_apis.py
NAVIGATOR_CMD="uv run navigator" uv run python scripts/smoke_cli_public_apis.py

Release CI also builds the wheel and runs scripts/verify_release_artifacts.py. The scheduled health job emits one row per operation with registry and capability versions and a state of HEALTHY, EMPTY, RATE_LIMITED, DOWN, or SKIPPED.

Live smoke tests contact upstream providers and should be run only when network access is intended. Required BYO keys stay in the OS keychain through navigator keys; never put them in prompts or command arguments.

Membership and deployment

The OSINT Navigator service owns sessions, PATs, capability introspection, MCP, and quota buckets. This service gates registry/query access on the data_sources capability. Cross-service environment and rollout details live in the deploy runbook.