dsa-server 0.1.0__py3-none-any.whl

agent/__init__.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""
+Agent module for stock analysis system.
+
+Provides LLM-based agent with tool-calling capabilities,
+pluggable trading strategies, and multi-turn conversation support.
+
+Enabled via AGENT_MODE=true environment variable.
+
+Use explicit imports to avoid pulling in heavy dependencies (e.g. json_repair)
+when only lightweight sub-modules like tools.registry are needed::
+
+    from src.agent.executor import AgentExecutor, AgentResult
+    from src.agent.runner import run_agent_loop, RunLoopResult
+    from src.agent.protocols import AgentContext, AgentOpinion, StageResult, AgentRunStats
+    from src.agent.orchestrator import AgentOrchestrator
+"""
+
+
+def __getattr__(name):
+    """Lazy import to avoid triggering json_repair etc. on package access."""
+    if name == "AgentExecutor":
+        from src.agent.executor import AgentExecutor
+        return AgentExecutor
+    if name == "AgentResult":
+        from src.agent.executor import AgentResult
+        return AgentResult
+    if name == "RunLoopResult":
+        from src.agent.runner import RunLoopResult
+        return RunLoopResult
+    if name in ("AgentContext", "AgentOpinion", "StageResult", "AgentRunStats"):
+        from src.agent import protocols
+        return getattr(protocols, name)
+    if name == "AgentOrchestrator":
+        from src.agent.orchestrator import AgentOrchestrator
+        return AgentOrchestrator
+    if name == "AgentMemory":
+        from src.agent.memory import AgentMemory
+        return AgentMemory
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "AgentExecutor",
+    "AgentResult",
+    "RunLoopResult",
+    "AgentContext",
+    "AgentOpinion",
+    "StageResult",
+    "AgentRunStats",
+    "AgentOrchestrator",
+    "AgentMemory",
+]

agent/agents/__init__.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""
+Specialised agents for the multi-agent pipeline.
+
+Each agent class inherits from :class:`BaseAgent` and implements
+a focused analysis scope (technical, intelligence, decision, risk).
+"""
+
+from src.agent.agents.base_agent import BaseAgent
+from src.agent.agents.technical_agent import TechnicalAgent
+from src.agent.agents.intel_agent import IntelAgent
+from src.agent.agents.decision_agent import DecisionAgent
+from src.agent.agents.risk_agent import RiskAgent
+from src.agent.agents.portfolio_agent import PortfolioAgent
+
+__all__ = [
+    "BaseAgent",
+    "TechnicalAgent",
+    "IntelAgent",
+    "DecisionAgent",
+    "RiskAgent",
+    "PortfolioAgent",
+]

agent/agents/base_agent.py

@@ -0,0 +1,286 @@
+# -*- coding: utf-8 -*-
+"""
+BaseAgent — abstract base for all specialised agents.
+
+Every agent in the multi-agent pipeline inherits from this class and
+implements :meth:`run`.  The base class provides shared utilities:
+tool-subset selection, prompt assembly, LLM invocation via the shared
+runner, and structured opinion output.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Optional
+
+from src.agent.llm_adapter import LLMToolAdapter
+from src.agent.memory import AgentMemory
+from src.agent.protocols import AgentContext, AgentOpinion, StageResult, StageStatus
+from src.agent.runner import RunLoopResult, run_agent_loop
+from src.agent.skills.defaults import extract_skill_id
+from src.agent.tools.registry import ToolRegistry
+from src.market_phase_prompt import format_market_phase_prompt_section
+from src.report_language import normalize_report_language
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAgent(ABC):
+    """Abstract base for all specialised agents.
+
+    Subclasses **must** implement:
+    - :pyattr:`agent_name` — unique agent identifier
+    - :meth:`system_prompt` — return the LLM system prompt
+    - :meth:`build_user_message` — construct the user message for the LLM
+
+    Subclasses **may** override:
+    - :pyattr:`tool_names` — restrict which tools the agent can access
+    - :pyattr:`max_steps` — per-agent step limit  (default 6)
+    - :meth:`post_process` — transform the raw LLM text into an :class:`AgentOpinion`
+    """
+
+    # Subclass overrides
+    agent_name: str = "base"
+    tool_names: Optional[List[str]] = None  # None → all tools available
+    max_steps: int = 6
+
+    def __init__(
+        self,
+        tool_registry: ToolRegistry,
+        llm_adapter: LLMToolAdapter,
+        skill_instructions: str = "",
+        technical_skill_policy: str = "",
+    ):
+        self.tool_registry = tool_registry
+        self.llm_adapter = llm_adapter
+        self.skill_instructions = skill_instructions
+        self.technical_skill_policy = technical_skill_policy
+        self.memory = AgentMemory.from_config()
+
+    # -----------------------------------------------------------------
+    # Abstract interface
+    # -----------------------------------------------------------------
+
+    @abstractmethod
+    def system_prompt(self, ctx: AgentContext) -> str:
+        """Build the system prompt for this agent."""
+
+    @abstractmethod
+    def build_user_message(self, ctx: AgentContext) -> str:
+        """Build the user message sent to the LLM."""
+
+    # -----------------------------------------------------------------
+    # Default hook for structured output
+    # -----------------------------------------------------------------
+
+    def post_process(self, ctx: AgentContext, raw_text: str) -> Optional[AgentOpinion]:
+        """Extract a structured :class:`AgentOpinion` from the raw LLM text.
+
+        Default: returns ``None`` (the raw text is still stored in
+        ``StageResult.meta["raw_text"]``).  Subclasses that produce
+        analysis opinions should override this.
+        """
+        return None
+
+    # -----------------------------------------------------------------
+    # Execution
+    # -----------------------------------------------------------------
+
+    def run(
+        self,
+        ctx: AgentContext,
+        progress_callback: Optional[Callable[[Dict[str, Any]], None]] = None,
+        timeout_seconds: Optional[float] = None,
+    ) -> StageResult:
+        """Execute this agent and return a :class:`StageResult`.
+
+        Steps:
+        1. Build system + user messages.
+        2. Optionally inject pre-fetched data from ``ctx.data``.
+        3. Delegate to :func:`run_agent_loop`.
+        4. Call :meth:`post_process` to produce an opinion.
+        5. Append the opinion to ``ctx.opinions``.
+        """
+        t0 = time.time()
+        result = StageResult(stage_name=self.agent_name, status=StageStatus.RUNNING)
+
+        try:
+            messages = self._build_messages(ctx)
+
+            # Restrict tools if the agent declares a subset
+            registry = self._filtered_registry()
+
+            loop_result: RunLoopResult = run_agent_loop(
+                messages=messages,
+                tool_registry=registry,
+                llm_adapter=self.llm_adapter,
+                max_steps=self.max_steps,
+                progress_callback=progress_callback,
+                max_wall_clock_seconds=timeout_seconds,
+                stock_scope=ctx.meta.get("stock_scope"),
+            )
+
+            result.tokens_used = loop_result.total_tokens
+            result.tool_calls_count = len(loop_result.tool_calls_log)
+            result.meta["raw_text"] = loop_result.content
+            result.meta["models_used"] = loop_result.models_used
+            result.meta["tool_calls_log"] = loop_result.tool_calls_log
+
+            if not loop_result.success:
+                result.status = StageStatus.FAILED
+                result.error = loop_result.error or "Agent loop did not produce a final answer"
+                return result
+
+            # Post-process into structured opinion
+            opinion = self.post_process(ctx, loop_result.content)
+            if opinion is not None:
+                opinion.agent_name = self.agent_name
+                self._apply_memory_calibration(ctx, opinion, result)
+                ctx.add_opinion(opinion)
+                result.opinion = opinion
+
+            result.status = StageStatus.COMPLETED
+
+        except Exception as exc:
+            logger.error("[%s] execution failed: %s", self.agent_name, exc, exc_info=True)
+            result.status = StageStatus.FAILED
+            result.error = str(exc)
+        finally:
+            result.duration_s = round(time.time() - t0, 2)
+
+        return result
+
+    # -----------------------------------------------------------------
+    # Internal helpers
+    # -----------------------------------------------------------------
+
+    def _build_messages(self, ctx: AgentContext) -> List[Dict[str, Any]]:
+        """Assemble the initial messages list for the LLM."""
+        messages: List[Dict[str, Any]] = [
+            {"role": "system", "content": self.system_prompt(ctx)},
+        ]
+
+        history = ctx.meta.get("conversation_history")
+        if isinstance(history, list):
+            for message in history:
+                if not isinstance(message, dict):
+                    continue
+                role = message.get("role")
+                content = message.get("content")
+                if role in {"user", "assistant", "system"} and isinstance(content, str) and content:
+                    messages.append({"role": role, "content": content})
+
+        report_language = normalize_report_language(ctx.meta.get("report_language", "zh"))
+        market_phase_section = format_market_phase_prompt_section(
+            ctx.meta.get("market_phase_context"),
+            report_language=report_language,
+        )
+        if market_phase_section:
+            messages.append({"role": "user", "content": market_phase_section})
+
+        analysis_context_pack_summary = ctx.meta.get("analysis_context_pack_summary")
+        if isinstance(analysis_context_pack_summary, str) and analysis_context_pack_summary:
+            messages.append({"role": "user", "content": analysis_context_pack_summary})
+
+        # Inject pre-fetched data as a synthetic assistant context
+        cached_data = self._inject_cached_data(ctx)
+        if cached_data:
+            messages.append({"role": "user", "content": cached_data})
+            messages.append({"role": "assistant", "content": "Understood, I have the pre-fetched data. Proceeding with analysis."})
+
+        messages.append({"role": "user", "content": self.build_user_message(ctx)})
+        return messages
+
+    def _inject_cached_data(self, ctx: AgentContext) -> str:
+        """Build a context string from already-fetched data in ``ctx.data``.
+
+        This avoids redundant tool calls when earlier stages have already
+        fetched the data this agent needs.
+        """
+        import json
+        parts: List[str] = []
+        for key, value in ctx.data.items():
+            if value is not None:
+                try:
+                    serialised = json.dumps(value, ensure_ascii=False, default=str)
+                except (TypeError, ValueError):
+                    serialised = str(value)
+                # Cap per-field size to avoid overwhelming the context window
+                if len(serialised) > 8000:
+                    serialised = serialised[:8000] + "...(truncated)"
+                parts.append(f"[Pre-fetched: {key}]\n{serialised}")
+        memory_context = self._build_memory_context(ctx)
+        if memory_context:
+            parts.append(memory_context)
+        return "\n\n".join(parts) if parts else ""
+
+    def _filtered_registry(self) -> ToolRegistry:
+        """Return a ToolRegistry restricted to ``self.tool_names``.
+
+        If ``tool_names`` is None (default), the full registry is returned.
+        """
+        if self.tool_names is None:
+            return self.tool_registry
+
+        from src.agent.tools.registry import ToolRegistry as TR
+        filtered = TR()
+        for name in self.tool_names:
+            tool_def = self.tool_registry.get(name)
+            if tool_def:
+                filtered.register(tool_def)
+            else:
+                logger.warning("[%s] requested tool '%s' not found in registry", self.agent_name, name)
+        return filtered
+
+    def _build_memory_context(self, ctx: AgentContext) -> str:
+        """Summarise recent analysis history for prompt injection."""
+        if not self.memory.enabled or not ctx.stock_code:
+            return ""
+
+        entries = self.memory.get_stock_history(ctx.stock_code, limit=3)
+        if not entries:
+            return ""
+
+        lines = ["[Memory: recent analysis history]"]
+        for entry in entries:
+            parts = [
+                entry.date or "unknown_date",
+                f"signal={entry.signal or 'unknown'}",
+                f"sentiment={entry.sentiment_score}",
+            ]
+            if entry.price_at_analysis:
+                parts.append(f"price={entry.price_at_analysis}")
+            if entry.outcome_5d is not None:
+                parts.append(f"outcome_5d={entry.outcome_5d}")
+            if entry.outcome_20d is not None:
+                parts.append(f"outcome_20d={entry.outcome_20d}")
+            if entry.was_correct is not None:
+                parts.append(f"was_correct={entry.was_correct}")
+            lines.append("- " + ", ".join(parts))
+        lines.append("Use this memory as context only; do not copy it verbatim into the final answer.")
+        return "\n".join(lines)
+
+    def _apply_memory_calibration(self, ctx: AgentContext, opinion: AgentOpinion, result: StageResult) -> None:
+        """Adjust confidence using historical calibration when enabled."""
+        if not self.memory.enabled:
+            return
+
+        skill_id = extract_skill_id(self.agent_name)
+        calibration = self.memory.get_calibration(
+            agent_name=self.agent_name,
+            stock_code=ctx.stock_code or None,
+            skill_id=skill_id,
+        )
+        if not calibration.calibrated:
+            return
+
+        raw_confidence = opinion.confidence
+        opinion.confidence = max(0.0, min(1.0, raw_confidence * calibration.calibration_factor))
+        result.meta["memory_calibration"] = {
+            "raw_confidence": raw_confidence,
+            "calibrated_confidence": opinion.confidence,
+            "factor": calibration.calibration_factor,
+            "samples": calibration.total_samples,
+        }

agent/agents/decision_agent.py

@@ -0,0 +1,232 @@
+# -*- coding: utf-8 -*-
+"""
+DecisionAgent — final synthesis and decision-making specialist.
+
+Responsible for:
+- Aggregating opinions from technical + intel + risk + skill agents
+- Producing the final Decision Dashboard JSON
+- Generating actionable buy/hold/sell recommendations with price levels
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import List, Optional
+
+from src.agent.agents.base_agent import BaseAgent
+from src.agent.protocols import AgentContext, AgentOpinion, normalize_decision_signal
+from src.report_language import normalize_report_language
+
+logger = logging.getLogger(__name__)
+
+
+class DecisionAgent(BaseAgent):
+    """Synthesise prior agent opinions into the final dashboard."""
+
+    agent_name = "decision"
+    max_steps = 3  # pure synthesis, should not need many tool calls
+    tool_names: Optional[List[str]] = []  # no tool access — works from context only
+
+    @staticmethod
+    def _is_chat_mode(ctx: AgentContext) -> bool:
+        return ctx.meta.get("response_mode") == "chat"
+
+    def system_prompt(self, ctx: AgentContext) -> str:
+        report_language = normalize_report_language(ctx.meta.get("report_language", "zh"))
+        if self._is_chat_mode(ctx):
+            prompt = """\
+You are a **Decision Synthesis Agent** replying directly to the user's latest
+stock-analysis question.
+
+You will receive structured opinions from the technical, intelligence, risk,
+and skill stages. Synthesize them into a concise, natural-language answer.
+
+Requirements:
+- Answer the user's actual question directly
+- Use Markdown when helpful
+- Keep the response practical and specific
+- Highlight the main signal, key reasoning, and major risks
+- Do NOT output JSON or code fences unless the user explicitly asks for them
+"""
+            if report_language == "en":
+                return prompt + "\nAlways answer in English.\n"
+            return prompt + "\n默认使用中文回答。\n"
+
+        skills = ""
+        if self.skill_instructions:
+            skills = f"\n## Active Trading Skills\n\n{self.skill_instructions}\n"
+
+        prompt = f"""\
+You are a **Decision Synthesis Agent** that produces the final investment \
+Decision Dashboard.
+
+You will receive:
+1. Structured opinions from a Technical Agent and an Intel Agent
+2. Any risk flags raised by a Risk Agent
+        3. Skill evaluation results (if applicable)
+
+Your task: synthesise all inputs into a single, actionable Decision Dashboard.
+{skills}
+## Core Principles
+1. **Core conclusion first** — one sentence, ≤30 chars
+2. **Split advice** — different for no-position vs has-position
+3. **Precise sniper levels** — concrete price numbers, no hedging
+4. **Checklist visual** — ✅⚠️❌ for each checkpoint
+5. **Risk priority** — risk alerts must be prominent. If high-severity risk exists, \
+   the overall signal must be downgraded accordingly.
+
+## Signal Weighting Guidelines
+- Technical opinion weight: ~40%
+- Intel / sentiment weight: ~30%
+- Risk flags weight: ~30% (negative override: any high-severity risk caps signal at "hold")
+- If a skill opinion is present, blend it at 20% weight (reducing others proportionally)
+
+## Scoring
+- 80-100: buy (all conditions met, high conviction)
+- 60-79: buy (mostly positive, minor caveats)
+- 40-59: hold (mixed signals, or risk present)
+- 20-39: sell (negative trend + risk)
+- 0-19: sell (major risk + bearish)
+
+## Actionability Guardrails
+- Do not flip directly between buy and sell only because one trading day moved up or down.
+- Base operation_advice on support/resistance, volume/chip context, main-force capital flow, and risk flags.
+- If price is between support and resistance and capital flow is not clearly one-sided, prefer a neutral action such as hold/watch/range-bound/shakeout watch; keep decision_type as hold.
+- Buy requires support confirmation or a valid resistance breakout with volume/capital-flow confirmation.
+- Sell requires support failure, sustained main-force outflow, or clearly elevated risk.
+
+## Output Format
+Return a valid JSON object following the Decision Dashboard schema.  The JSON \
+must include at minimum these top-level keys:
+  stock_name, sentiment_score, trend_prediction, operation_advice,
+  decision_type, confidence_level, dashboard, analysis_summary,
+  key_points, risk_warning
+
+Important: ``decision_type`` must stay within the existing enum
+``buy|hold|sell``. Express stronger conviction via ``confidence_level``,
+``sentiment_score``, and the natural-language fields instead of inventing
+new decision_type values.
+
+The nested ``dashboard`` object must include ``phase_decision`` with these
+keys: ``phase_context``, ``action_window``, ``immediate_action``,
+``watch_conditions``, ``next_check_time``, ``confidence_reason``,
+``data_limitations``. For intraday/lunch-break/near-close phases, describe the
+current action, watch conditions, and next check point. For pre-market,
+non-trading, or unknown phases, do not invent today's intraday movement. If
+quote, daily bars, or technical data is stale, fallback, missing, fetch_failed,
+partial, or estimated, ``confidence_level`` must not be High/高 and the
+limitation must be reflected in ``confidence_reason`` or ``data_limitations``.
+"""
+        if report_language == "en":
+            return prompt + """
+
+## Output Language
+- Keep every JSON key unchanged.
+- `decision_type` must remain `buy|hold|sell`.
+- Write all human-readable JSON values in English.
+"""
+        return prompt + """
+
+## 输出语言
+- 所有 JSON 键名保持不变。
+- `decision_type` 必须保持为 `buy|hold|sell`。
+- 所有面向用户的人类可读文本值必须使用中文。
+"""
+
+    def build_user_message(self, ctx: AgentContext) -> str:
+        if self._is_chat_mode(ctx):
+            parts = [
+                "# User Question",
+                ctx.query,
+                "",
+                f"Stock: {ctx.stock_code} ({ctx.stock_name})" if ctx.stock_name else f"Stock: {ctx.stock_code}",
+                "",
+            ]
+        else:
+            parts = [
+                f"# Synthesis Request for {ctx.stock_code}",
+                f"Stock: {ctx.stock_code} ({ctx.stock_name})" if ctx.stock_name else f"Stock: {ctx.stock_code}",
+                "",
+            ]
+
+        # Feed prior opinions
+        if ctx.opinions:
+            parts.append("## Agent Opinions")
+            for op in ctx.opinions:
+                parts.append(f"\n### {op.agent_name}")
+                parts.append(f"Signal: {op.signal} | Confidence: {op.confidence:.2f}")
+                parts.append(f"Reasoning: {op.reasoning}")
+                if op.key_levels:
+                    parts.append(f"Key levels: {json.dumps(op.key_levels)}")
+                if op.raw_data:
+                    extra_keys = {k: v for k, v in op.raw_data.items()
+                                  if k not in ("signal", "confidence", "reasoning", "key_levels")}
+                    if extra_keys:
+                        parts.append(f"Extra data: {json.dumps(extra_keys, ensure_ascii=False, default=str)}")
+                parts.append("")
+
+        # Feed risk flags
+        if ctx.risk_flags:
+            parts.append("## Risk Flags")
+            for rf in ctx.risk_flags:
+                parts.append(f"- [{rf.get('severity', 'medium')}] {rf.get('category', '')}: {rf.get('description', '')}")
+            parts.append("")
+
+        # Skill meta
+        requested_skills = ctx.meta.get("skills_requested") or ctx.meta.get("strategies_requested")
+        if requested_skills:
+            parts.append(f"## Skills: {', '.join(requested_skills)}")
+            parts.append("")
+
+        if self._is_chat_mode(ctx):
+            parts.append(
+                "Answer the user in natural language using the evidence above. "
+                "Do not output JSON unless the user explicitly requests structured data."
+            )
+        else:
+            parts.append("Synthesise the above into the Decision Dashboard JSON.")
+        return "\n".join(parts)
+
+    def post_process(self, ctx: AgentContext, raw_text: str) -> Optional[AgentOpinion]:
+        """Store the parsed dashboard in ctx.meta; also return an opinion."""
+        if self._is_chat_mode(ctx):
+            text = (raw_text or "").strip()
+            if not text:
+                return None
+
+            ctx.set_data("final_response_text", text)
+            prior = next((op for op in reversed(ctx.opinions) if op.agent_name != self.agent_name), None)
+            return AgentOpinion(
+                agent_name=self.agent_name,
+                signal=prior.signal if prior is not None else "hold",
+                confidence=prior.confidence if prior is not None else 0.5,
+                reasoning=text,
+                raw_data={"response_mode": "chat"},
+            )
+
+        from src.agent.runner import parse_dashboard_json
+
+        dashboard = parse_dashboard_json(raw_text)
+        if dashboard:
+            dashboard["decision_type"] = normalize_decision_signal(
+                dashboard.get("decision_type", "hold")
+            )
+            ctx.set_data("final_dashboard", dashboard)
+            try:
+                _raw_score = dashboard.get("sentiment_score", 50) or 50
+                _score = float(_raw_score)
+            except (TypeError, ValueError):
+                _score = 50.0
+            return AgentOpinion(
+                agent_name=self.agent_name,
+                signal=dashboard.get("decision_type", "hold"),
+                confidence=min(1.0, _score / 100.0),
+                reasoning=dashboard.get("analysis_summary", ""),
+                raw_data=dashboard,
+            )
+        else:
+            # Even if JSON parsing fails, store the raw text for downstream use
+            ctx.set_data("final_dashboard_raw", raw_text)
+            logger.warning("[DecisionAgent] failed to parse dashboard JSON")
+            return None