Metadata-Version: 2.4
Name: navigator-cli
Version: 0.2.1
Summary: Navigator CLI + Data Navigator service: query public data sources from your agent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.27
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: keyring<26,>=25
Requires-Dist: markdown>=3.10.2
Requires-Dist: navigator-contracts==0.1.1
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pyyaml<7,>=6
Requires-Dist: uvicorn[standard]<1,>=0.30

# 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](SPEC.md) for the durable product and execution contract.

## Quick start

```bash
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

```text
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.

```bash
# 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:

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

## Validation

```bash
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](../docs/deploy-runbook.md).
