Deepr

Persistent domain experts built from bounded, auditable research.

Deepr uses local models, proven subscription quota, and explicitly authorized paid APIs to build experts with beliefs, gaps, contradictions, confidence, citations, and provenance. Use it when research must stay useful, current, and inside hard cost limits.

Capacity and cost

Capacity	Intended use	Safety posture
Local Ollama	Routine expert setup, maintenance, evaluation, and consultation	Preferred owned-capacity path. Endpoint ownership must be proven.
Prepaid plan quota	Selected expert workflows using an existing subscription	Runs only when authentication, tool confinement, and paid-overage posture are proven safe.
Metered API	Premium bounded research and synthesis	Explicit opt-in only. Never selected as automatic fallback.

A budget is a ceiling, not permission to spend. Paid dispatch requires explicit consent, trusted pricing, finite bounds, a durable reservation, and append-only settlement. Spend and concurrent holds are checked together. Unknown money state fails closed.

deepr budget set 10
deepr budget status
deepr budget freeze --reason "operator stop"
deepr costs doctor

budget set 0 freezes paid work. Paid composed fan-out stays disabled until one durable parent reservation covers every child, retry, verifier, tool, and synthesis call. Details: Capacity and Cost and spend authority design.

Install

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/blisspixel/deepr/main/scripts/install.ps1 | iex"

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/blisspixel/deepr/main/scripts/install.sh | bash

The installers use the latest verified GitHub Release wheel in an isolated pipx environment. PyPI publication is not enabled. See Installation for source and platform-specific setup.

Quick start

deepr init
deepr doctor --skip-connectivity
deepr capacity
deepr expert blueprint "My Domain Expert" --template --output expert-blueprint.json
deepr expert blueprint "My Domain Expert" --from-file expert-blueprint.json --apply --attested-by operator
deepr expert make "My Domain Expert" --local -d "The decisions this expert supports"
deepr expert consult "What should we decide next?" --expert "My Domain Expert" --local

Preview paid work without dispatching it:

deepr research "What changed in this field this month?" \
  --provider openai \
  --model o4-mini-deep-research \
  --preview

Preview and dispatch share the same hard request envelope. A provider key, positive budget, and explicit confirmation are still required. See Quick Start and Experts.

What works now

Area	Current contract
Bounded research	Single provider jobs work when model, token, tool, and payload pricing can be bounded completely.
Persistent experts	Blueprint, local creation, maintenance, consultation, beliefs, gaps, outcomes, handoffs, and derived views are available.
Local investigations	Experimental multi-expert research, checking, synthesis, and staged learning run at $0 provider cost.
Plan quota	Claude Code is executable only after a live proof that paid extra usage is disabled. Other adapters remain visible with typed refusal reasons.
MCP and A2A	Read, consult, handoff, validation, and scoped transport surfaces are available. Deepr exposes 36 MCP tools.
Paid multi-call work	Batch, campaign, team, and other composed paid graphs remain gated pending one aggregate parent budget.

The authoritative boundary between shipped, experimental, visible, and planned behavior is Supported Surface.

Documentation

Guide	Purpose
Installation	Supported installation and upgrade paths
Quick Start	First research and expert workflow
Supported Surface	Stable, experimental, visible, planned, and gated behavior
Capacity and Cost	Local, subscription, metered, scheduler, and budget contracts
Experts	Persistent expert lifecycle and commands
Models	Provider models, pricing posture, and selection
Architecture	Components, data flow, and design boundaries
Threat Model	Security boundaries and mitigations
Changelog	Released behavior and migration notes
Roadmap	Active priorities and planned work
Contributing	Development workflow and Definition of Done

Development

uv pip install -e ".[dev,full]"
pytest tests/unit/ --ignore=tests/data -q
ruff check src/deepr/
ruff format --check src/deepr/
python scripts/check_file_sizes.py
python scripts/check_ratchets.py
python scripts/check_paid_api_boundaries.py

Do not run bare pytest: integration tests can contact real providers. See Contributing for every required gate.

License

Apache 2.0

GitHub | Issues | Discussions