feat(day6): TranslatorAgent, QuestionGenerator pipeline, Groq fallback for CN desk

- agents/translator_agent.py: thesis → PredictionMarketQuestion via Groq LLM
  - Polymarket-shaped binary questions, time-bounded 30-90 days
  - Oracle-resolvable criteria with cited data sources
- markets/question_generator.py: full pipeline orchestrator (analyze → translate → pin)
  - Routes to US/CN/CRYPTO agent by region key
  - IPFS pins both thesis and question artifacts
- agents/china_agent.py: Groq fallback when DEEPSEEK_API_KEY absent
- tests/test_day6.py: 9 new tests (agent routing, parser, fallback, instantiation)
- All 30 tests pass

Co-Authored-By: AdaL <adal@sylph.ai>

Author: chindris-mihai-alexandru

agents/translator_agent.py

@@ -0,0 +1,185 @@
+"""Translator Agent — converts an InvestmentThesis into a PredictionMarketQuestion.
+
+This agent is region-agnostic: it accepts a thesis from any desk (US, CN, CRYPTO, EU)
+and produces a Polymarket-shaped binary question that is:
+- Time-bounded (expiry ≤ 90 days out)
+- Oracle-resolvable (objective YES/NO criteria citing a data source)
+- Language-normalised to English
+
+Model routing (per AGENTS.md):
+- Default: Groq / llama-3.3-70b-versatile (fast, free-tier)
+- Override via model_client / model_kwargs constructor args.
+
+Run standalone:
+    uv run python -m agents.translator_agent --ticker AAPL
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+import adalflow as adal
+
+from agents.base_agent import PydanticJsonParser
+from reasoning.trace_schema import Direction, InvestmentThesis, PredictionMarketQuestion
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Prompt template
+# ---------------------------------------------------------------------------
+
+_TRANSLATOR_TEMPLATE = """\
+<SYS>
+You are a prediction-market question designer. Your job is to convert an investment thesis
+into a single, binary, oracle-resolvable prediction-market question.
+
+Rules:
+1. The question MUST be answerable YES or NO by a neutral third party using public data.
+2. The question MUST be time-bounded — expiry within 30–90 days from today ({{today}}).
+3. The resolution_criteria MUST cite a specific, publicly accessible data source
+   (e.g. "Bloomberg consensus EPS estimate", "CoinGecko daily close", "PBOC official announcement").
+4. category must be one of: macro | earnings | policy | crypto | geopolitics
+5. translation_confidence: how confident you are this question faithfully captures the thesis (0.0–1.0).
+
+Output ONLY strict JSON matching this schema (no extra text):
+{{schema}}
+</SYS>
+
+Investment thesis to translate:
+Ticker: {{ticker}}
+Region: {{region}}
+Direction: {{direction}}
+Confidence score: {{confidence_score}}
+Summary (EN): {{summary_en}}
+Risk factors: {{risks}}
+Source thesis ID: {{thesis_id}}
+Source language: {{lang}}
+Translated by model: {{model_name}}\
+"""
+
+
+class TranslatorAgent(adal.Component):
+    """Converts an InvestmentThesis → PredictionMarketQuestion via LLM."""
+
+    def __init__(
+        self,
+        *,
+        model_client: adal.ModelClient | None = None,
+        model_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__()
+        client = model_client or adal.GroqAPIClient()  # type: ignore[attr-defined]
+        kwargs = model_kwargs or {"model": "llama-3.3-70b-versatile", "temperature": 0.1, "max_tokens": 1024}
+
+        schema_str = json.dumps(
+            PredictionMarketQuestion.model_json_schema(), indent=2
+        )
+        template = _TRANSLATOR_TEMPLATE.replace("{{schema}}", schema_str)
+
+        self._generator = adal.Generator(
+            model_client=client,
+            model_kwargs=kwargs,
+            template=template,
+        )
+        self._parser = PydanticJsonParser(PredictionMarketQuestion)
+        self._model_name = kwargs.get("model", "llama-3.3-70b-versatile")
+
+    def translate(self, thesis: InvestmentThesis) -> PredictionMarketQuestion | None:
+        """Synchronously translate a thesis into a prediction-market question."""
+        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+        risks = "; ".join(thesis.risk_factors) if thesis.risk_factors else "none provided"
+
+        output = self._generator(
+            prompt_kwargs={
+                "today": today,
+                "ticker": thesis.ticker_or_asset,
+                "region": thesis.region.value,
+                "direction": thesis.direction.value,
+                "confidence_score": f"{thesis.confidence_score:.2f}",
+                "summary_en": thesis.thesis_summary_en[:800],
+                "risks": risks[:400],
+                "thesis_id": thesis.thesis_id,
+                "lang": thesis.working_language,
+                "model_name": self._model_name,
+            }
+        )
+
+        question = self._parser.call(
+            output,
+            extra_fields={
+                "source_thesis_id": thesis.thesis_id,
+                "source_language": thesis.lang,
+                "translated_by_model": self._model_name,
+            },
+        )
+
+        if not isinstance(question, PredictionMarketQuestion):
+            logger.warning("TranslatorAgent failed to parse PredictionMarketQuestion. raw: %s",
+                           getattr(output, "raw_response", "")[:300])
+            return None
+
+        return question
+
+    async def atranslate(self, thesis: InvestmentThesis) -> PredictionMarketQuestion | None:
+        """Async wrapper — runs translate in executor to avoid blocking event loop."""
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self.translate, thesis)
+
+
+# ---------------------------------------------------------------------------
+# CLI smoke test
+# ---------------------------------------------------------------------------
+
+
+async def _main() -> None:
+    from reasoning.trace_schema import AssetClass, Direction, Region
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--ticker", default="AAPL")
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    # Construct a dummy thesis for smoke-testing
+    from datetime import datetime, timezone
+    thesis = InvestmentThesis(
+        ticker=args.ticker,
+        region=Region.US,
+        asset_class=AssetClass.EQUITY,
+        direction=Direction.LONG,
+        conviction=0.75,
+        summary=f"{args.ticker} shows strong earnings momentum with AI tailwinds.",
+        catalysts=["Q2 earnings beat expected", "AI capex cycle acceleration"],
+        risk_factors=["Fed rate hike", "regulatory headwinds"],
+        lang="en",
+    )
+
+    agent = TranslatorAgent()
+    question = await agent.atranslate(thesis)
+    if question:
+        print(question.model_dump_json(indent=2))
+    else:
+        print("Translation failed — check logs.")
+
+
+def run() -> None:
+    asyncio.run(_main())
+
+
+if __name__ == "__main__":
+    run()

markets/question_generator.py

@@ -0,0 +1,125 @@
+"""Question Generator — orchestrates the full thesis→market pipeline.
+
+Pipeline:
+1. Run a regional agent (US / CN / CRYPTO) to produce an InvestmentThesis.
+2. Pass the thesis to TranslatorAgent to produce a PredictionMarketQuestion.
+3. Pin both artifacts to IPFS and record a TraceMetadata entry.
+
+This module is the single entry-point for the end-to-end demo.
+
+Run standalone:
+    GROQ_API_KEY=xxx uv run python -m markets.question_generator --ticker AAPL --region us
+    GROQ_API_KEY=xxx uv run python -m markets.question_generator --ticker ETH --region crypto
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+from typing import Literal
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from agents.translator_agent import TranslatorAgent
+from reasoning import ipfs_pinner
+from reasoning.trace_schema import InvestmentThesis, PredictionMarketQuestion
+
+logger = logging.getLogger(__name__)
+
+RegionKey = Literal["us", "cn", "crypto"]
+
+
+def _build_agent(region: RegionKey):  # type: ignore[return]
+    """Instantiate the correct regional agent for *region*."""
+    if region == "us":
+        from agents.us_agent import USAgent
+        return USAgent()
+    if region == "cn":
+        from agents.china_agent import ChinaAgent
+        return ChinaAgent()
+    if region == "crypto":
+        from agents.crypto_agent import CryptoAgent
+        return CryptoAgent()
+    raise ValueError(f"Unknown region: {region!r}. Choose from: us, cn, crypto")
+
+
+async def generate(
+    ticker: str,
+    region: RegionKey = "us",
+    *,
+    pin: bool = True,
+) -> tuple[InvestmentThesis, PredictionMarketQuestion | None]:
+    """Full pipeline: analyze → translate → (optional) pin to IPFS.
+
+    Returns:
+        (thesis, question) — question is None if translation fails.
+    """
+    # 1. Regional analysis
+    agent = _build_agent(region)
+    logger.info("Running %s agent on %s…", region.upper(), ticker)
+    thesis = await agent.analyze(ticker)
+    logger.info("Thesis: %s %s (conviction=%.2f)", ticker, thesis.direction.value, thesis.conviction)
+
+    # 2. Translate to prediction-market question
+    translator = TranslatorAgent()
+    logger.info("Translating thesis → prediction-market question…")
+    question = await translator.atranslate(thesis)
+    if question:
+        logger.info("Question: %s", question.question_text)
+    else:
+        logger.warning("Translation produced no question.")
+
+    # 3. IPFS pinning (soft-fail)
+    if pin:
+        thesis_cid = await ipfs_pinner.pin_json(thesis.model_dump(mode="json"), name=f"thesis-{thesis.thesis_id[:8]}")
+        logger.info("Thesis pinned → %s", thesis_cid)
+
+        if question:
+            q_cid = await ipfs_pinner.pin_json(question.model_dump(mode="json"), name=f"question-{question.question_id[:8]}")
+            logger.info("Question pinned → %s", q_cid)
+
+    return thesis, question
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+async def _main() -> None:
+    parser = argparse.ArgumentParser(description="Full thesis → prediction-market pipeline.")
+    parser.add_argument("--ticker", default="AAPL")
+    parser.add_argument("--region", choices=["us", "cn", "crypto"], default="us")
+    parser.add_argument("--no-pin", action="store_true", help="Skip IPFS pinning")
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    thesis, question = await generate(args.ticker, args.region, pin=not args.no_pin)
+
+    print("\n" + "=" * 60)
+    print("INVESTMENT THESIS")
+    print("=" * 60)
+    print(thesis.model_dump_json(indent=2, ensure_ascii=False))
+
+    if question:
+        print("\n" + "=" * 60)
+        print("PREDICTION MARKET QUESTION")
+        print("=" * 60)
+        print(question.model_dump_json(indent=2))
+
+
+def run() -> None:
+    asyncio.run(_main())
+
+
+if __name__ == "__main__":
+    run()