StockResearchAgents

Evidence-first company research for agent harnesses, with versioned contracts, deterministic validation and analytics, durable lifecycle controls, and completed-only dossiers.

Prototype research only. Not financial advice. StockResearchAgents has no broker integration and cannot submit, modify, approve, cancel, or fill an order. Investment-style output is explicitly non-executable (non_executable: true); it is an analytical scenario, never an action.

StockResearchAgents gives an MCP-capable harness or custom application a strict research workflow without choosing its model provider, prompt runtime, retrieval stack, or agent scheduler. The caller supplies evidence and reasoning; the core validates the typed result, preserves provenance and limitations, and publishes only a completed dossier.

When to use this project

Use StockResearchAgents when you need a harness-neutral, evidence-first contract for point-in-time company research, deterministic analytics, lifecycle controls, and completed-only publication. It fits MCP hosts and custom Python applications that already own their models, retrieval, credentials, and execution policy.

Do not use it as a model runtime, market-data vendor, broker, order-management system, autonomous trading engine, or evidence of investment performance. Live-provider coverage is deliberately narrow, licensed sources remain host-owned, and every trade-like output is a non-executable analytical scenario.

Related MCP server: quant-research-mcp

Verify it locally

Python 3.11 through 3.14 and uv are supported. From a source checkout:

uv sync
uv run python scripts/smoke_backend.py

Expected output has this shape:

ok run=analytics-… stages=26 events=34

This CI-backed smoke check publishes the deterministic, credential-free ORCL test submission through the completed-result path. It proves contract and publication behavior—not live retrieval, research quality, forecast calibration, or investment performance.

The checked-in preview and its JSON artifacts are visibly fixture-labeled, non-executable, and regenerated byte-for-byte in CI. See Examples; they are product-surface proof, not current ORCL research.

To inspect the public workflow contract without running a model or retrieving data:

uv run stock-research-agents analytics-plan \
  --input examples/company-request.v1.json \
  --output plan.json

The example request is explicitly fixture-mode. Changing its symbol does not make it live. See Getting started for the complete first-run explanation.

What you get

The one public product profile is company-analytics.v1. Its strict terminal result, CompanyAnalyticsResultV1, retains the exact submission and seven authoritative artifacts: dossier, analytics bundle, run card, hypothesis ledger, research iterations, quality receipt, and forecast set.

How it works

flowchart LR
    C["Caller runtime<br/>models, tools, retrieval, credentials"]
    P["company-analytics.v1<br/>26-stage workflow contract"]
    V["Deterministic validation<br/>temporal, lineage, numerical, safety"]
    G{"Publication gate"}
    R["Completed CompanyAnalyticsResultV1"]
    O["MCP reads, exports,<br/>Research Dossier Viewer"]

    C --> P --> V --> G
    G -->|accepted| R --> O
    G -->|rejected| X["Explicit validation errors<br/>no published dossier"]

1. A caller validates a request and receives versioned roles, dependencies, capabilities, completion criteria, and output schemas.

2. The caller retrieves cutoff-valid evidence and executes the stages with its own agents and tools.

3. StockResearchAgents validates the complete terminal submission and its cross-references.

4. Only an accepted, atomically published result becomes readable through MCP, exports, or the viewer.

Architecture explains the ports-and-adapters boundaries, lifecycle state machine, repositories, projections, and security invariants.

Interfaces

The coordination MCP intentionally registers no research-data tools. Credentials, raw licensed bodies, provider sessions, prompt text, model execution, and agent scheduling remain outside the core boundary.

Source and proof status

StockResearchAgents therefore has partial live public-source coverage, not complete live company research. Missing, stale, conflicting, or entitlement-blocked evidence remains visible. A scheduled, bounded, non-gating canary records sanitized public-provider status and contract shape, but it does not certify freshness or availability for a production run. See the source portfolio, research-data MCP, and proof ledger.

Install and integrate

No public release is claimed until a tagged version has been published. For development, use the source-checkout commands above. Once a release exists, the supported PyPI, GitHub Release, MCP, and host-specific commands will be listed in Harnesses and verified through the release process.

The complete documentation index is in docs/README.md.

Stable product language

Wire identifiers are versioned and are not cosmetically renamed. See the glossary.

Contributing, support, and security

• Read CONTRIBUTING.md before changing a contract, workflow, source adapter, or presentation boundary.

• Use SUPPORT.md for usage questions and troubleshooting routes.

• Report vulnerabilities through the private process in SECURITY.md, not a public issue.

• Follow the community code of conduct in issues, reviews, and project discussions.

• See the evidence-focused roadmap for priorities and explicit non-goals.

• Review user-visible changes in CHANGELOG.md.

Licensed under the Apache License 2.0.