Primr API Reference¶
This document describes how to use Primr programmatically as a Python library.
Installation¶
Quick Start¶
import asyncio
from primr.core.research_orchestrator import ResearchOrchestrator, ResearchMode
async def main():
orchestrator = ResearchOrchestrator()
result = await orchestrator.research(
"Acme Corp",
"https://acme.example",
mode=ResearchMode.COMPLETE
)
if result.success:
print(f"Generated {len(result.section_results)} sections")
print(f"Duration: {result.duration_seconds:.0f}s")
else:
print(f"Error: {result.error}")
asyncio.run(main())
Core Classes¶
ResearchOrchestrator¶
The main entry point for running research.
from primr.core.research_orchestrator import (
ResearchOrchestrator,
ResearchMode,
ResearchConfig,
OrchestratorResult
)
Constructor¶
No arguments required. The orchestrator lazy-loads clients as needed.
research()¶
Execute company research using the specified mode.
async def research(
company_name: str,
website: str | None = None,
mode: ResearchMode = ResearchMode.STRUCTURED,
config: ResearchConfig | None = None,
on_progress: Callable[[str], None] | None = None,
context_files: list[str] | None = None,
) -> OrchestratorResult
Parameters:
| Name | Type | Description |
|---|---|---|
company_name |
str | Name of the company to research |
website |
str or None | Company website URL |
mode |
ResearchMode | Research mode (STRUCTURED, DEEP_RESEARCH, COMPLETE) |
config |
ResearchConfig or None | Optional configuration overrides |
on_progress |
Callable or None | Progress callback function |
context_files |
list or None | Additional context files (PDFs, docs) |
Returns: OrchestratorResult
Example with progress callback:
def on_progress(message: str):
print(f"Progress: {message}")
result = await orchestrator.research(
"Acme Corp",
"https://acme.example",
mode=ResearchMode.COMPLETE,
on_progress=on_progress
)
ResearchMode¶
Available research modes.
from primr.core.research_orchestrator import ResearchMode
ResearchMode.STRUCTURED # Website scraping + web search
ResearchMode.DEEP_RESEARCH # Autonomous web research
ResearchMode.COMPLETE # Two-step: structured then deep
ResearchConfig¶
Configuration for a research task.
from primr.core.research_orchestrator import ResearchConfig
config = ResearchConfig(
mode=ResearchMode.COMPLETE,
timeout=3600, # Max duration in seconds
poll_interval=10, # Seconds between status checks
include_website_scrape=True,
include_web_search=True,
sections=None # Specific sections to research (or None for all)
)
OrchestratorResult¶
Result from the research orchestrator.
@dataclass
class OrchestratorResult:
company_name: str
website: str | None
mode: ResearchMode
section_results: dict[str, str] # Section key -> content
raw_content: str
citations: list
duration_seconds: float
success: bool
error: str | None
timestamp: datetime
pending_interaction_id: str # Internal durable-recovery handoff, or empty
The interaction ID is persisted when background work starts and is acknowledged only by the outer writer after its required output set is durable. Callers that invoke the orchestrator directly and write their own artifacts own that final acknowledgement boundary.
Versioned Job Status¶
Use primr --check-jobs --json for the CLI collection contract. MCP
check_jobs, primr://research/status, A2A check_jobs, hosted status, and the
application job list expose the same primr.job-status v1.0 projection without
report bodies or paths. See Job Status for field semantics and
compatibility rules.
Versioned CLI Command Errors¶
Commands that accept --json emit exactly one JSON object on an expected or
top-level failure. The stable error envelope is:
| Field | Type | Meaning |
|---|---|---|
schema_version |
string | Always primr.command-error.v1 for this contract. |
operation |
string | Lowercase command or operation name. |
error |
boolean | Always true. |
error_type |
string | Stable category, including unexpected_error for unhandled failures. |
message |
string | Body-safe operator or caller guidance. |
hints |
array of strings | Optional ordered recovery actions. |
Human progress text is suppressed from JSON stdout, including workspace lease,
interrupt, and unexpected top-level failures. Consumers should branch on
schema_version and error_type, not parse message text.
Accessing results:
result = await orchestrator.research("Acme Corp", "https://acme.example")
if result.success:
# Access individual sections
overview = result.section_results.get("company_overview", "")
products = result.section_results.get("detailed_products_services", "")
# Get all section keys
print(result.section_results.keys())
# Access raw content (for Complete mode)
full_report = result.raw_content
# Access citations
for citation in result.citations:
print(f"{citation['number']}: {citation['url']}")
Core Modules¶
The primr.core package contains specialized modules for different aspects of research. These can be imported directly for more granular control.
Workspace Management¶
Working folder creation and file operations.
Fresh run folders are allocated atomically. Concurrent same-company runs keep the sortable minute label but receive distinct numeric suffixes instead of sharing mutable state. Higher-level research and strategy flows also hold cross-process ownership leases while resuming or publishing company artifacts; malformed, foreign-host, or unverifiable ownership fails closed.
from primr.core.workspace import (
create_working_folder,
consolidate_working_folder,
save_section_output,
validate_context_files,
WorkspaceConfig,
ConsolidationResult,
)
# Create a working folder for research
folder = create_working_folder("Acme Corp")
print(f"Working folder: {folder}")
# Save section output
save_section_output(folder, "company_overview", "Acme Corp is a technology company...")
# Consolidate all sections into a single file
result = consolidate_working_folder(folder)
print(f"Consolidated {result.section_count} sections")
AI Strategy Generation¶
Generate AI strategy recommendations with platform context.
from primr.core.ai_strategy import (
generate_ai_strategy_sync,
Platform,
)
# Generate AI strategy for a company. Cost-gated hosts can explicitly block
# environment-driven vendor-research refreshes for estimate parity.
output_path = generate_ai_strategy_sync(
company_name="Acme Corp",
platform=Platform.AWS,
company_research_path="output/Acme_Corp_Strategic_Overview.md",
allow_vendor_refresh=False,
)
if output_path:
print(output_path)
Platform enum:
Platform.AWS # Amazon Web Services
Platform.AZURE # Microsoft Azure
Platform.GCP # Google Cloud Platform
Platform.AGNOSTIC # No single cloud preference
Platform.PRIVATE # Private cloud or NVIDIA
Deep Research Runner¶
Execute Deep Research with preflight validation.
from primr.core.deep_research_runner import (
perform_deep_research,
validate_preflight,
DeepResearchConfig,
DeepResearchMode,
PreflightResult,
)
# Build the exact run shape, then validate it before provider work
config = DeepResearchConfig(
company_name="Acme Corp",
website="https://acme.example",
mode=DeepResearchMode.COMPLETE,
)
preflight = validate_preflight(config)
if preflight.is_valid:
result = await perform_deep_research(config)
else:
print(f"Preflight failed: {preflight.errors}")
CLI Module¶
Command-line interface components for programmatic use.
# Run system check programmatically
success = run_doctor()
# Parse CLI arguments
config = parse_args(["Acme Corp", "https://acme.example", "--mode", "deep"])
print(f"Company: {config.company_name}")
print(f"Mode: {config.mode}")
Structured Research¶
Website scraping pipeline with section-by-section analysis.
from primr.core.structured_research import (
run_research,
research_section,
generate_initial_overview,
ScrapedData,
AnalysisResult,
ResearchContext,
)
Vendor Research¶
Platform AI capabilities research.
from primr.core.vendor_research import (
get_or_generate_vendor_research,
get_or_generate_vendor_research_sync,
VendorResearchFile,
VendorResearchResult,
)
Backward Compatibility¶
For existing code, all functions remain available from research_agent.py:
# These imports still work (delegate to new modules internally)
from primr.core.research_agent import (
main,
run_doctor,
create_working_folder,
consolidate_working_folder,
run_research,
research_section,
Platform,
DeepResearchConfig,
DeepResearchMode,
)
AI Client¶
Direct access to the AI client for custom prompts.
Using the singleton¶
Creating a new instance¶
client = AIClient(api_key="your-api-key")
response = client.generate(
"Analyze this company",
model_type="research",
thinking_level="high"
)
generate()¶
Generate content with automatic retries.
def generate(
prompt: str,
model_type: str = "research",
temperature: float = 1.0,
thinking_level: str = "high",
max_retries: int | None = None,
timeout: float | None = None,
) -> str
Parameters:
| Name | Type | Description |
|---|---|---|
prompt |
str | The prompt to send |
model_type |
str | "research" or "report" |
temperature |
float | Sampling temperature (0.0-2.0) |
thinking_level |
str | Model-supported enum; current Gemini values range from minimal to high |
max_retries |
int or None | Override default retry count |
timeout |
float or None | Request timeout in seconds |
generate_fast()¶
Fast generation with minimal thinking.
Token usage tracking¶
client = AIClient(track_usage=True)
# Make some calls
client.generate("First prompt")
client.generate("Second prompt")
# Get usage summary
usage = client.get_usage_summary()
print(f"Total tokens: {usage['total_tokens']}")
print(f"Estimated cost: ${usage['total_cost']:.4f}")
# Reset counters
client.reset_usage()
Deep Research Client¶
Direct access to Gemini's Deep Research Agent.
The client uses Google's background Interactions API. Background interactions
set store=True, which Google requires for polling and resume. Context-file
uploads wait for their File Search long-running operations to finish before the
research interaction starts. Google documents that imported File Search data
persists until its store is deleted, while the temporary raw File API object is
deleted after 48 hours. Primr deletes owned stores after terminal work, but
keeps a store when an accepted interaction may still be running. See Google's
Interactions storage guide
and File Search guide.
Basic usage¶
client = DeepResearchClient()
result = await client.research(
"Research Acme Corp's competitive position in the market"
)
print(result.content)
for citation in result.citations:
print(f"Source: {citation['url']}")
With progress callback¶
def on_progress(progress: ResearchProgress):
print(f"Status: {progress.status.value}")
print(f"Message: {progress.message}")
if progress.thought:
print(f"Thinking: {progress.thought}")
result = await client.research(
"Research Acme Corp",
on_progress=on_progress
)
Output formats¶
# Company profile format
result = await client.research(
"Research Acme Corp",
output_format="company_profile"
)
# Executive summary format
result = await client.research(
"Research Acme Corp",
output_format="executive_summary"
)
# Competitive analysis format
result = await client.research(
"Research Acme Corp",
output_format="competitive_analysis"
)
With priority URLs¶
result = await client.research(
"Research Acme Corp",
priority_urls=["https://acme.example", "https://ir.acme.example"]
)
Job Management¶
Deep Research jobs run asynchronously. If a connection drops, the job continues on Google's servers.
from primr.ai.deep_research import get_deep_research_client
from primr.ai.job_persistence import (
get_pending_jobs,
remove_pending_job,
save_pending_job,
)
# Check status of a specific job without mutating pending state
client = get_deep_research_client()
result = client.check_job("v1_abc123...")
print(f"Status: {result['status']}") # Provider status, or check_error for a local check failure
print(f"Terminal: {result['terminal']}")
if result['content']:
print(f"Content: {result['content'][:500]}...")
# List all pending jobs
jobs = get_pending_jobs()
for job_id, info in jobs.items():
print(f"{job_id}: {info['description']} (saved {info['started']})")
# Manually save a job for later recovery
save_pending_job(
interaction_id="v1_abc123...",
job_type="ai_strategy",
description="AI Strategy for ExampleCo"
)
# Remove a completed job only after its output is durably saved
remove_pending_job("v1_abc123...")
Pending-job mutations hold a local operating-system lock for the complete read-modify-write transaction and publish with atomic replacement. Cleanup fails closed when the registry is malformed and never removes records added after the operator's preview.
CLI commands for job management:
primr --check-jobs # Read-only cloud and latest-local status
primr --resume-latest # Finalize completed cloud jobs, then acknowledge them
primr --clear-jobs # Confirm removal of all pending recovery records
Scraping¶
Direct access to the scraping engine.
from primr.data.scrape import (
scrape_with_requests,
scrape_with_httpx,
scrape_with_playwright,
scrape_with_playwright_aggressive,
get_cached_content,
cache_content,
clear_cache
)
Tiered scraping¶
url = "https://example.com"
# Try each tier in order
content, error = scrape_with_requests(url)
if content is None:
content, error = scrape_with_httpx(url)
if content is None:
content, error = scrape_with_playwright(url)
if content is None:
content, error = scrape_with_playwright_aggressive(url)
if content:
print(f"Scraped {len(content)} characters")
else:
print(f"All tiers failed: {error}")
Caching¶
url = "https://example.com"
# Check cache first
cached = get_cached_content(url)
if cached:
print("Using cached content")
else:
content, error = scrape_with_requests(url)
if content:
cache_content(url, content)
# Clear old cache entries
clear_cache(max_age_hours=24)
# Clear all cache
clear_cache()
Parallel scraping¶
from primr.data import ParallelScraper, get_parallel_scraper
scraper = get_parallel_scraper()
results = await scraper.scrape_urls([
"https://example.com/page1",
"https://example.com/page2",
"https://example.com/page3"
])
for result in results:
if result.success:
print(f"{result.url}: {len(result.content)} chars")
else:
print(f"{result.url}: {result.error}")
Report Generation¶
Generate reports from research results.
from primr.output import DocumentBuilder
from pathlib import Path
builder = DocumentBuilder()
# Build DOCX from sections
doc_path = builder.build_docx(
sections=result.section_results,
company_name="Acme Corp",
output_dir=Path("output")
)
print(f"Report saved to: {doc_path}")
Configuration¶
Accessing settings¶
from primr.config import get_settings, configure
# Get current settings
settings = get_settings()
print(f"Research model: {settings.ai.research_model}")
print(f"Scrape timeout: {settings.scraping.timeout}")
# Validate settings
settings.validate_all(include_api_keys=True)
Custom configuration¶
from primr.config import configure
from pathlib import Path
settings = configure(
project_root=Path("/custom/path"),
verbose=True,
debug=True
)
Configuration classes¶
from primr.config import (
TimeoutConfig,
CacheConfig,
ScrapingConfig,
AIConfig,
SearchConfig,
PathConfig,
PricingConfig
)
# Example: Custom timeout config
timeout = TimeoutConfig(
connect=10.0,
read=30.0,
total=60.0
)
timeout.validate() # Raises ValueError if invalid
Type Definitions¶
Primr provides comprehensive type definitions for type-safe code.
from primr.types import (
# Type aliases
URL,
FilePath,
HTMLContent,
TextContent,
# Enums
AIModelType,
ThinkingLevel,
ScrapeTier,
OutputFormat,
# TypedDicts
SearchResult,
ScrapedPage,
GradeResult,
ReportSection,
CompanyInfo,
ResearchContext,
# Protocols
AIClientProtocol,
ScraperProtocol,
SearchProtocol,
CacheProtocol,
# Generic types
Result,
# Type guards
is_valid_url,
is_search_result,
is_scraped_page
)
Using the Result type¶
from primr.types import Result
def fetch_data(url: str) -> Result[str]:
try:
content = scrape(url)
return Result.ok(content)
except Exception as e:
return Result.err(e)
result = fetch_data("https://example.com")
if result.is_ok:
print(result.value)
else:
print(f"Error: {result.error}")
# Or use unwrap_or for default value
content = result.unwrap_or("No content available")
Error Handling¶
from primr.utils.errors import (
ResearchError,
AIError,
ScrapingError,
ConfigurationError,
ValidationError,
retry_on_failure,
safe_call
)
Custom error handling¶
from primr.utils.errors import AIError, retry_on_failure
@retry_on_failure(max_retries=3, delay=1.0)
def call_api():
return client.fetch()
# Or use safe_call for exception wrapping
result = safe_call(risky_function, default_value="fallback")
Error context¶
from primr.utils.errors import error_context
with error_context("fetching company data", company="Acme Corp"):
# Operations here will have context in error messages
data = fetch_data()
Logging¶
from primr.utils.logging_config import get_logger, setup_logging
# Get a module-specific logger
logger = get_logger("my_module")
logger.info("Starting operation")
logger.debug("Debug details")
logger.error("Something went wrong")
# Configure logging
setup_logging(level="DEBUG", log_file="primr.log")
Console Output¶
from primr.utils.console import console
console.step("Starting research...")
console.ok("Research complete")
console.warn("Some sections had low quality")
console.error("Failed to scrape website")
console.progress(5, 10, "Processing sections")
console.progress_done()
Observability¶
from primr.utils.observability import (
operation_context,
timed,
Metrics,
emit_metrics
)
# Track operation duration
with operation_context("research", company="Acme Corp"):
research_company("Acme Corp")
# Decorator for timing
@timed("my_operation")
def slow_function():
return perform_operation()
# Emit custom metrics
metrics = Metrics(
operation="custom_op",
duration_seconds=5.0,
success=True,
metadata={"key": "value"}
)
emit_metrics(metrics)
Complete Example¶
import asyncio
from pathlib import Path
from primr.core.research_orchestrator import ResearchOrchestrator, ResearchMode
from primr.output import DocumentBuilder
from primr.utils.console import console
from primr.utils.logging_config import setup_logging
async def research_company(name: str, website: str):
# Setup
setup_logging(level="INFO")
# Progress callback
def on_progress(msg: str):
console.step(msg)
# Run research
console.step(f"Starting research for {name}")
orchestrator = ResearchOrchestrator()
result = await orchestrator.research(
name,
website,
mode=ResearchMode.COMPLETE,
on_progress=on_progress
)
if not result.success:
console.error(f"Research failed: {result.error}")
return None
console.ok(f"Research complete in {result.duration_seconds:.0f}s")
# Generate report
builder = DocumentBuilder()
output_path = builder.build_docx(
sections=result.section_results,
company_name=name,
output_dir=Path("output")
)
console.ok(f"Report saved to {output_path}")
return output_path
if __name__ == "__main__":
asyncio.run(research_company("Acme Corp", "https://acme.example"))
Prompt Architecture¶
The prompt system (v1.2.5+) externalizes prompts to YAML configuration files.
from primr.prompts import (
PromptComposer,
PromptContext,
ComposedPrompt,
StrategyModuleRegistry,
get_registry,
load_prompt_config,
build_company_overview_prompt,
build_ai_strategy_prompt,
get_available_prompts,
)
PromptComposer¶
Build prompts from YAML configurations with variable substitution.
from primr.prompts import PromptComposer, PromptContext
composer = PromptComposer()
context = PromptContext(
company_name="Acme Corp",
website_url="https://acme.example",
platform="azure",
)
# Compose a standard prompt
result = composer.compose("company_overview", context)
print(result.content)
print(f"Sections: {result.section_count}")
print(f"Words: {result.word_count}")
# Compose a strategy prompt
result = composer.compose_strategy("ai", context)
print(result.content)
StrategyModuleRegistry¶
Discover and manage strategy modules.
from primr.prompts import get_registry
registry = get_registry()
# List available strategies
for name in registry.list_names():
print(name) # ai, cloud, data
# Get strategy details
strategy = registry.get("ai")
print(strategy.display_name) # "AI Strategy"
print(strategy.description)
# Get context files for a strategy (for File Search Store)
files = registry.get_context_files("ai", vendor="azure")
for f in files:
print(f) # vendor-research/vendor-research-azure-2025-12.txt
Legacy Prompt Builders¶
For backward compatibility, the original functions still work:
from primr.prompts import (
build_company_overview_prompt,
build_ai_strategy_prompt,
get_available_prompts,
)
# List available prompts
prompts = get_available_prompts() # ['ai_strategy', 'company_overview', ...]
# Build prompts (delegates to PromptComposer internally)
prompt = build_company_overview_prompt("Acme Corp", website_url="https://acme.example")
prompt = build_ai_strategy_prompt("Acme Corp", platform="azure")
Custom Exceptions¶
from primr.prompts import (
PromptConfigError,
PromptConfigNotFoundError,
PromptConfigValidationError,
StrategyModuleNotFoundError,
DataSourceNotFoundError,
)
try:
composer.compose("nonexistent", context)
except PromptConfigNotFoundError as e:
print(f"Not found: {e.prompt_name}")
print(f"Searched: {e.searched_paths}")
print(f"Available: {e.available_prompts}")
Singleton Management¶
Most components use thread-safe singletons. For testing or custom configurations, you can reset them:
from primr.ai import reset_client
from primr.data import reset_cache
from primr.config import reset_settings
# Reset all singletons
reset_client()
reset_cache()
reset_settings()
MCP Server¶
Primr includes a Model Context Protocol (MCP) server that enables AI agents to drive company research programmatically. The MCP server exposes Primr's functionality through a standardized protocol that AI assistants like Claude Desktop can use.
Protocol Revision¶
Primr speaks MCP specification revision 2026-07-28 natively (via MCP
Python SDK v2) and still answers the legacy initialize handshake, so both
modern stateless clients and older handshake-era clients work against one
server on either transport. Spec-revision specifics Primr implements:
server/discoveradvertises supported versions, capabilities, and server identity (name, version, instructions).tools/list,prompts/list,resources/list,resources/templates/list, andresources/readresults carryttlMs/cacheScopecache hints. All hints areprivate: responses are auth-scoped and must not be reused across authorization contexts by shared intermediaries.- Parameterized
primr://.../by_job/{job_id}resources are advertised throughresources/templates/list(and remain inresources/listfor older clients). - Unknown tools, resources, and prompts return JSON-RPC
-32602(Invalid Params) per the 2026-07-28 error-code alignment. - Tool listings are deterministic across calls, which enables client-side caching and stable LLM prompt-cache prefixes.
Primr does not use the deprecated Roots, Sampling, or Logging capabilities, the retired HTTP+SSE transport, or protocol-level sessions.
Quick Start¶
# Run with stdio transport (for Claude Desktop)
primr-mcp --stdio
# Run with HTTP transport
primr-mcp --http --port 8000
# Loopback-only development mode (no auth)
primr-mcp --http --host 127.0.0.1 --port 8000 --no-auth --allow-plaintext
HTTP authentication can be disabled only on an explicit loopback listener.
Primr refuses --no-auth with wildcard, public, or otherwise non-loopback
hosts even when --allow-plaintext acknowledges upstream TLS termination.
Claude Desktop Integration¶
Add to your claude_desktop_config.json:
Programmatic Usage¶
import asyncio
from primr.mcp_server import create_mcp_server
async def main():
# Create server with stdio transport
server = create_mcp_server(transport="stdio")
await server.run()
# Or with HTTP transport
server = create_mcp_server(
transport="streamable-http",
port=8000,
host="127.0.0.1",
require_auth=True,
)
await server.run()
asyncio.run(main())
HTTP Probes¶
HTTP mode exposes two unauthenticated, body-safe probe routes:
GET /healthzis a shallow process-liveness check. It returns HTTP 200 with{"status":"ok"}and does not claim that controller state or persistence is ready.GET /readyzreturns HTTP 200 only while the controller lifecycle is ready, its exclusive journal lease is held, shutdown has not started, and journal, audit, and output persistence passed startup preflight. It returns HTTP 503 with allowlisted component states otherwise.
Both responses set Cache-Control: no-store and omit paths, exception text,
and stored content. Deploy the current process-local controller as exactly one
persistent replica.
Tools¶
Without optional A2A support, the MCP server exposes 16 tools: 11 core
research, lifecycle, and usage tools; three agentic tools; and two skill-pack
tools. Installing the A2A extra adds delegate_to_agent as a seventeenth tool.
This section documents the core research and lifecycle tools. Agentic tools are
covered under MCP Agentic Tools, and the skill-pack tools
are covered in the Skill Pack Guide.
estimate_run¶
Get cost and time estimates before running research. Always surface the exact
estimate and get explicit user approval. Cost-cap enforcement is on by default
for every MCP transport, so pass the approved estimate into
research_company.max_estimated_cost_usd with its approval_token.
{
"name": "estimate_run",
"arguments": {
"company_url": "https://acme.example",
"mode": "full",
"platforms": ["azure"],
"strategy_type": "ai",
"no_ai_strategy": false
}
}
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
company_url |
string | Yes | Company website URL |
mode |
string | No | Research mode: full (default), premium, scrape, deep |
platforms |
array of strings | No | Exactly one platform for the integrated AI strategy. Values: azure, aws, gcp, agnostic, private. Default: ["agnostic"]. Generate additional platform documents after the report with estimate_strategy and generate_strategy. |
strategy_type |
string | No | Integrated strategy type. The supported value is ai (default). Generate other strategy modules after the report with estimate_strategy and generate_strategy. |
no_ai_strategy |
boolean | No | Skip AI strategy generation entirely (report only). Default: false |
verify |
boolean | No | Run post-QA claim verification (~$0.01, 3-5 min). Default: false |
max_estimated_cost_usd |
number | No | Reserved execution-cap field. estimate_run does not launch work; pass the enforced ceiling to research_company. |
Response:
{
"estimated_cost_usd": 0.89,
"estimated_time_minutes": 53,
"estimated_time_range": "34-53 min + AI strategy (Grok)",
"planned_pages": 20,
"mode": "full",
"budget_enforcement": {
"preflight": "refuses to start when the estimated cost exceeds the ceiling",
"runtime_checkpoints": true,
"runtime": "runtime checkpoints are active for optional fast-mode spend; core workbook and section-writing calls are not skipped after they start",
"checkpointed_stages": [
"research deepening",
"cross-validation enrichment",
"contradiction resolution",
"strategy generation"
],
"non_interruptible_required_tasks": []
},
"ai_strategy": true,
"platforms": ["azure"],
"strategy_type": "ai",
"approval_token": "<signed token>",
"approval_token_id": "<token id>",
"approval_expires_at": "<ISO-8601 expiry>"
}
The estimate always returns a short-lived approval token bound to the quoted
execution shape. Pass that token and an execution ceiling at least as high as
estimated_cost_usd to research_company. Map the estimate's one platforms
item to the execution platform field. Estimates with zero or multiple
platforms, the multi-target ms alias, or a non-AI strategy_type are rejected
before an approval token is issued.
Approval tokens are single-use and bound to the server process that issued them, in addition to their tool, arguments, cost ceiling, and expiry. A server restart invalidates outstanding tokens even when the signing secret is shared. Call the matching estimate tool again after a restart and obtain fresh user approval before execution.
estimate_strategy¶
Get cost and time estimates before generating a strategy document. Always
surface the exact estimate and get explicit user approval. Enforcement is on
by default for every MCP transport, so pass the approved estimate into
generate_strategy.max_estimated_cost_usd with its approval_token.
Response:
{
"strategy_type": "customer_experience",
"estimated_cost_usd": 2.5,
"estimated_time_minutes": 12,
"requires_platform": false,
"platform": null,
"cost_basis": "Planning estimate for one standard Gemini Deep Research task; actual token and tool usage varies.",
"cost_warning": "Strategy generation incurs real API charges. Get explicit user approval before generate_strategy.",
"approval_token": "<signed token>",
"approval_token_id": "<token id>",
"approval_expires_at": "<ISO-8601 expiry>"
}
research_company¶
Initiate company research asynchronously. The call returns a job id after the
supervised worker joins its ownership boundary and emits ready; the pipeline
then continues in that child process. Full and premium modes include one
agnostic AI Strategy by default. Set platform to bias it or
no_ai_strategy=true to request the report only. Call this only after
estimate_run and explicit user approval.
{
"name": "research_company",
"arguments": {
"company_name": "Acme Corp",
"company_url": "https://acme.example",
"mode": "full",
"platform": "azure",
"skip_qa": false,
"max_estimated_cost_usd": 0.89,
"approval_token": "<signed token from estimate_run>"
}
}
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
company_name |
string | Yes | Display name for the company |
company_url |
string | Yes | Company website URL (must be valid HTTP/HTTPS) |
mode |
string | No | Research mode: full (default), premium, scrape, deep |
platform |
string | No | Platform for AI strategy. Values: azure, aws, gcp, agnostic, private. Default for full and premium: agnostic. |
no_ai_strategy |
boolean | No | Skip AI Strategy generation and return the base report only. Default: false |
skip_qa |
boolean | No | Skip quality assessment. Default: false |
verify |
boolean | No | Run post-QA claim verification. Default: false |
destination |
string | No | Optional destination under an allowed output root, such as client-deliverables. Artifacts are copied here in addition to the default output/ directory. Absolute paths outside configured roots are rejected. |
max_estimated_cost_usd |
number or numeric string | Yes | Hard ceiling for estimated run cost and runtime budget. Use a value at least as high as the approved estimate. |
approval_token |
string | Yes | Short-lived token returned by the matching estimate_run. |
Response:
generate_strategy¶
Generate a strategy document from an existing report after the fact. This is
only needed when adding or regenerating a strategy for a completed research
run. New full and premium research_company calls include an agnostic strategy
by default; set platform there only when the strategy should target a
specific platform. Use this standalone flow for additional platform documents
and for non-AI strategy modules; integrated research accepts one AI strategy
target per run.
{
"name": "generate_strategy",
"arguments": {
"report_path": "output/Acme_Corp_Strategic_Overview.md",
"strategy_type": "customer_experience",
"max_estimated_cost_usd": 2.5,
"approval_token": "<signed token from estimate_strategy>"
}
}
Strategy types: ai_strategy, customer_experience,
modern_security_compliance, data_fabric_strategy, and skills. Each
non-AI request dispatches its matching YAML-defined module. The legacy
skills module also emits per-role SKILL.md files; use estimate_skill_pack
and generate_skill_pack for the QA-refined pack workflow.
check_jobs¶
Check research job status. Completed jobs return output pointers by default.
Authenticated HTTP callers do not receive inline report or strategy bodies
from check_jobs; the report scope authorizes the explicit
primr://output/report/by_job/{job_id} resource instead. Local stdio callers
keep the historical inline-artifact default for backwards compatibility.
Prefer primr://output/artifacts/by_job/{job_id} for compact inventory reads
and primr://output/report/by_job/{job_id} for explicit report-body reads.
Response (in progress):
{
"jobs": [
{
"job_id": "job_abc123",
"status": "in_progress",
"company_name": "Acme Corp",
"output_path": null
}
]
}
Response (completed - authenticated default):
{
"jobs": [
{
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"output_path": "output/Acme_Corp_Strategic_Overview_04-08-2026.md",
"artifacts_content_included": false,
"include_artifacts_requested": false,
"artifact_metadata_uri": "primr://output/artifacts/by_job/job_abc123",
"report_read_uri": "primr://output/report/by_job/job_abc123"
}
]
}
Response (authenticated caller requested artifacts without report scope):
{
"jobs": [
{
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"output_path": "output/Acme_Corp_Strategic_Overview_04-08-2026.md",
"artifacts_content_included": false,
"include_artifacts_requested": true,
"artifact_metadata_uri": "primr://output/artifacts/by_job/job_abc123",
"report_read_uri": "primr://output/report/by_job/job_abc123",
"report_read_required": true,
"required_scopes": ["report"]
}
]
}
Response (authenticated caller requested artifacts with report scope):
{
"jobs": [
{
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"output_path": "output/Acme_Corp_Strategic_Overview_04-08-2026.md",
"artifacts_content_included": false,
"include_artifacts_requested": true,
"artifact_metadata_uri": "primr://output/artifacts/by_job/job_abc123",
"report_read_uri": "primr://output/report/by_job/job_abc123",
"report_read_required": true
}
]
}
Response (local stdio compatibility path):
{
"jobs": [
{
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"output_path": "output/Acme_Corp_Strategic_Overview_04-08-2026.md",
"artifacts_content_included": true,
"include_artifacts_requested": true,
"artifacts": [
{
"type": "strategic_overview",
"filename": "Acme_Corp_Strategic_Overview_04-08-2026.md",
"content": "# Acme Corp Strategic Overview\n\n..."
},
{
"type": "ai_strategy",
"filename": "Acme_Corp_AI_Strategy_AZURE_04-08-2026.md",
"content": "# AI Strategy (Azure)\n\n..."
}
]
}
]
}
run_qa¶
Run quality assessment on a report.
doctor¶
Check system health and configuration.
In cloud mode, cloud_diagnostics distinguishes verified health from
configuration presence. container_app_health performs a live /healthz
request and sets probe_performed: true; status: ok is used only for a
successful probe. Cosmos DB, Blob Storage, Service Bus, Application Insights,
and cost-governor entries report status: configured with
probe_performed: false when their configuration is present. They do not
claim connectivity, and the diagnostic omits endpoint, account, and connection
values. It also discards the /healthz response body. Missing optional
configuration reports status: not_configured. A failed live probe or invalid
cloud health configuration adds a failed cloud component and prevents the
overall MCP or A2A status from reporting healthy.
The response retains orphaned_stores_count, config_valid,
api_keys_configured, and warnings for compatibility and adds:
{
"status": "degraded",
"checks": [
{"component": "configuration", "status": "ok"},
{"component": "provider_keys", "status": "not_configured"},
{"component": "output_directory", "status": "ok"},
{"component": "audit_log", "status": "not_observed"}
],
"audit_log": {
"schema_version": "1.0",
"status": "not_observed",
"sink": "jsonl",
"write_attempted": false,
"read_attempted": false
}
}
healthy means all represented checks are ready, degraded means the process
is usable with a limitation or warning, and unhealthy means configuration
validation failed. Missing provider keys are degraded rather than unhealthy
because keyless prep and recon remain available. The audit component exposes
no path, event body, URL, caller id, or exception message. Configuration
validation details and output paths remain in server logs rather than this
read-scoped response.
clear_jobs¶
Clear stale pending jobs.
cancel_job¶
Cancel an active local research job. Primr first asks the supervised worker to
stop, then uses bounded process-tree termination if necessary. A successful
cancelled response is returned only after worker exit is observed. Repeating
the request is idempotent. Stopping the local worker does not prove that a
remote provider task stopped when that provider has no cancellation API.
Response:
{
"success": true,
"job_id": "job_abc123",
"status": "cancelled",
"worker_exit_confirmed": true,
"termination_method": "cooperative",
"message": "Job cancelled. Any partial artifacts have been preserved."
}
If worker exit cannot be confirmed, Primr returns
error_type: "cancellation_failed" and does not mark the job cancelled.
wait_for_status_change¶
Wait for an owned job's high-level status to change, or until a bounded timeout
expires. This avoids tight polling. timeout_seconds defaults to 60 and is
capped at 300.
{
"name": "wait_for_status_change",
"arguments": {
"job_id": "job_abc123",
"timeout_seconds": 60
}
}
The response includes changed, the previous and current status, current
stage, and stage progress. A terminal job returns immediately. Missing and
unowned jobs both return job_not_found.
show_usage¶
Read cloud control-plane spending and remaining budget for the current caller. The tool takes no arguments. Local mode returns a message explaining that local usage is not tracked by this cloud budget endpoint.
delegate_to_agent¶
Delegate a task to an external A2A agent. Requires pip install primr[a2a].
{
"name": "delegate_to_agent",
"arguments": {
"agent_url": "https://remote-agent.example.com",
"message": "Research Acme Corp competitive landscape",
"skill_id": "research_company"
}
}
Response (success):
Response (error):
SSRF protection validates all agent URLs. Private IPs, metadata endpoints, and non-HTTP schemes are blocked.
Prompts¶
governed_execution¶
Use this prompt when building a generic cost-aware MCP client. It encodes the default contract: estimate first, tell the user the action costs money, get explicit approval, pass max_estimated_cost_usd into spend tools, and treat research as a long-running async job.
research_workflow¶
Guided workflow for company research.
strategy_selection¶
Guided workflow for selecting and generating strategy documents.
A2A Server¶
Primr can also expose its capabilities via the A2A (Agent-to-Agent) protocol, allowing other agents to discover and invoke Primr's research tools.
# Install A2A support
pip install primr[a2a]
# Standalone A2A server (auth on; binds to 127.0.0.1 by default)
primr-a2a
# Local-development shortcut. --no-auth is refused unless --host is loopback,
# so accidentally exposing the A2A skill set on a public interface fails closed.
primr-a2a --host 127.0.0.1 --no-auth
# Co-hosted with MCP server
primr-mcp --http --a2a --a2a-port 9000
Agent Card (served at /.well-known/agent-card.json, with
/.well-known/agent.json kept as an alias):
Authenticated A2A requests use the same bearer-token identity and legacy
scope compatibility as MCP HTTP. read can estimate, inspect job status, and
check health. report is required to read report or strategy body text.
research is required to start paid work, run QA, or cancel an A2A research
task. Legacy write tokens still satisfy research for compatibility, but
it does not satisfy report.
Skills available via A2A:
| Skill ID | Required scope | Description |
|---|---|---|
estimate_research |
read |
Cost/time estimate plus approval-token fields for a research run |
research_company |
research |
Start async research (SSE streaming progress); requires max_estimated_cost_usd and the matching approval_token from estimate_research by default |
check_jobs |
read |
Current job status |
run_qa |
research |
Quality assessment on completed reports |
read_report_by_job |
report |
Explicit owned-job report or strategy body read with content_mode, artifact_type, and max_chars negotiation |
read_artifacts_by_job |
read |
Compact owned-job artifact metadata without report body content |
read_qa_summary_by_job |
read |
Compact owned-job QA summary metadata without detailed QA/report bodies |
read_usage_summary_by_job |
read |
Compact owned-job usage/cost metadata without approval tokens or report bodies |
read_source_summary_by_job |
read |
Compact owned-job source appendix metadata without report bodies |
read_trace_summary_by_job |
read |
Compact owned-job scrape trace metadata without URLs, raw trace entries, or page content |
read_verification_summary_by_job |
read |
Compact owned-job claim verification metadata without raw claims or source URLs |
read_calibration_summary_by_job |
read |
Compact owned-job label-calibration metadata without raw claims, source URLs, evidence reviews, or rationales |
read_stage_scorecard |
read |
Compact eval scorecard metadata by eval id |
system_health |
read |
System diagnostics |
Example A2A estimate message:
{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{"kind": "text", "text": "{\"url\": \"https://acme.com\", \"mode\": \"full\"}"}],
"metadata": {"skillId": "estimate_research"}
}
}
}
Use the returned estimated_cost_usd as max_estimated_cost_usd and pass the
returned approval_token into research_company.
Example A2A report read message:
{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{"kind": "text", "text": "{\"job_id\": \"job_abc123\", \"content_mode\": \"preview\", \"artifact_type\": \"report\", \"max_chars\": 2000}"}],
"metadata": {"skillId": "read_report_by_job"}
}
}
}
Use read_artifacts_by_job, read_qa_summary_by_job,
read_usage_summary_by_job, read_source_summary_by_job,
read_trace_summary_by_job, read_verification_summary_by_job, and
read_calibration_summary_by_job before requesting full report text when an
agent only needs metadata.
Example A2A research message:
{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{"kind": "text", "text": "{\"url\": \"https://acme.com\", \"name\": \"Acme\", \"mode\": \"full\", \"max_estimated_cost_usd\": 0.89, \"approval_token\": \"<token from estimate_research>\"}"}],
"metadata": {"skillId": "research_company"}
}
}
}
The A2A server shares the MCP server's SingleJobStore, rate limiter, auth
context, and security middleware. The single-job model is enforced across both
protocols. Authenticated A2A jobs are owned by the token client_id; local
unauthenticated loopback jobs keep the legacy a2a owner id. The internal
loopback marker cannot be selected by a JWT subject. A2A tasks/get requires
the exact request owner, and an unowned task id returns the same not-found
response as an unknown task id.
Skill invocations and task cancellation write privacy-preserving audit events
to the shared audit JSONL. Events include transport, skill name, outcome,
hashed message/result payloads, hashed caller id, granted scopes, duration,
job id when present, and sanitized estimate/cap metadata. They do not store
raw A2A message text, task ids, company URLs, report paths, approval tokens,
raw results, or caller ids.
Resources¶
The MCP server exposes primary read-only resources for job state, governance, audit, and output discovery. For agent clients, assume research is long-running and monitor/resume from job state rather than blocking on one request:
primr://research/status¶
Current research job status with progress information.
{
"status": "in_progress",
"job_id": "job_abc123",
"company_name": "Acme Corp",
"mode": "full",
"current_stage": "deep_research",
"stage_progress_percent": 45,
"stage_expected_minutes": 15,
"possibly_stuck": false
}
primr://research/next-actions¶
Recommended next action for the active or latest job.
{
"job_source": "active",
"job_id": "job_abc123",
"status": "in_progress",
"recommended_action": "monitor_job",
"message": "Research is still running. Monitor status instead of relaunching the job.",
"follow_up": [
"Read primr://research/status",
"Use wait_for_status_change for short blocking waits",
"Reconnect and resume monitoring if the client session drops"
]
}
primr://agent/governance¶
Default governance contract for generic MCP clients.
{
"schema_version": "1.0",
"principles": [
"Call estimate tools before any cost-incurring tool",
"Tell the user that research and strategy generation incur real API cost",
"Get explicit user approval before execution",
"Pass max_estimated_cost_usd into every cost-incurring tool",
"Pass the approval_token returned by the matching estimate tool",
"Treat Primr as a long-running async job system, not a synchronous request",
"Cost-governed MCP tools require max_estimated_cost_usd and approval_token by default"
],
"research_flow": {
"estimate_tool": "estimate_run",
"execute_tool": "research_company",
"cap_argument": "max_estimated_cost_usd",
"approval_argument": "approval_token",
"status_resource": "primr://research/status",
"wait_tool": "wait_for_status_change",
"expected_runtime": "standard runs are often 34-53 minutes; premium multi-vendor runs can reach 75-120 minutes",
"client_behavior": "launch once, then monitor and resume rather than waiting synchronously"
},
"strategy_flow": {
"estimate_tool": "estimate_strategy",
"execute_tool": "generate_strategy",
"cap_argument": "max_estimated_cost_usd",
"approval_argument": "approval_token"
},
"skill_pack_flow": {
"estimate_tool": "estimate_skill_pack",
"execute_tool": "generate_skill_pack",
"cap_argument": "max_estimated_cost_usd",
"approval_argument": "approval_token"
}
}
primr://agent/audit/recent¶
Recent privacy-preserving agent audit events for MCP tool calls, MCP resource
reads, and A2A skill calls. Local stdio callers can read this directly; HTTP
callers need admin scope. Events include request ids, body-free
OpenTelemetry span projections, hashes, and metadata, not raw tool arguments,
raw tool results, raw A2A message text, task ids, raw resource URI query
values, raw resource bodies, raw caller ids, report paths, URLs, or approval
tokens. The implementation reads at most the latest 1 MiB and returns at most
200 events. Registered tool names and scopes are allowlisted, resource kinds
are normalized, unknown identifiers are fixed labels or hashes, and encoded
events are limited to 16 KiB. Schema-invalid objects and incomplete oversized
tails are never returned and mark the sink degraded. Additive persisted fields
are discarded rather than reflected to the caller. Reads and writes reject
symbolic-link targets. audit_sink describes the most recent bounded read and
write state, including external replacement or truncation after a successful
write, without exposing the configured path or failure message.
{
"schema_version": "1.0",
"event_count": 3,
"events": [
{
"schema_version": "1.0",
"event_id": "0f3a...",
"request_id": "0f3a...",
"event_type": "tool_call",
"tool_name": "estimate_run",
"status": "success",
"transport": "stdio",
"actor": "stdio",
"client_id_hash": null,
"auth_scopes": [],
"args_hash": "sha256:...",
"result_hash": "sha256:...",
"approval_token_id": "12MvGGCWxWgTl-ii-z6wrw",
"estimated_cost_usd": 0.89,
"duration_ms": 8,
"otel_span": {
"name": "primr.stdio.tool_call.estimate_run",
"attributes": {
"primr.request_id": "0f3a...",
"primr.event_type": "tool_call",
"primr.transport": "stdio",
"primr.tool_name": "estimate_run",
"primr.status": "success",
"primr.duration_ms": 8
}
}
},
{
"schema_version": "1.0",
"event_id": "1a4b...",
"request_id": "1a4b...",
"event_type": "tool_call",
"tool_name": "a2a/check_jobs",
"status": "success",
"transport": "a2a",
"actor": null,
"client_id_hash": "sha256:...",
"auth_scopes": ["read"],
"args_hash": "sha256:...",
"result_hash": "sha256:...",
"duration_ms": 3,
"otel_span": {
"name": "primr.a2a.tool_call.a2a.check_jobs",
"attributes": {
"primr.request_id": "1a4b...",
"primr.transport": "a2a",
"primr.tool_name": "a2a/check_jobs",
"primr.status": "success"
}
}
},
{
"schema_version": "1.0",
"event_id": "2b5c...",
"request_id": "2b5c...",
"event_type": "resource_read",
"tool_name": "resources/read",
"status": "success",
"transport": "http",
"actor": null,
"client_id_hash": "sha256:...",
"auth_scopes": ["read"],
"args_hash": "sha256:...",
"result_hash": "sha256:...",
"resource_kind": "primr://output/calibration_summary/by_job/{job_id}",
"resource_uri_hash": "sha256:...",
"job_id": "42dc1447-bc80-4c36-9f7c-668b40ffdbd8",
"duration_ms": 4,
"otel_span": {
"name": "primr.http.resource_read.resources.read",
"attributes": {
"primr.request_id": "2b5c...",
"primr.job_id": "42dc1447-bc80-4c36-9f7c-668b40ffdbd8",
"primr.resource_kind": "primr://output/calibration_summary/by_job/{job_id}"
}
}
}
],
"audit_sink": {
"schema_version": "1.0",
"status": "ok",
"sink": "jsonl",
"file_observed": true,
"write_attempted": true,
"last_write_succeeded": true,
"read_attempted": true,
"last_read_succeeded": true,
"malformed_event_count": 0,
"read_truncated": false,
"incomplete_tail": false,
"file_replaced_after_successful_write": false,
"file_truncated_after_successful_write": false
}
}
primr://research/modes¶
Current mode guidance for integrations.
{
"schema_version": "1.0",
"default_mode": "full",
"default_mode_behavior": "Standard research pipeline. When XAI_API_KEY is available, Primr uses the Grok hybrid path by default. Use premium to force Gemini Deep Research.",
"cost_warning": "Research runs incur real API charges. Call estimate_run first and get explicit user approval before research_company.",
"search_defaults": {
"provider": "duckduckgo",
"search_api_key_required": false,
"google_custom_search_optional": true
}
}
primr://output/latest¶
Most recent research output. Local stdio callers can add
?full_content=true for complete content. Authenticated HTTP callers receive
metadata and, when a job is known, a report_read_uri; report bodies and
previews stay on primr://output/report/by_job/{job_id} even when the caller
holds the report scope.
{
"report_path": "output/Acme_Corp_Strategic_Overview.md",
"company_name": "Acme Corp",
"generation_timestamp": "2026-02-02T10:30:00",
"report_type": "markdown",
"content_preview": "# Acme Corp Strategic Overview...",
"content_preview_included": true,
"full_content_included": false,
"report_read_required": false
}
primr://output/report/by_job/{job_id}¶
Explicit report-body retrieval for one owned job. HTTP callers must own the job
and hold the report scope. This is the preferred path when an agent needs
report text because it separates status monitoring from content consumption and
supports bounded output negotiation.
Query parameters:
content_mode:metadata,preview, orfull(defaultpreview)artifact_type:report,strategy, orall(defaultreport)max_chars: positive character limit, capped by the server
{
"schema_version": "1.0",
"job_id": "job_abc123",
"company_name": "Acme Corp",
"status": "completed",
"content_mode": "preview",
"artifact_type_filter": "report",
"max_chars": 2000,
"artifact_count": 1,
"content_included": true,
"full_content_included": false,
"artifacts": [
{
"type": "strategic_overview",
"filename": "Acme_Corp_Strategic_Overview_06-30-2026.md",
"size_bytes": 184320,
"content_hash": "sha256:abc123...",
"content_included": true,
"content": "# Acme Corp Strategic Overview...",
"content_chars": 2000,
"content_truncated": true,
"full_content_included": false
}
]
}
Insufficient-scope responses do not include report text:
{
"error": "insufficient_scope",
"message": "Report content requires the report scope.",
"job_id": "job_abc123",
"required_scopes": ["report"],
"granted_scopes": ["read"],
"full_content_included": false,
"content_included": false
}
primr://output/artifacts¶
Pipeline stage artifacts for the active job or latest terminal job. This
legacy resource includes short previews and is useful for local interactive
review. Prefer primr://output/artifacts/by_job/{job_id} for agent automation
that only needs a compact inventory, and
primr://output/qa_summary/by_job/{job_id} when the client only needs QA
metadata, and primr://output/usage_summary/by_job/{job_id} when the client
only needs cost, timing, approval, or artifact-count metadata, and
primr://output/source_summary/by_job/{job_id} when the client only needs
citation/source appendix metadata, and
primr://output/trace_summary/by_job/{job_id} when the client only needs
scrape trace health metadata, and
primr://output/verification_summary/by_job/{job_id} when the client only
needs claim verification metadata, and
primr://output/calibration_summary/by_job/{job_id} when the client only
needs label-calibration metadata, including report-only inference source-copy
counts.
{
"job_id": "job_abc123",
"job_status": "completed",
"artifacts": [
{
"artifact_type": "scraped_content",
"file_path": "output/acme_corp/scraped_content.txt",
"size_bytes": 125000,
"preview": "Acme Corp designs...",
"content_hash": "sha256:abc123..."
}
]
}
primr://output/artifacts/by_job/{job_id}¶
Compact, ownership-gated artifact metadata for one job. This resource returns file names, paths, sizes, hashes, timestamps, physical classifications, semantic roles, and missing-file state without report body content. Use it before requesting full report content or broad output previews.
HTTP callers can read only jobs owned by the authenticated client. Missing jobs
and unowned jobs return the same job_not_found shape so clients cannot probe
for other job ids.
{
"schema_version": "1.1",
"resource": "primr://output/artifacts/by_job",
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"artifact_count": 3,
"full_content_included": false,
"artifacts": [
{
"index": 0,
"artifact_type": "report_markdown",
"artifact_role": "primary_report",
"file_name": "Acme_Corp_Strategic_Overview_06-28-2026.md",
"file_path": "output/acme_corp/Acme_Corp_Strategic_Overview_06-28-2026.md",
"exists": true,
"size_bytes": 184320,
"modified_at": "2026-06-28T18:30:00+00:00",
"content_hash": "sha256:abc123..."
},
{
"index": 1,
"artifact_type": "run_manifest",
"artifact_role": "run_metadata",
"file_name": "run_manifest.json",
"file_path": "output/acme_corp/run_manifest.json",
"exists": true,
"size_bytes": 4096,
"modified_at": "2026-06-28T18:30:01+00:00",
"content_hash": "sha256:def456..."
},
{
"index": 2,
"artifact_type": "report_docx",
"artifact_role": "primary_report",
"file_name": "Acme_Corp_Strategic_Overview_06-28-2026.docx",
"file_path": "output/acme_corp/Acme_Corp_Strategic_Overview_06-28-2026.docx",
"exists": false
}
]
}
Error responses:
{
"error": "no_artifacts",
"message": "Job job_abc123 has no output artifacts yet",
"job_id": "job_abc123",
"status": "running"
}
primr://output/qa_summary/by_job/{job_id}¶
Compact, ownership-gated QA artifact summary for one job. This resource reads
attached QA JSON sidecars and current text QA reports classified as
qa_summary, then returns score, status, count, parse, hash, timestamp, and
top-level-key metadata without returning detailed issue, recommendation, or
report body text.
HTTP callers can read only jobs owned by the authenticated client. Missing jobs
and unowned jobs return the same job_not_found shape so clients cannot probe
for other job ids. Malformed QA JSON returns metadata plus parse_error
without echoing the malformed body.
{
"schema_version": "1.0",
"resource": "primr://output/qa_summary/by_job",
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"summary_count": 1,
"full_content_included": false,
"summaries": [
{
"index": 2,
"artifact_type": "qa_summary",
"file_name": "Acme_Corp_QA_Report.json",
"file_path": "output/acme_corp/Acme_Corp_QA_Report.json",
"exists": true,
"size_bytes": 2048,
"modified_at": "2026-06-28T18:45:00+00:00",
"content_hash": "sha256:abc123...",
"parsed": true,
"full_content_included": false,
"top_level_keys": ["issues", "overall_score", "ready_for_use", "status"],
"status_fields": {
"ready_for_use": true,
"status": "passed"
},
"score_fields": {
"overall_score": 91
},
"count_fields": {
"issues_count": 0
}
}
]
}
No QA summary response:
{
"error": "qa_summary_not_found",
"message": "Job job_abc123 has no attached QA summary artifact",
"job_id": "job_abc123",
"status": "completed",
"summary_count": 0
}
primr://output/usage_summary/by_job/{job_id}¶
Compact, ownership-gated usage and cost summary for one job. This resource
reads run_manifest.json files adjacent to the owned job's output artifacts
and returns cost, timing, approval, budget-enforcement, execution, parse,
hash, timestamp, and artifact-count metadata without returning company URL,
approval token, the manifest artifact list, or full manifest content.
Completed research manifests contain run-scoped actual model usage plus the
flat Deep Research tasks accepted during that run, including optional
verification performed before completion. actual_cost_usd remains null for
cancellation and failures that cannot be measured. A failed Premium run can
report reconciled spend when its paid partial report was durably published.
HTTP callers can read only jobs owned by the authenticated client. Missing jobs
and unowned jobs return the same job_not_found shape so clients cannot probe
for other job ids. Malformed manifests return metadata plus parse_error
without echoing the malformed body.
{
"schema_version": "1.0",
"resource": "primr://output/usage_summary/by_job",
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"summary_count": 1,
"full_content_included": false,
"summaries": [
{
"index": 0,
"artifact_type": "run_manifest",
"file_name": "run_manifest.json",
"file_path": "output/acme_corp/run_manifest.json",
"exists": true,
"size_bytes": 4096,
"modified_at": "2026-06-28T20:30:00+00:00",
"content_hash": "sha256:abc123...",
"parsed": true,
"full_content_included": false,
"manifest_schema_version": "1.1",
"mode": "full",
"estimate": {
"cost_usd": 0.76,
"time_minutes": 42,
"estimated_at": "2026-06-28T19:00:00Z"
},
"approval": {
"approved": true,
"approved_at": "2026-06-28T19:01:00Z",
"bound_to_estimate": true,
"approved_by_present": true,
"token_present": false
},
"budget": {
"approved_ceiling_usd": 0.80,
"runtime_budget_active": true,
"preflight": "refuses to start when the estimated cost exceeds the ceiling",
"runtime_checkpoints": true,
"runtime": "runtime checkpoint is active before and between optional strategy documents after required Deep Research completes; the required Deep Research task cannot be stopped mid-flight",
"checkpointed_stages": ["optional strategy generation"],
"non_interruptible_required_tasks": ["required Deep Research task"]
},
"execution": {
"started_at": "2026-06-28T19:02:00Z",
"completed_at": "2026-06-28T19:44:00Z",
"status": "completed",
"actual_cost_usd": 0.83,
"actual_time_minutes": 42
},
"artifact_count": 3
}
]
}
No manifest response:
{
"error": "usage_summary_not_found",
"message": "Job job_abc123 has no run manifest available",
"job_id": "job_abc123",
"status": "completed",
"summary_count": 0
}
primr://output/source_summary/by_job/{job_id}¶
Compact, ownership-gated source appendix summary for one job. This resource reads owned markdown and text report artifacts, parses the source appendix, and returns citation counts, source definition counts, missing and unused citation numbers, duplicate URL counts, source domains, and source URLs without returning report body content.
HTTP callers can read only jobs owned by the authenticated client. Missing jobs
and unowned jobs return the same job_not_found shape so clients cannot probe
for other job ids.
{
"schema_version": "1.0",
"resource": "primr://output/source_summary/by_job",
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"summary_count": 1,
"full_content_included": false,
"summaries": [
{
"index": 0,
"artifact_type": "report_markdown",
"file_name": "Acme_Corp_Strategic_Overview_06-28-2026.md",
"file_path": "output/acme_corp/Acme_Corp_Strategic_Overview_06-28-2026.md",
"exists": true,
"size_bytes": 184320,
"modified_at": "2026-06-28T20:30:00+00:00",
"content_hash": "sha256:abc123...",
"parsed": true,
"source_format": "markdown",
"source_section_present": true,
"full_content_included": false,
"inline_reference_count": 12,
"referenced_numbers": [1, 2, 3],
"definition_count": 3,
"valid_source_count": 3,
"invalid_source_count": 0,
"duplicate_url_count": 0,
"missing_definition_numbers": [],
"unused_definition_numbers": [],
"domains": [
{"domain": "acme.example", "count": 2},
{"domain": "sec.gov", "count": 1}
],
"sources": [
{
"reference": 1,
"url": "https://acme.example/news",
"domain": "acme.example",
"title": "Acme newsroom"
}
]
}
]
}
No report artifact response:
{
"error": "source_summary_not_found",
"message": "Job job_abc123 has no report artifact available for source summary",
"job_id": "job_abc123",
"status": "completed",
"summary_count": 0
}
primr://output/trace_summary/by_job/{job_id}¶
Compact, ownership-gated scrape trace summary for one job. Same-run trace JSONL files are attached to job metadata when present. This resource parses those trace artifacts and returns tier attempts, success rates, latency summaries, block counts, HTTP status counts, and validation health without returning URLs, final URLs, raw trace entries, or page content.
HTTP callers can read only jobs owned by the authenticated client. Missing jobs
and unowned jobs return the same job_not_found shape so clients cannot probe
for other job ids.
{
"schema_version": "1.0",
"resource": "primr://output/trace_summary/by_job",
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"summary_count": 1,
"full_content_included": false,
"summaries": [
{
"index": 0,
"artifact_type": "scrape_trace",
"file_name": "Acme_Corp_20260628_213000.jsonl",
"file_path": "logs/scrape_traces/Acme_Corp_20260628_213000.jsonl",
"exists": true,
"size_bytes": 8192,
"modified_at": "2026-06-28T21:30:00+00:00",
"content_hash": "sha256:abc123...",
"parsed": true,
"trace_schema_version": "1.1",
"trace_run_id": "trace-run-1",
"trace_started_at": "2026-06-28T21:00:00",
"full_content_included": false,
"raw_entries_included": false,
"urls_included": false,
"entry_count": 12,
"success_count": 10,
"failure_count": 2,
"success_rate": 0.8333333333333334,
"blocked_count": 1,
"block_type_counts": [{"value": "hard_block", "count": 1}],
"http_status_counts": [{"value": "200", "count": 10}],
"tier_summaries": [
{
"tier": "requests",
"attempts": 12,
"successes": 8,
"success_rate": 0.6666666666666666,
"avg_latency_ms": 125.0,
"p95_latency_ms": 250.0
}
],
"avg_text_length": 4200.0,
"thin_page_count": 1,
"validated_page_count": 9,
"valid_page_count": 8,
"content_valid_rate": 0.8888888888888888
}
]
}
No trace artifact response:
{
"error": "trace_summary_not_found",
"message": "Job job_abc123 has no scrape trace artifact available",
"job_id": "job_abc123",
"status": "completed",
"summary_count": 0
}
primr://output/verification_summary/by_job/{job_id}¶
Compact, ownership-gated claim verification summary for one job. Same-run
verification.json artifacts are attached to job metadata when MCP
verification runs, including fast-mode MCP runs. This resource parses those
verification artifacts and returns trust score, claim counts, status counts,
first-party downgrade counts, and source-reference counts without returning
raw claims, source URLs, search queries, explanations, or report body content.
HTTP callers can read only jobs owned by the authenticated client. Missing jobs
and unowned jobs return the same job_not_found shape so clients cannot probe
for other job ids.
{
"schema_version": "1.0",
"resource": "primr://output/verification_summary/by_job",
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"summary_count": 1,
"full_content_included": false,
"summaries": [
{
"index": 1,
"artifact_type": "verification_summary",
"file_name": "verification.json",
"file_path": "output/acme_corp/verification.json",
"exists": true,
"size_bytes": 4096,
"modified_at": "2026-06-28T21:45:00+00:00",
"content_hash": "sha256:abc123...",
"parsed": true,
"full_content_included": false,
"raw_claim_results_included": false,
"source_urls_included": false,
"search_queries_included": false,
"trust_score": 0.88,
"trust_percentage": 88,
"verification_gate": "PASS",
"total_claims": 25,
"verified_count": 22,
"unverified_count": 3,
"contradicted_count": 0,
"claim_result_count": 25,
"claim_status_counts": [
{"value": "verified", "count": 22},
{"value": "unverified", "count": 3}
],
"first_party_downgrade_count": 1,
"source_reference_count": 47
}
]
}
No verification artifact response:
{
"error": "verification_summary_not_found",
"message": "Job job_abc123 has no verification summary artifact available",
"job_id": "job_abc123",
"status": "completed",
"summary_count": 0
}
primr://output/calibration_summary/by_job/{job_id}¶
Compact, ownership-gated label-calibration summary for one job. This resource
summarizes attached .calibration.json artifacts, plus calibration sidecars
adjacent to owned report artifacts using the standard
<report filename>.calibration.json naming convention. It returns per-label
traceability counts, report-only inference source-copy counts, evidence-review
count buckets, judge provenance, and cloud-vs-local judge-agreement metadata
without returning raw claims, source URLs, evidence reviews, rationales, or
report body content.
HTTP callers can read only jobs owned by the authenticated client. Missing jobs
and unowned jobs return the same job_not_found shape so clients cannot probe
for other job ids.
{
"schema_version": "1.0",
"resource": "primr://output/calibration_summary/by_job",
"job_id": "job_abc123",
"status": "completed",
"company_name": "Acme Corp",
"summary_count": 1,
"full_content_included": false,
"summaries": [
{
"index": 0,
"artifact_type": "calibration_sidecar",
"file_name": "Acme_Corp_Strategic_Overview_06-28-2026.md.calibration.json",
"file_path": "output/acme_corp/Acme_Corp_Strategic_Overview_06-28-2026.md.calibration.json",
"exists": true,
"size_bytes": 6144,
"modified_at": "2026-06-28T22:00:00+00:00",
"content_hash": "sha256:abc123...",
"parsed": true,
"full_content_included": false,
"raw_claims_included": false,
"claim_text_included": false,
"source_urls_included": false,
"evidence_reviews_included": false,
"rationales_included": false,
"report_file": "Acme_Corp_Strategic_Overview_06-28-2026.md",
"max_per_label": 10,
"judge": {
"kind": "local",
"model": "qwen2.5:14b"
},
"judge_agreement": {
"scope": "report",
"local_model": "qwen2.5:14b",
"compared": 4,
"agreed": 3,
"agreement": 0.75
},
"label_count": 2,
"claim_result_count": 5,
"claims_sampled": 5,
"decidable_claims": 3,
"traceable_count": 2,
"untraceable_count": 1,
"no_source_count": 0,
"unfetchable_count": 0,
"exempt_count": 1,
"source_copied_count": 1,
"per_label": [
{
"label": "Confirmed",
"sampled": 3,
"traceable": 2,
"untraceable": 1,
"no_source": 0,
"unfetchable": 0,
"exempt": 0,
"source_copied": 0,
"decidable": 3,
"precision": 0.667
},
{
"label": "Hypothesis",
"sampled": 2,
"traceable": 0,
"untraceable": 0,
"no_source": 0,
"unfetchable": 0,
"exempt": 1,
"source_copied": 1,
"decidable": 0,
"precision": null
}
],
"validation_rubric": {
"claims_with_reviews": 3,
"source_reviews": 5,
"support_counts": [
{"value": "supported", "count": 4},
{"value": "unsupported", "count": 1}
],
"dimension_counts": [
{
"dimension": "reasoning_strength",
"counts": [
{"value": "strong", "count": 4},
{"value": "partial", "count": 1}
]
}
]
}
}
]
}
No calibration sidecar response:
{
"error": "calibration_summary_not_found",
"message": "Job job_abc123 has no calibration sidecar available",
"job_id": "job_abc123",
"status": "completed",
"summary_count": 0
}
primr://config¶
Current configuration (no secrets exposed).
{
"available_modes": ["scrape", "deep", "full", "premium"],
"available_strategies": {
"ai_strategy": "Business-first AI portfolio, economics, operating model, architecture, and governance",
"customer_experience": "CX improvement plan",
"modern_security_compliance": "Security posture assessment",
"data_fabric_strategy": "Data platform modernization",
"skills": "Skills ideation (roles x skills hypothesis)"
},
"configured_vendors": ["azure", "aws", "gcp"]
}
primr://strategies/available¶
List of available strategy types with metadata for Open Claw integration.
{
"schema_version": "1.0",
"cost_warning": "Strategy generation incurs real API charges. Surface the current estimate and get explicit user approval before generate_strategy.",
"strategies": [
{
"id": "ai_strategy",
"name": "AI Strategy",
"description": "Business-first AI portfolio, economics, operating model, architecture, and governance",
"requires_platform": true,
"estimated_time_minutes": 15,
"estimated_cost_usd": 2.5,
"cost_basis": "Planning estimate for one standard Gemini Deep Research task; actual token and tool usage varies."
},
{
"id": "customer_experience",
"name": "Customer Experience Strategy",
"description": "CX transformation and digital experience improvement plan",
"requires_platform": false,
"estimated_time_minutes": 12,
"estimated_cost_usd": 2.5,
"cost_basis": "Planning estimate for one standard Gemini Deep Research task; actual token and tool usage varies."
},
{
"id": "modern_security_compliance",
"name": "Security & Compliance Strategy",
"description": "Zero Trust architecture and compliance posture assessment",
"requires_platform": false,
"estimated_time_minutes": 12,
"estimated_cost_usd": 2.5,
"cost_basis": "Planning estimate for one standard Gemini Deep Research task; actual token and tool usage varies."
},
{
"id": "data_fabric_strategy",
"name": "Data Fabric Strategy",
"description": "Modern data platform for agentic AI and semantic layers",
"requires_platform": false,
"estimated_time_minutes": 12,
"estimated_cost_usd": 2.5,
"cost_basis": "Planning estimate for one standard Gemini Deep Research task; actual token and tool usage varies."
},
{
"id": "skills",
"name": "Skills Ideation",
"description": "Top-5 roles x top-3 skills hypothesis grounded in research signals",
"requires_platform": false,
"estimated_time_minutes": 8,
"estimated_cost_usd": 2.5,
"cost_basis": "Planning estimate for one standard Gemini Deep Research task; actual token and tool usage varies."
}
]
}
primr://output/by_job/{job_id}¶
Job-scoped output metadata and gated report preview for provenance tracking.
Ensures any returned preview corresponds to a specific approved job.
Authenticated HTTP callers need the report scope to receive
content_preview; otherwise the response returns report_read_required=true
and points to primr://output/report/by_job/{job_id}. Use
primr://output/artifacts/by_job/{job_id} first when a client only needs
artifact metadata and not report text. Use
primr://output/qa_summary/by_job/{job_id} first when a client only needs QA
outcome metadata. Use primr://output/usage_summary/by_job/{job_id} first
when a client only needs run cost, timing, approval, or artifact-count metadata.
Use primr://output/source_summary/by_job/{job_id} first when a client only
needs citation/source appendix metadata.
Use primr://output/trace_summary/by_job/{job_id} first when a client only
needs scrape trace health metadata without URLs, raw trace entries, or page
content.
Use primr://output/verification_summary/by_job/{job_id} first when a client
only needs claim verification metadata without raw claims, source URLs, search
queries, explanations, or report body content.
Use primr://output/calibration_summary/by_job/{job_id} first when a client
only needs label-calibration metadata, including inference source-copy counts,
without raw claims, source URLs, evidence reviews, rationales, or report body
content.
{
"job_id": "abc123",
"report_path": "output/acme_corp/report.md",
"company_name": "Acme Corp",
"generation_timestamp": "2026-02-15T10:31:00Z",
"report_type": "markdown",
"content_preview": "# Acme Corp Strategic Overview...",
"content_preview_included": true,
"report_read_required": false,
"report_read_uri": "primr://output/report/by_job/abc123",
"status": "completed"
}
primr://output/manifest/latest¶
Run manifest for the most recent completed job. Provides audit trail for compliance and debugging.
{
"schema_version": "1.1",
"job_id": "abc123",
"company_name": "Acme Corp",
"company_url": "https://acme.example",
"mode": "full",
"estimate": {
"cost_usd": 0.75,
"time_minutes": 30,
"estimated_at": "2026-02-15T10:00:00Z"
},
"approval": {
"token": null,
"approval_token_id": "approval-abc123",
"approved_at": "2026-02-15T10:01:00Z",
"approved_by": "stdio",
"bound_to_estimate": true
},
"budget": {
"approved_ceiling_usd": 0.80,
"runtime_budget_active": true,
"enforcement": {
"preflight": "refuses to start when the estimated cost exceeds the ceiling",
"runtime_checkpoints": true,
"runtime": "runtime checkpoint is active before and between optional strategy documents after required Deep Research completes; the required Deep Research task cannot be stopped mid-flight",
"checkpointed_stages": ["optional strategy generation"],
"non_interruptible_required_tasks": ["required Deep Research task"]
}
},
"execution": {
"started_at": "2026-02-15T10:01:05Z",
"completed_at": "2026-02-15T10:31:00Z",
"status": "completed",
"actual_cost_usd": 0.78,
"actual_time_minutes": 30
},
"artifacts": [
"output/acme_corp/report.md",
"output/acme_corp/scraped_content.txt",
"output/acme_corp/insights.txt"
]
}
Prompt Templates¶
Two prompt templates are available for guided workflows:
research_workflow¶
Guides through the complete research process.
strategy_selection¶
Helps select appropriate strategy types based on company context.
Security¶
The MCP server includes comprehensive security features:
Path Validation¶
All file paths are validated to prevent path traversal attacks:
- Paths must be relative to workspace root
- Symlinks are resolved and checked
- .. sequences are blocked
URL Validation¶
URLs are validated to prevent SSRF attacks: - Only HTTP/HTTPS schemes allowed - Private/internal IPs blocked (10.x, 172.16-31.x, 192.168.x, 127.x) - DNS rebinding protection
Rate Limiting¶
Per-tool rate limits prevent abuse:
- estimate_run: 30 requests/minute
- estimate_strategy: 30 requests/minute
- research_company: 2 requests/minute
- Other tools: 10 requests/minute
Authentication (HTTP mode)¶
JWT authentication for HTTP transport:
- Tokens verified via JWKS endpoint or shared secret
- Admin policy: role=admin claim or MCP_ADMIN_TOKENS env var
- Client ID extracted for rate limiting and job ownership
Job Store¶
The MCP server uses a single-job model with journal persistence:
from primr.mcp_server.job_store import SingleJobStore
store = SingleJobStore(journal_path="logs/mcp_journal.json")
# Create a job
job = store.create(company_name="Acme Corp", mode="full", owner_client_id="client1")
# Update progress
job.advance_stage(ResearchStage.DEEP_RESEARCH)
job.heartbeat(progress=50)
store.update(job)
# Check for stuck jobs
if job.is_possibly_stuck():
print("Job may be stuck - no heartbeat in 5+ minutes")
# Get active job
active = store.get_active()
# Get latest completed job
terminal = store.get_latest_terminal()
Graceful Shutdown¶
The server handles shutdown gracefully:
- Requests cooperative stop for each supervised worker, then escalates through bounded process-tree termination and waits for worker exit.
- Waits for remaining controller tasks within the shutdown budget, then cancels tasks that have not settled.
- Marks any residual active job without an owned worker as failed with
error_type="server_shutdown"and persists the journal. - Uses a 5-second worker-shutdown budget inside a 10-second total shutdown budget.
Error Codes¶
Standard error codes returned by tools:
| Code | Description |
|---|---|
INVALID_URL |
URL format invalid |
SSRF_BLOCKED |
URL blocked for security |
URL_UNREACHABLE |
URL could not be reached |
PATH_TRAVERSAL_BLOCKED |
Path traversal attempt blocked |
REPORT_NOT_FOUND |
Report file not found |
JOB_NOT_FOUND |
Job ID not found |
JOB_IN_PROGRESS |
Another job already running |
RATE_LIMIT_EXCEEDED |
Rate limit exceeded |
Agentic Architecture¶
Primr's agentic architecture, introduced in v1.7.0 and expanded since, enables AI agents to drive research workflows with persistent memory, hypothesis tracking, governance hooks, and MCP resources.
Tracked Company Profiles¶
Track local company profiles in the per-user data directory. Profiles are JSON
metadata under <per-user data dir>/company_profiles, relocated by
PRIMR_DATA_DIR, and currently store URL, freshness status, run pointers, and
retention classification without introducing a database. Run pointers are
body-free references to owned artifacts; report bodies and raw source content
stay outside the profile JSON.
primr company track "Acme Corp" https://acme.example
primr company list
primr company show "Acme Corp"
primr company export "Acme Corp"
from primr.agentic import CompanyProfileStore
store = CompanyProfileStore()
profile = store.track("Acme Corp", "https://acme.example")
profile = store.record_run(
"Acme Corp",
"job-20260630-acme",
artifacts=["output/acme/report.md"],
manifest_path="output/acme/run_manifest.json",
)
print(profile.freshness_status)
Research Memory¶
Track hypotheses across research sessions with confidence levels.
from primr.agentic.memory import ResearchMemory
from primr.agentic.models import ConfidenceLevel, Hypothesis
memory = ResearchMemory()
hypothesis = Hypothesis(
id="h_001",
claim="Acme is expanding into AI-powered logistics",
confidence=ConfidenceLevel.UNTESTED,
topic="strategy",
)
memory.save_hypotheses("Acme Corp", [hypothesis])
# Add evidence and persist the updated hypothesis.
hypothesis.validate("The Q3 earnings call describes an AI logistics initiative.")
memory.save_hypotheses("Acme Corp", [hypothesis])
for item in memory.get_hypotheses("Acme Corp"):
print(f"[{item.confidence.value}] {item.claim}")
companies = memory.list_companies()
Confidence Levels¶
| Level | Description |
|---|---|
UNTESTED |
Initial state with no evidence gathered |
VALIDATED |
Evidence supports the hypothesis |
INVALIDATED |
Evidence contradicts the hypothesis |
CONFIRMED |
Strong evidence confirms the hypothesis |
Roadmap API¶
Query the development roadmap programmatically.
from primr.agentic.roadmap_api import RoadmapAPI
from primr.agentic.models import VersionStatus
api = RoadmapAPI()
# Get current version
current = api.get_current_version()
print(f"Current: v{current.number} - {current.title}")
# Get next planned version
next_ver = api.get_next_version()
# List versions by status
completed = api.list_by_status(VersionStatus.COMPLETED)
planned = api.list_by_status(VersionStatus.PLANNED)
# Get specific roadmap-band details
v2 = api.get_version("2.0")
if v2:
for feature in v2.features:
print(f" - {feature.name}: {feature.description}")
# Search features
results = api.search_features("memory")
for version, feature in results:
print(f"v{version.number}: {feature.name}")
Hook System¶
Register governance hooks for cost control and security.
from primr.agentic import (
CostGuardHook,
HookContext,
HookResult,
HookSystem,
HookType,
SSRFGuardHook,
)
# Create hook system
hooks = HookSystem()
# Register cost guard (blocks operations exceeding budget)
hooks.register(CostGuardHook(max_cost_usd=5.0))
# Register SSRF guard (blocks internal URLs)
hooks.register(SSRFGuardHook())
# Execute hooks before an operation
context = HookContext(
hook_type=HookType.PRE_TOOL_USE,
stage_name="scrape",
arguments={
"url": "https://acme.example",
"estimated_cost_usd": 2.50,
},
)
response = await hooks.run_pre_hooks("scrape", context)
if response.result is HookResult.BLOCK:
print(f"Operation blocked: {response.message}")
else:
await run_scrape(context.arguments)
Custom Hooks¶
import logging
from primr.agentic import (
Hook,
HookContext,
HookResponse,
HookResult,
HookType,
)
logger = logging.getLogger(__name__)
class AuditHook(Hook):
"""Log all operations for audit trail."""
@property
def hook_type(self) -> HookType:
return HookType.PRE_TOOL_USE
async def execute(self, context: HookContext) -> HookResponse:
logger.info("Operation: %s", context.stage_name or context.tool_name)
return HookResponse(result=HookResult.ALLOW)
hooks.register(AuditHook())
Subagent Architecture¶
Specialized subagents for different research tasks.
from pathlib import Path
from primr.agentic.subagents import ScraperSubagent, SubagentContext
context = SubagentContext(
company_name="Acme Corp",
company_url="https://acme.example",
working_dir=Path("./working/acme"),
)
scraper = ScraperSubagent(context)
result = await scraper.execute()
if result.is_success and result.data is not None:
print(f"Scraped {result.data.pages_scraped} pages")
print(f"Corpus: {result.data.corpus_path}")
else:
print(f"Failed: {result.error}")
Available Subagents¶
| Subagent | Purpose |
|---|---|
ScraperSubagent |
Website scraping with tier escalation |
AnalystSubagent |
Deep research and hypothesis generation |
WriterSubagent |
Report generation from research data |
QASubagent |
Quality assessment and scoring |
VerifierSubagent |
Claim verification and trust scoring |
Research Orchestrator¶
Coordinate subagents through the research pipeline.
from primr.agentic.orchestrator import (
ResearchOrchestrator,
OrchestratorConfig,
OrchestratorResult,
)
from primr.agentic.memory import ResearchMemory
from primr.agentic import HookSystem, CostGuardHook
# Configure orchestrator
config = OrchestratorConfig(
output_dir=Path("./output"),
fail_fast=False, # Continue on non-critical failures
)
# Initialize with memory and hooks
memory = ResearchMemory()
hooks = HookSystem()
hooks.register(CostGuardHook(max_cost_usd=10.0))
orchestrator = ResearchOrchestrator(
config=config,
memory=memory,
hook_system=hooks,
)
# Run orchestrated research (mode="full" succeeds only when a report path exists)
result: OrchestratorResult = await orchestrator.research(
company_name="Acme Corp",
company_url="https://acme.example",
mode="full",
)
if result.is_success and result.report_path:
print(f"Report: {result.report_path}")
print(f"Hypotheses: {len(result.hypotheses)}")
print(f"Stages: {result.completed_stages}")
else:
print(f"Errors: {result.errors}")
MCP Agentic Tools¶
Additional MCP tools for agentic workflows.
query_roadmap¶
Query roadmap versions and features.
Response:
{
"version": "2.0",
"title": "primr as a composable, cost-tunable research *role*",
"status": "planned",
"features": [
{"name": "Backend freedom", "status": "planned"},
{"name": "Memory", "status": "planned"},
{"name": "Interoperability", "status": "planned"}
],
"blockers": ["Depends on v1.x (in_progress)"],
"dependencies": ["1.x"]
}
get_hypotheses¶
Retrieve hypotheses for a company from research memory.
Response:
{
"company": "Acme Corp",
"hypotheses": [
{
"id": "h_001",
"claim": "Acme is expanding into AI-powered logistics",
"confidence": "validated",
"evidence": ["The Q3 earnings call describes an AI logistics initiative."],
"created_at": "2026-07-12T10:30:00",
"updated_at": "2026-07-12T10:45:00",
"expires_at": null,
"topic": "strategy"
}
],
"count": 1
}
save_hypothesis¶
Save a hypothesis to research memory.
{
"name": "save_hypothesis",
"arguments": {
"company": "Acme Corp",
"hypothesis_id": "h_002",
"claim": "Acme plans to acquire a logistics startup",
"confidence": "untested",
"evidence": "Rumored in industry newsletter",
"topic": "m&a"
}
}
Response for a new hypothesis:
MCP Agentic Resources¶
Additional MCP resources for agentic workflows.
primr://roadmap¶
Current roadmap with versions, features, and inferred dependencies. Selected fields from the current response are shown below.
{
"current_version": "1.x",
"next_version": "2.0",
"versions": [
{
"number": "1.x",
"title": "the excellent single-shot brief",
"status": "in_progress"
},
{
"number": "2.0",
"title": "primr as a composable, cost-tunable research *role*",
"status": "planned"
},
{
"number": "3.0",
"title": "the research frontier, same guardrails",
"status": "planned",
"dependencies": ["2.0"]
}
],
"dependency_graph": {
"1.x": [],
"2.0": ["1.x"],
"3.0": ["2.0"]
}
}
primr://memory/{company}¶
Research memory for a specific company.
{
"company_name": "Acme Corp",
"hypotheses": [
{
"id": "h_001",
"claim": "Acme is expanding into AI-powered logistics",
"confidence": "validated",
"evidence": ["The Q3 earnings call describes an AI logistics initiative."],
"created_at": "2026-07-12T10:30:00",
"updated_at": "2026-07-12T10:45:00",
"expires_at": null,
"topic": "strategy"
}
],
"scrape_patterns": [],
"research_notes": [],
"last_researched": "2026-07-12T10:45:00+00:00"
}
primr://context¶
AGENTS.md context-map summary for development agents (CLAUDE.md only imports AGENTS.md). quick_start is a string containing at most the first 1,000 characters of that section, or null when the section is absent.
{
"context_map_path": "AGENTS.md",
"summary": {
"sections": [
"Quick Start",
"Language and runtime choices",
"Architecture Pointers",
"Use the one seam - don't invent a sixth way",
"Negative Constraints",
"Verification Commands",
"CLI verb convention",
"Git / PR"
],
"has_quick_start": true,
"has_negative_constraints": true,
"has_verification_commands": true,
"has_progressive_disclosure": true
},
"full_content_available": true,
"quick_start": "primr turns a company URL into a sourced strategic brief..."
}
CLI Commands¶
New CLI commands for agentic workflows:
# Research memory
primr memory "Acme Corp" # View hypotheses for a company
primr --memory-list # List all companies with memory
# Orchestrated research (experimental; still billable — cost gate required)
primr orchestrate "Acme Corp" https://acme.example --dry-run
primr orchestrate "Acme Corp" https://acme.example --max-cost 5.0
# Roadmap
primr roadmap # Show roadmap overview
primr --roadmap-version v2.0 # Show version details
Skills Directory¶
Pre-built workflow definitions in skills/:
| Skill | Description |
|---|---|
company-research |
Full pipeline with memory integration |
scrape-strategy |
Tier selection and error handling |
hypothesis-tracking |
Confidence level management |
qa-iteration |
Section refinement workflow |
Each skill includes a SKILL.md with workflow steps, decision points, and example usage.