Module: astro.agents
Why this module exists
LLMs excel at synthesis and critique when given bounded, well-structured inputs. This module wraps provider calls into role-specific agents (analysts, researchers, trader, risk) that all speak the same state dictionary contract expected by DecisionExecutor and workflow.build_analyst_chain. Without this layer, prompt strings would be scattered across routes and scripts—untestable and unsafe to evolve.
Where it fits in the system
flowchart LR
Ctx[DecisionContext]
Ex[DecisionExecutor]
Ag[agents_callables]
St[AstroState_reports]
Ctx --> Ex
Ex --> Ag
Ag --> St
Upstream: DecisionContext text fields and optional ModelPrediction (from services.context_builder).
Downstream: Populated reports and debate histories consumed by policy, signal extraction, and risk in decision_engine.
What happens if it fails
| Failure | System impact |
|---|
| Provider auth error | Route or script raises; decision aborts mid-pipeline |
| Over-long context | Latency, truncation, or provider errors—monitor token usage |
| Bad patch shape from custom agent | KeyError or silent state corruption—follow existing patch patterns |
Module overview
| |
|---|
| Purpose | LLM-powered analysts, bull/bear researchers, research synthesizer, trader, three-way risk debators, risk judge, and shared memory utilities. |
| Responsibilities | Produce text reports and debate state consumed by DecisionExecutor; expose factory functions for each agent role. |
| Dependencies | langchain LLM handles from utils.llm.factory; decision_engine.state_manager types in payloads. |
Key entry points (astro/agents/__init__.py)
Factory functions (representative list): create_technical_analyst, create_sentiment_analyst, create_news_analyst, create_fundamentals_analyst, create_macro_analyst, create_bullish_researcher, create_bearish_researcher, create_research_synthesizer, create_trader_agent, create_aggressive_debator, create_conservative_debator, create_neutral_debator, create_risk_judge.
Each returns a callable compatible with workflow.build_analyst_chain / executor patches (dict-in, dict-out patches on AstroState fields).
Key classes
| Class / type | Role |
|---|
FinancialSituationMemory (agents/shared/memory.py) | Role-tagged memory buffer for debators/judge. |
| Agent callables | Encapsulate prompt + LLM invoke; mutate state via returned patches. |
Key functions
| Function | Description |
|---|
extract_signal_from_text (agents/trader/signal_generator.py) | Parse BUY/SELL/HOLD from narrative text. |
build_analyst_chain (decision_engine/workflow.py) | Ordered list of analyst steps from string keys. |
Subpackages
| Path | Role |
|---|
agents/analysts/ | Market, sentiment, news, fundamentals, macro |
agents/researchers/ | Bull, bear, debate engine, synthesizer |
agents/trader/ | Trader agent, signal extraction |
agents/risk/ | Debators, judge, exposure, portfolio constraints, position sizer |
agents/shared/ | Base agent, memory, messaging, grounding |