stock-research-agents

StockResearchAgents

Use company-analytics.v1 as the primary profile. Treat StockResearchAgents as a contract, analytics, publication, and read-model capability—not as the model or data provider.

Keep these authorities separate:

• Let the active harness own web/browser/provider retrieval, model reasoning, native agents, authentication, entitlements, and hard interruption.
• Let StockResearchAgents own the 26-stage workflow contract, strict point-in-time and terminal validation, deterministic calculations, research-quality records, atomic completed publication, and completed-only projection. The caller runtime attests intermediate completion criteria; StockResearchAgents records opaque nonterminal envelopes as committed, not independently verified content.
• Never put an API key, token, cookie, authorization value, provider configuration, raw source body, unrestricted tool argument, or broker/order instruction into a StockResearchAgents call.

Run company analytics

1. Resolve the exact instrument identity. Do not guess an exchange, share class, fund, or crypto asset from an ambiguous symbol.
2. Set requested_at and cutoff_at to exact timezone-aware instants. Use the current instant as the cutoff for a current-research request unless the user asks for a historical replay.
3. Declare a truthful research_mode: live only after live retrieval; fixture for synthetic test data; historical_replay for retained as-of evidence.
4. Call discover_capability, then prepare_company_analytics with a schema-valid company request, execution mode, and the most suitable research pack. Default to initiating-coverage.v1 for a complete company picture and sequential when the runtime lacks native subagents; use native for a caller-managed multi-agent run and import only when submitting an already completed bundle. Execute the returned stage-instructions.v1 roles, objectives, completion criteria, dependencies, capabilities, and output refs; exact prompt wording remains caller-owned. The returned company-analytics-submission.v1 schema is self-contained and includes typed analytics records; use the strict Python contracts as authoritative for cross-field semantics.
5. Execute dependency-ready stages in parallel only for a stateless plan. In a durable native run, commit exactly the current first-incomplete stage, accept the returned next stage, and preserve that order even if tools gathered supporting evidence concurrently. Do not omit stages merely because the harness lacks subagents.
6. Execute the source-portfolio plan below with caller-owned web, browser, connector, or research-data tools. Do not stop after the first successful provider when more explicit routes are configured: use SourcePortfolioCollector for same-capability fan-out, retain its SourcePortfolioReceipt, and carry the receipt's ordered route-qualified source_batch_ids into the run card and source-lineage crosswalk. GDELT and search results are discovery evidence only: open the underlying issuer, regulator, exchange, macro authority, or attributable publisher page before treating a claim as verified. Normalize only bounded evidence, locators, hashes, timestamps, and permitted extracts into the terminal contracts. Preserve SourceBatch/observation identity, digest scope, dossier document ID, analytics source/license receipt, and entitlement translation in the versioned source-lineage crosswalk.
7. Produce deterministic analytics for fundamentals, ratios, valuation, consensus, positioning, catalysts, and declared experiments. Preserve input IDs, units, periods, rounding, assumptions, implementation digests, and point-in-time dataset receipts.
8. Issue falsifiable hypotheses and explicit forecasts only when their target, horizon, resolution rule, evidence, and cutoff are defined. Namespace every forecast_id globally with the exact <quality_run_id>. prefix. Never reinterpret confidence, rating strength, or risk severity as a forecast probability.
9. Assemble one complete company-analytics-submission.v1 wrapper containing the company-research-submission.v1 request/dossier plus analytics, source-lineage crosswalk, run card, hypothesis ledger, research iterations, quality receipt, and forecast set. The run card must bind the shipped workflow digest, selected execution mode, and exact ordered 26-stage receipt set.
10. Prefer create_company_analytics_run for a durable run. Use the shared start, receipt, stage-commit, pause/resume, cancellation, event, and finalize controls with the latest optimistic revision across all 26 stages. The sequential runner reports executor_required until the caller supplies a LifecycleStageExecutor; it does not provide model reasoning or retrieval. Resume from the first incomplete stage and replay interrupted in-flight caller work. Treat nonterminal stage events as durable commitments, not proof that StockResearchAgents read caller-owned content. The final stage must contain the complete analytics payload and pass strict schema plus coordinator-commitment validation. Treat the published CompanyAnalyticsResultV1 as canonical: it retains the exact CompanyAnalyticsSubmissionV1 and seven authoritative artifacts. The durable lifecycle ID remains the control handle; after completion, resolve the canonical result through control.result_run_id. The quality outcome index is recoverable derived state, not part of a distributed transaction.
11. After a successful finalize_run or import_company_analytics, inspect its presentation receipt. When status is ready, return or open its run-specific url; in Codex App, show that local URL as the completed end product. When status is path_only, render get_run_view inline. When status is unavailable, keep the completed research result and retry presentation with launch_research_report. Never launch one page per company, never open a browser before completion, and never present private partial-stage material as a completed result. Use import_company_analytics only when the caller already has one complete analytics payload and does not need lifecycle checkpoints.
12. After a forecast resolves, append a typed observation with record_research_outcome; inspect reproducible records with get_research_quality. Corrections must supersede earlier observations rather than overwrite history.