Skip to content

Primr Configuration Reference

This document describes all configuration options available in Primr.

Environment Variables

Model Provider Keys

Variable Description Required
XAI_API_KEY xAI Grok key for standard reasoning, strategy, and the XAI-only writing fallback Recommended
GEMINI_API_KEY Google Gemini key for low-cost writing/utility, premium mode, and Gemini-backed stages Recommended for the cheapest measured default
OPENAI_API_KEY Optional OpenAI GPT/o-series provider for routed utility, reasoning, writing, and registered premium-research candidates; this key alone does not enable full execution No
ANTHROPIC_API_KEY Optional Anthropic Claude provider for reasoning, writing, and pro roles No
OPENROUTER_API_KEY Preferred OpenRouter multi-provider gateway key; routes by default when configured No
OLLAMA_API_KEY Optional key for Ollama or another local OpenAI-compatible endpoint; Ollama defaults to ollama when unset No
AZURE_OPENAI_API_KEY Optional Azure AI Foundry provider (resolves the foundry/azure provider); set AZURE_OPENAI_BASE_URL or AZURE_OPENAI_ENDPOINT for the deployment endpoint No
AWS_BEARER_TOKEN_BEDROCK Optional AWS Bedrock provider (resolves the bedrock/aws provider); the standard AWS credential chain (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGION/AWS_PROFILE) also works. Needs pip install 'primr[bedrock]' No

Run primr init for guided first-run setup. Set keys directly with primr keys set gemini, primr keys set xai, primr keys set openai, primr keys set openrouter, primr keys set anthropic, primr keys set ollama, primr keys set foundry, or primr keys set bedrock; these hidden prompts require a foreground input/output terminal. Shell env vars and local .env values are also supported for noninteractive configuration. Run primr keys path to see the user-level config file. OpenRouter provides a single-key gateway routing by default when configured. See OpenRouter Gateway for safeguards and configuration options.

Agent Host Authentication

Primr does not define or store agent-host credential variables. Authenticate inside the official host, and keep its OAuth tokens and session state there. primr-zero keeps the host-assisted workflow inside the selected host. Primr also has an unpromoted Codex source-relevance adapter. A single-company experimental run can enable it only with --inference hybrid and --acknowledge-host-agent-may-bill, because installed Codex authentication does not prove whether execution uses plan allowance or metered API-key billing. Never copy a Claude Code OAuth token, browser cookie, or other subscription credential into Primr. Direct provider calls still use the provider API keys listed above.

Optional Search Keys

Variable Description Required
SEARCH_API_KEY Google Custom Search API key, only when SEARCH_PROVIDER=google No
SEARCH_ENGINE_ID Google Custom Search Engine ID, only when SEARCH_PROVIDER=google No

Optional Settings

Variable Description Default
AI_RESEARCH_MODEL Legacy Gemini-backed research model override gemini-3.8-flash
AI_REPORT_MODEL Legacy Gemini-backed report model override gemini-4-carbon
VERBOSE Enable verbose output false
DEBUG Enable debug mode false
PRIMR_INFERENCE_PROFILE Runtime capability-routing profile for wired stages. Supported values are cloud and hybrid. cloud is the default; hybrid enables the current routed utility-stage pilots. Route metadata is recorded in _run_state.json. Prefer the --inference CLI flag for normal use. Internal enum values used by tests and evals are not supported configuration. cloud
PRIMR_OPENROUTER_ENABLED Explicit toggle for OpenRouter routing (defaults to 1 when OPENROUTER_API_KEY is configured). Set to 0 to disable OpenRouter routing without deleting the key. 1 if configured, else 0
PRIMR_OPENROUTER_ZDR Requires zero-data-retention OpenRouter endpoints. Set to 0 only after reviewing the privacy tradeoff; provider data collection remains denied. 1
PRIMR_OPENROUTER_MODEL Optional custom OpenRouter model slug. Requires explicit input and output price variables below. unset
PRIMR_OPENROUTER_INPUT_PRICE Custom model input price in USD per 1M tokens; also enforced as the provider prompt-price ceiling. unset
PRIMR_OPENROUTER_OUTPUT_PRICE Custom model output price in USD per 1M tokens; also enforced as the provider completion-price ceiling. unset
PRIMR_OPENROUTER_MAX_INPUT_TOKENS Declared custom OpenRouter model input limit. 128000
PRIMR_OPENROUTER_MAX_OUTPUT_TOKENS Declared custom OpenRouter model output limit. 16384

Note: Legacy Gemini model override variables are still supported for Gemini-backed stages. Provider-aware routing otherwise uses the model registry and configured provider keys. Current Gemini defaults: - gemini-3.8-flash - Current stable Flash model; the default for legacy Gemini paths - gemini-4-carbon - Strongest current Gemini 4 model; the default Gemini reasoning model. Introductory rates are $2/$10 per 1M tokens through 2026-11-30, then $4/$20.

Superseded model ids stay in the registry for historical quotes and are rejected for new requests. Cost estimates (--dry-run) use the selected model's published rates. Model IDs marked unavailable in the registry are not supported override targets.

Gemini 3.8 Flash is the Flash default and Gemini 3.5 Flash-Lite is the lite default. Primr omits sampling controls on current Gemini 4 and Claude adaptive-thinking request paths and keeps thinking levels explicit. Gemini 3.8 Flash registry prices switch from Google's introductory rates to the published January 1, 2027 rates by pricing date, so future dry-runs do not silently underquote. See Google's latest-model migration guide and pricing page.

Scraping Behavior

Variable Description Default
PRIMR_MAX_HEADED_POPUPS Total number of visible-browser challenges allowed per run. Shared across the Patchright stealth tier (main-site rescue) and the orchestrator's adaptive Playwright retry. Default is 0 (no popups ever); set to 5 (or any N) to opt in for a run. 0
PRIMR_SKIP_HIRING_SIGNALS When set to 1 / true / yes, skips the hiring-signals stage entirely - no ATS/provider probes (Greenhouse, Lever, Ashby, SmartRecruiters, Workday, Workable, Recruitee, Jobvite, iCIMS, BambooHR), no careers-page crawl, no DuckDuckGo web-search fallback, no LLM extraction. Use when researching companies where hiring data is irrelevant or when debugging. Note: skill packs treat job postings as their primary input, so packs generated against companies with PRIMR_SKIP_HIRING_SIGNALS=1 will fall back to recon + research only and may require --allow-recon-only. unset
PRIMR_ALLOW_HEADED_FALLBACK Master switch for the visible-browser path in the stealth tier. Set to 0 / false / no to disable entirely regardless of budget. 1
PRIMR_ENABLE_DRISSION Include DrissionPage tiers in the external validation orchestrator. 0
PRIMR_ENABLE_GROK_SURROGATE Experimental opt-in to metered xAI web_search synthesis when deterministic blocked-site fallbacks return no content. Governed CLI/MCP/A2A research runs reject this environment-only spend because it is not estimate-bound. 0
PRIMR_DISABLE_GROK_SURROGATE Emergency override that disables the xAI surrogate even when its enable switch is set. 0
PRIMR_BROWSER_HEADED Force the Playwright tiers to launch in headed mode for a specific call. Normally set internally by the adaptive-retry path, not by users. unset
PRIMR_BROWSER_SESSION_MODE persistent enables a reused browser profile per host (set internally during adaptive retry). unset
PRIMR_PDF_LLM_MAX_CALLS Per-process experimental budget for Gemini-backed PDF extraction during scraping. Default 0 keeps PDF extraction local with PyMuPDF only. Governed CLI/MCP/A2A research runs reject positive values because these calls are not yet estimate-bound. 0
PRIMR_PDF_LLM_MAX_TOTAL_MB Total PDF bytes that Gemini extraction may receive after PRIMR_PDF_LLM_MAX_CALLS is enabled. 40

Provider-backed single-company research prompts for approval by default. JSON execution never opens an interactive prompt: without --skip-confirm, it returns one primr.command-error.v1 object with error_type: "approval_required" and starts no provider work. First run the exact command with --dry-run --json, obtain explicit approval for that quote, then repeat it with --skip-confirm --json. Approved JSON execution keeps stdout to one structured result object.

Vendor Research Cache

Vendor research (AI news) defaults to a grounded-lite engine: one Gemini call with Google Search grounding produces live, cited results at roughly $0.30 per platform. Deep Research (~$2.50/task) is opt-in via --deep-research. Results are shared in the per-user cache and reused when present. Stale or missing cache files do not trigger a fresh refresh automatically because the run must quote that extra task before execution. Use the matching explicit control when a refresh is intentional:

  • primr --generate-vendor-research <vendor> --dry-run, then repeat without --dry-run and approve the quoted aggregate estimate
  • primr "Company" https://company.com --refresh-vendor-research

Integrated research and standalone strategy commands ignore ambient automatic refresh settings. Their dry-run and budget estimates include one grounded-lite refresh task per selected platform (or a Deep Research task under --deep-research) only when --refresh-vendor-research is present. PRIMR_ALLOW_VENDOR_REFRESH=1 remains available to direct library callers that explicitly leave cache policy under environment control; estimate-bound CLI and MCP paths override it to prevent unquoted provider work.

The direct cache command accepts azure, aws, gcp, private, agnostic, or all, plus --budget <usd> and --json. It starts no provider work during dry-run, requires confirmation by default, and treats --skip-confirm as explicit noninteractive approval. JSON execution returns a structured prerequisite error when preflight fails; after preflight passes, execution without --skip-confirm returns an approval_required object. Any failed target produces a nonzero exit code while successful artifact paths remain in the human or JSON result.

Cache publication uses a same-directory atomic replacement. A completed remote task is recorded before local publication, linked destination files are replaced rather than followed, and a failed refresh reuses an existing cache with a visible warning. A provider or polling exception after submission also records a conservative task-cost row, while local preflight failure records no provider usage. Fast multi-platform refresh tasks run serially before parallel strategy writing because the provider client and usage ledger are shared process state. Each later refresh budget gate includes earlier submitted tasks.

Explicit refresh execution has a run-local outcome ledger. Provider submission callbacks record which targets started and which completed, failed, or were skipped by the budget gate. This avoids attributing work from another concurrent job to the current run. Partial refresh remains visible even when a cached file lets strategy generation continue, and causes a nonzero CLI result while preserving the completed report and successful artifacts.

AI Strategy Deep Research uses the same run-local submission accounting. Preflight and context-assembly failures do not count as provider spend, while a task that reaches provider submission remains counted even if publication later fails. Optional standard-strategy setup errors persist a failed strategy outcome and preserve the completed base report instead of converting the whole run into an apparent report failure.

Standalone strategy JSON has separate estimate, refusal, and result contracts. Use --dry-run --json for the one-object estimate. Execution with --json requires --skip-confirm and returns one result object containing expected targets, successful artifact paths, and failed targets. Without that explicit approval, the command returns one approval_required object and starts no provider work.

Variable Description Default
PRIMR_VENDOR_NEWS_TTL_DAYS Freshness threshold for cached vendor research before Primr reports it as stale. Stale files are still reused unless refresh is explicitly enabled. 7
PRIMR_ALLOW_VENDOR_REFRESH Allows stale or missing vendor research cache to trigger generation only in direct library paths that leave refresh policy environment-controlled. Integrated CLI and MCP strategy paths override it off. unset

Reasoning Topology

Variable Description Default
PRIMR_CONTINUOUS_REASONING Controls whether workbook generation (Phase 3) and cross-validation (Phase 5) share one Grok session so the validator inherits the corpus and workbook reasoning the generator produced. Every tier reasons with the version-pinned Grok 4.7 route; MAX also writes with it. FAST differs through lower reasoning effort, not a separate model. Set to 0 / false / no / off to disable. Set to 1 / true / yes / on to force-enable regardless of CLI flags. Unset means use the CLI value, which defaults on. unset (effectively on via CLI default)

Notes on continuous reasoning: - On by default after the n=3 pilot. Pass --no-continuous-reasoning on the CLI to disable for a single run. - Section writing (Phase 4) is intentionally untouched and remains parallel + fresh-call per section. The topology change only affects Phase 3 + Phase 5. - Cost impact varies by company: an n=3 pilot saw deltas from −3.7% to +32% versus the prior fresh-call topology (average ~+12%). Token accumulation across the shared session is the source of any extra cost. - Quantified quality benefit: bare leaked-instruction lines in the final report drop from an average of 5.3 (fresh-call) to 1.0 (continuous) - about 81% fewer. Hard count, not LLM-judge opinion. - Env var precedence: PRIMR_CONTINUOUS_REASONING overrides the CLI flag if explicitly set, so you can disable across all runs on a machine without changing CLI invocations.

Confidence-Label Honesty

A June-2026 calibration pass measured that primr's (Confirmed) / (Reported) labels traced to their cited source only ~0-8% of the time: the prose reads authoritative but the labels overclaim their grounding. The label-honesty pass closes that gap. It is opt-in, fail-safe, and not a shipping gate: it adjusts content (lowers a label) only on positive evidence of an overclaim, and never withholds a deliverable.

Variable Description Default
PRIMR_LABEL_HONESTY Experimental pre-ship claim-label judge. It remains default-off. Governed CLI/MCP/A2A research runs reject this environment-only switch because its judge calls are not yet part of the estimate and approval shape. Calibration harnesses may still exercise it explicitly. unset (off)

Artifact Shipping Gates

Final reports and strategy documents pass through deterministic ship-time gates (primr.output.artifact_validation). When a blocking gate trips it withholds the polished DOCX while still writing the Markdown/TXT and a sidecar *_validation.txt report, so you always get the content, just not a deliverable that looks broken. Blocking gates default to zero tolerance; a malformed or negative value falls back to 0 so a gate can never be silently disabled by a bad env value. Scaffolding-leak detection is non-blocking visibility and an eval metric, not a shipping gate.

Variable Description Default
PRIMR_MAX_SCAFFOLDING_LEAKS Max tolerated internal-scaffolding markers before logging a non-blocking warning. This covers bare [workbook], [cross-ref ...], bold **What to validate:** lines, and informal [cite: label] markers. It never withholds the polished DOCX. 0
PRIMR_MAX_DANGLING_CITATIONS Max tolerated dangling inline citations, [cite: N] references with no matching entry in the ## Sources appendix. The deterministic backstop behind the upstream LLM citation repair, which keeps the original report when it cannot reach zero. 0
PRIMR_MAX_STRUCTURE_DEFECTS Max tolerated structural defects: duplicate top-level ## headings and empty sections. Required-section presence is intentionally not gated here because it is report-type-dependent and stays a QA-scoring signal. 0

Notes on the popup budget: - The budget is a single shared counter - opt in once with PRIMR_MAX_HEADED_POPUPS=N and that N is the total allowance across all trigger points in the run. - External-source validation (web-search results) uses a separate orchestrator that excludes the Patchright stealth tier by design, so validation-pass popups are already impossible even when the budget is set. - On Linux, the budget is automatically treated as 0 when neither DISPLAY nor WAYLAND_DISPLAY is set, so SSH sessions, CI runners, and headless containers never attempt a visible-browser launch.

Configuration Classes

TimeoutConfig

Controls timeout behavior for HTTP operations.

from primr.config import TimeoutConfig

config = TimeoutConfig(
    connect=10.0,  # Connection timeout (seconds)
    read=30.0,     # Read timeout (seconds)
    total=60.0,    # Total operation timeout (seconds)
)
config.validate()  # Raises ValueError if invalid
Field Type Default Description
connect float 10.0 Timeout for establishing connection
read float 30.0 Timeout for reading response data
total float 60.0 Overall operation timeout

Validation rules: - All values must be positive - total must be >= connect - total must be >= read

CacheConfig

Controls caching behavior.

from primr.config import CacheConfig

config = CacheConfig(
    max_size=100,       # Maximum cache entries
    ttl_seconds=3600.0, # Time-to-live (None = no expiry)
    name="my_cache",    # Cache name for logging
)
config.validate()
Field Type Default Description
max_size int 100 Maximum number of cached items
ttl_seconds float or None 3600.0 Cache entry lifetime (None = no expiry)
name str "default" Cache identifier for metrics

Validation rules: - max_size must be positive - ttl_seconds must be positive or None - name must be non-empty

ScrapingConfig

Controls web scraping behavior.

Field Type Default Description
max_retries int 2 Maximum retry attempts
timeout int 15 Request timeout (seconds)
max_depth int 2 Maximum crawl depth
cache_ttl_hours int 24 Cache lifetime (hours)
min_content_length int 100 Minimum content length
min_html_length int 500 Minimum HTML length
excluded_sites list [...] URL patterns to skip
soft_block_indicators list [...] Block detection keywords

AIConfig

Controls AI model behavior.

Field Type Default Description
research_model str gemini-3.8-flash Legacy Gemini-backed research model override
report_model str gemini-4-carbon Legacy Gemini-backed report model override
max_retries int 3 Maximum retry attempts
grade_threshold int 70 Quality threshold (0-100)
default_temperature float 1.0 Model temperature (0.0-2.0)
default_thinking_level str "high" Model-supported thinking level
model_fallbacks dict {...} Fallback model chains

SearchConfig

Controls search API behavior.

Field Type Default Description
num_results int 3 Results per search
parallel_limit int 2 Concurrent searches
initial_retry_delay int 5 Initial retry delay (seconds)
excluded_domains list [...] Domains to exclude

PathConfig

Controls file paths.

Field Type Default Description
project_root Path cwd Project root directory
output_dir Path {root}/output Report output directory
working_dir Path {root}/working Working files directory
logs_dir Path {root}/logs Log files directory
cache_dir Path {root}/logs/scrape_cache Scrape cache directory

Usage history is durable user data, shared by show-usage, cost estimation, and evaluation auto-staging. It lives at PRIMR_DATA_DIR/usage_history.json when that override is set, otherwise under %LOCALAPPDATA%/primr on Windows or $XDG_DATA_HOME/primr (default ~/.local/share/primr) on Linux and macOS. primr doctor shows the resolved location. It survives replacement of a pipx or uv tool environment.

On first use, Primr imports the current installation's legacy logs/usage_history.json into the durable history. Existing distinct records from both files are retained; identical records already present are not imported again. A usage_history.migrated-<hash>.json copy retains the original bytes, and the legacy file remains untouched. Malformed legacy bytes are preserved as usage_history.legacy-<hash>.json with a warning. An unreadable or malformed existing history is never overwritten by a save; repair or move it before retrying. Library callers can still supply an explicit storage_path to use an isolated history without importing legacy data.

Migration and saves serialize through a persistent sibling usage_history.json.lock file, with a bounded wait of 10 seconds. Each save reloads committed history before appending this session's unsaved records, so another Primr process's saves or migrations are retained. The lock coordinates cooperating local processes using this protocol; it does not protect against older versions, external writers, or independent machines syncing the same directory. Keep the lock file in place. A lock timeout or failed write leaves session records pending for a later save in the same process.

Synced folders (OneDrive, Dropbox, Google Drive)

Keep high-churn paths - working/, logs/, and the scrape cache - outside cloud-synced folders when possible. Sync clients briefly lock files while uploading them, which collides with the frequent checkpoint writes a run makes (_run_state.json alone is rewritten on every phase transition). Primr retries these atomic writes when a lock blocks them (the run-state checkpoint additionally falls back to a direct overwrite), so a synced folder will not corrupt state, but runs are slower and noisier there. Run from a plain local directory (for example C:\research\ rather than C:\Users\you\OneDrive\...), and let only the final deliverables in output/ live in a synced location if you want them backed up. primr doctor probes the same atomic write path a real run uses, so it will surface this contention before a long run does.

PricingConfig

Controls cost estimation. Prices are per 1 million tokens.

Field Type Default Description
gemini_input_per_million float 2.00 Input token cost (USD/1M)
gemini_output_per_million float 12.00 Output token cost (USD/1M)
deep_research_base_cost float 2.50 Base cost per deep research task
search_cost_per_query float 0.035 Search API cost per query

These legacy settings are not the whole estimator for modern routed runs. The current default estimate comes from provider routing and strategy settings: with xAI plus Gemini configured, the default Strategic Overview plus one platform-neutral AI Strategy is typically around $1.26; an explicitly requested two-platform strategy is typically around $1.45; and --no-ai-strategy is typically around $1.08. XAI-only defaults remain on the higher legacy path. Always use primr --dry-run as the source of truth.

Usage

Getting Settings

from primr.config import get_settings

settings = get_settings()

# Access nested config
model = settings.ai.research_model
timeout = settings.scraping.timeout

Validating Configuration

from primr.config import get_settings

settings = get_settings()

# Validate all config values (except API keys)
settings.validate_all()

# Validate including API keys
settings.validate_all(include_api_keys=True)

# Validate API keys only
settings.validate()

Custom Configuration

from primr.config import configure
from pathlib import Path

settings = configure(
    project_root=Path("/custom/path"),
    verbose=True,
    debug=True,
)

Testing

from primr.config import reset_settings

# Reset singleton for test isolation
reset_settings()

Prompt Configuration

Prompts are configured via YAML files in src/primr/prompts/. See docs/INTERNALS.md for the full prompt architecture documentation.

Prompt Directory Structure

src/primr/prompts/
├── company_overview.yaml      # Company research prompt
├── strategic_layer.yaml       # Strategic analysis prompt
├── shared/
│   ├── epistemic_rules.yaml   # Fact/inference/hypothesis rules
│   ├── formatting.yaml        # Formatting standards
│   └── personas.yaml          # Analyst personas
└── strategies/
    ├── ai_strategy.yaml       # AI strategy module
    ├── cloud_migration.yaml   # Cloud migration (placeholder)
    └── data_strategy.yaml     # Data strategy (placeholder)

Adding Custom Strategy Modules

Create a new YAML file in src/primr/prompts/strategies/:

meta:
  name: "My Strategy"
  version: "1.0.0"
  description: "Description of the strategy"
  status: "active"

persona: "senior_consultant"

document_purpose: |
  Purpose of this strategy document...

sections:
  - id: executive_summary
    name: "Executive Summary"
    part: 1
    purpose: "High-level overview"
    covers:
      - "Key findings"
    depth: "2-3 paragraphs"

The strategy is automatically discovered. CLI support is available via --strategy-type and discoverable via --list-strategies.

Startup Banner

Primr shows a short startup banner by default in interactive terminals. It is skipped automatically in non-interactive/CI contexts and when NO_COLOR disables styling.

# Show banner only, then exit
primr --banner

# Choose mode explicitly
primr --banner static
primr --banner animated

# Disable once
primr --no-banner

# Disable globally (env)
set PRIMR_NO_BANNER=1

Env controls: - PRIMR_BANNER=auto|off|static|animated - PRIMR_NO_BANNER=1 - PRIMR_BANNER_DURATION_MS=250..3000 (animated mode)