Persistent domain experts built from bounded, auditable research.
Deepr develops inspectable expert understanding from retained research, concepts, positions, reasoning, temporal relationships, and experience. It prefers owned local models, then proven subscription quota, with no automatic fallback to a paid API.
Deepr is for people and agent teams making recurring decisions in domains that keep changing. Instead of rebuilding context for every run, they consult the same inspectable expert state through the CLI or MCP and can see what changed, what supports a position, and what remains unknown.
The expert's knowledge base connects research, concepts, explanations, and reasoned positions. Temporal records preserve changes; readable notebooks and memory views make the accumulated understanding inspectable. The product goal is an expert that develops through study, judgment, experience, and reviewed revision, then performs better on future problems. Automatic outcome-driven learning and longitudinal proof of better judgment remain roadmap work.
The next user-facing milestone is preparation before advice by default: check developments relevant to the question and environment, reconsider the stored perspective, then answer from a dated context. Current consultation uses stored expert state; explicit fresh-context maintenance is available. See the active sequence and delivery plan for the baseline, preparation, durable learning, and repeated-use evidence gates.
The pictured roster is one operator's working set: 49 experts, 25 of them
flagship. Each card exposes positions, studied findings, retained source
counts, and recorded stance shifts from durable state. Flagship membership is
user-curated local state. This is a real local roster, not a clean-install
default and not evidence of improved judgment; grades read thin state honestly,
and deepr expert health will say so. See the
validation record.
An expert should help explain a field: what works, when it is appropriate, where approaches break down, and why reasonable people disagree. For Python, that includes language and runtime behavior, computer-science fundamentals, testing and packaging, performance, security, and the tradeoffs behind advice. Breadth must come from retained research and demonstrated answers.
Expertise is open-book: strong source content, organized notes, and quick access to the original references matter as much as what the model recalls. Deepr's retained library supplies inspectable detail behind its guidance. Default live preparation and question-directed tool use remain the next delivery gate.
The profile opens on the expert's perspective, positions and reasoning, supporting research, questions considered, and unresolved questions. Claim-level support estimates remain available for inspection with their basis and limits; they do not grade the expert's overall correctness. The Python exemplar and profile acceptance criteria define what a replacement screenshot must demonstrate from real retained work. The dated Python validation includes actual Markdown, a source-linked graph, source hashes, and reviewed answers. That example has not passed its guidance gate; it is evidence for the next repairs, not a qualified expert advertisement. Reports, digests, and portable exports remain regenerable views of structured expert state.
Local and eligible plan-quota work stay at $0 marginal API cost. Metered work
never becomes an automatic fallback and cannot turn the local wallet into an
open check.
The aim is bounded authorized spend, not zero spend. No surprise bills means no bill you did not ask for; it does not mean no bills. A cap that can be exceeded is not a cap, and a cap you cannot raise is not a control, it is a wall. Deepr prefers local and plan capacity because that is cheapest, not because paid work is forbidden.
The model is the cloud-platform budget cap: a total ceiling, not a blank
cheque and not a recurring allowance. A one-time $20 cap stops at $20
forever; $20 per month re-arms twelve times a year and is $240 of annual
exposure, so a non-renewing provider limit is treated as the safer posture
rather than refused for lacking a reset.
| Control | Behaviour |
|---|---|
| Default ceiling | $5.00, fail-closed |
| Raising it | DEEPR_MAX_SPEND_CEILING_USD, set by the operator only |
| Upper bound on a raise | $100, so a typo cannot authorize a fortune |
| Lowering it | Honoured, never clamped back up |
| Auditability | The ceiling in force is reported in every contract summary |
Store an OpenRouter key with a hidden prompt, never as a command argument:
deepr keys set openrouter
deepr keys list
deepr keys check --provider openrouter
deepr budget set 20
deepr budget credits add --amount 20
deepr budget authorize openrouterA stored key is optional paid capacity. budget set 20 persists the owner
ceiling and the monthly window; it is not spend authority by itself. Wallet
credits are the non-renewing $20 cap. budget authorize openrouter proves
the live key limit is a provider hard stop. MCP, schedules, and automatic
fallback stay blocked. Attended deepr research --provider openrouter can
then run one pinned completion under the wallet and ledger.
| Class | Current posture |
|---|---|
| Local Ollama | Preferred for expert setup, maintenance, evaluation, and consultation after endpoint ownership is proven. Records $0 and does not consume wallet capacity. |
| Plan quota | Visible/read-only. No production adapter is currently execution-eligible. Claude Code is blocked because managed-policy hooks can survive safe mode; other adapters retain their existing safety blocks. Subscription auth and disabled paid overage alone do not prove process confinement. |
| Metered API | No automatic fallback. Attended deepr research --provider openrouter can run one pinned no-tool completion after a stored key, wallet credits, and budget authorize openrouter. The attended absorb path still requires verified provider prepaid-no-overage or a hard provider ceiling, plus a cumulative Deepr wallet, a separate finite job ceiling, explicit confirmation, and a durable reservation. Other metered surfaces remain gated. |
A local wallet is cumulative operator authorization, not provider credit. Paid dispatch also requires authenticated proof of provider-side prepaid capacity or a hard stop with overage disabled. OpenRouter's current-key limit is that hard stop for attended one-shot research. Other metered providers stay blocked until their account-control verifiers land. Funding a wallet, setting a budget, or approving a prompt cannot enable those other paths.
deepr capacity
deepr research "A bounded premium question" --provider openai --model o4-mini-deep-research --preview
deepr research "Compare model families" --provider openrouter --model qwen/qwen3.8-flash --preview
deepr research "A bounded premium question" --provider openrouter --model qwen/qwen3.8-flash --limit 0.50
deepr providers openrouter-check
deepr costs doctorOpenRouter catalog slugs can be previewed write-free. Automatic routing, expert
routing, and evaluation stay blocked. Explicit attended research can run one
pinned completion after deepr budget authorize openrouter. Omitting --model
defaults to qwen/qwen3.8-flash. Frontier OpenRouter slugs stay explicit. The public route
check needs no key; the separate current-key check uses a hidden prompt by
default and makes no inference request. An explicit checkout-local .env
source is documented for local use. Officially valid nullable limit controls
are reported honestly. A non-renewing total cap is accepted and reconciled
against lifetime usage. A key without a finite BYOK-inclusive limit at or
below the operator ceiling remains ineligible. Key inspection does not itself
fire inference.
See Capacity and Cost for the operating and billing boundary, Models for provider-route proposals and bounded price classes, and the OpenRouter design note for the execution gates that remain.
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 | bashInstallers use the latest verified GitHub Release wheel in an isolated pipx environment. PyPI publication is not enabled.
v2.50.19 includes the formation and knowledge commands below. Install the latest release above or follow Quick Start for a source installation.
deepr init
deepr doctor --skip-connectivity
deepr capacity
deepr expert make "My Domain Expert" --local -d "The decisions this expert supports"
deepr expert knowledge "My Domain Expert"
deepr expert consult "What should we decide next?" --expert "My Domain Expert" --localLocal creation now develops a research foundation: bounded free web search, retained sources, study of mechanisms and failures, a reasoned brief, an evidence graph, and linked Markdown. It needs an installed local model and makes no paid API call. Review the build record and practical answers before relying on its guidance. A successful build is not a qualification score.
Use --profile-only for an empty profile or --no-discovery to study only
retained UTF-8 sources. expert build NAME retries an incomplete foundation;
expert knowledge NAME regenerates its linked notebook without model calls.
Consultation selects bounded literal excerpts around the study's cited source anchors, including evidence later in a document. Excerpt selection preserves source references and does not certify that a claim is supported.
See Quick Start and Supported Surface
for current workflows. The MCP Agent Guide
covers the 37 MCP tools, dual-era 2026-07-28 protocol, and
deepr mcp conformance. The Agent Plugins install guide
covers the portable skill and read-only MCP package, host PATH setup, and its
isolated expert workspace. OKF export and the OpenClaw host-profile reference
are documented in Supported Surface.
Current compatibility targets are MCP 2026-07-28 with the documented legacy
eras and published Agent Plugins 1.0.0. See the
compatibility verification record
for tested behavior and the distinction from draft standards and host certification.
v2.50.22 adds deepr eval expert-value-rehearsal: the local four-arm
rehearsal with isolated worker inputs, blinded review binding, verified
resume and assembly of the value workbook, at $0. It also repairs local
study prompts, which had repeated every source three times. No review or
value result is claimed; the full run is pending.
v2.50.21 adds a local-only fleet-seat profile (deepr mcp seat-profile)
so an external harness or host-side router can consult experts without a
spend tool, and stops advertising Claude as an executable $0 plan.
v2.50.20 verifies prepared source-copy inventories before controlled comparisons. It adds no inference, research dispatch or expert-memory writes.
v2.50.19 repairs local expert creation, preserves source and consultation
evidence, and presents reasoned perspective without an overall expertise
score. Practical guidance qualification remains open; current-source
preparation before each answer is still planned.
v2.50.18 added live OpenRouter key inspection, a binding owner ceiling,
budget authorize openrouter, and attended one-shot research under the
wallet and ledger. v2.50.17 added deepr keys set openrouter. v2.50.16
added an owner-raisable local spend ceiling and a non-renewing OpenRouter
total cap, plus local Lemonade portraits and the Delve mark. v2.50.15
corrected MCP and Agent Plugins compatibility and blocked Claude plan
execution until managed-policy commands can be confined. It did not enable
skill execution or a claim that expert memory helps.
Next is v2.51: one blinded four-arm evaluation of whether a maintained expert improves repeated decisions versus fresh research, static history, and compiled state. That measurement comes first because Deepr's product claim is durable judgment, not a larger agent runtime. Host wiring, expert-authored skills, and broader paid APIs wait until that evidence exists.
The first rehearsal compares all four arms on the same local model and frozen sources. It can test the contribution of maintained state under that setup; it cannot establish superiority over frontier web research. Next, prepare equal isolated source inventories and bind blinded reviews to exact answers. The research assessment explains the evidence, remaining gaps, and acceptance criteria.
After the preserved baseline, v2.52 targets preparation before advice; v2.53 targets durable temporal learning; v2.54 develops perspective and inquiry; and v2.55 tests repeated-use value. Broader execution follows demonstrated benefit and its own authority gates. See what's next and why.
The local-first runtime proposal considers a creator for reusable expert skills and selected OKF knowledge, plus an optional Cloudflare companion. Local execution and canonical knowledge remain the default; hosted observation and execution are planned and gated.
- Approach contract - what the method claims, refuses, and leaves experimental
- Supported Surface - what currently runs
- Install
- Quick Start
- Capacity and Cost
- Experts
- MCP Agent Guide
- Architecture
- Models
- Threat Model
- Roadmap
- Changelog
- Contributing
uv pip install -e ".[dev,full]"
python -m 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.pyDo not run bare pytest: integration tests can contact real providers. The
blocking unit suite requires at least 80 percent branch coverage.