feat: Major simulation engine, prompt system, and CLI overhaul

.env.example

@@ -1,12 +1,13 @@
-# LLM API Keys
+# LLM API Keys (fill in whichever providers you use)
 KIMI_API_KEY=your_kimi_api_key_here
+DEEPSEEK_API_KEY=your_deepseek_api_key_here
+DASHSCOPE_API_KEY=your_dashscope_api_key_here
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
-DEEPSEEK_API_KEY=
 
-# LLM defaults
+# LLM defaults (used when --provider/--model not specified)
 DEFAULT_LLM_PROVIDER=kimi
-DEFAULT_LLM_MODEL=kimi-k2.5
+DEFAULT_LLM_MODEL=kimi-k2.6
 
 # Storage
 DATABASE_PATH=data/orgconstruct.db

.gitignore

@@ -46,6 +46,7 @@ data/archives/*.json
 # Logs
 *.log
 logs/
+!logs/*.md
 
 # OS
 .DS_Store
@@ -55,5 +56,18 @@ Thumbs.db
 .agents/
 .claude/
 
+# Docs (not published, kept locally)
+docs/
+
+# Papers and copyrighted materials
+*.pdf
+
+# Experiment scripts (local only, not published)
+scripts/
+
 # Research scratch
 erp_extract.txt
+backend/data/
+
+# paper drafts
+paper/

backend/src/orgconstruct/agents/discussion.py

@@ -45,11 +45,13 @@ async def run(self, context: GameContext) -> Decision:
         for round_num in range(1, self.max_rounds + 1):
             for agent in self.agents:
                 response = await agent.respond(context, self.last_discussion_history)
-                self.last_discussion_history.append({
-                    "round": round_num,
-                    "role": agent.display_name,
-                    "content": response,
-                })
+                self.last_discussion_history.append(
+                    {
+                        "round": round_num,
+                        "role": agent.display_name,
+                        "content": response,
+                    }
+                )
                 logger.info(
                     "Round %d %s: %s...",
                     round_num,

backend/src/orgconstruct/agents/erpsim_discussion.py

@@ -2,13 +2,23 @@
 
 Structurally identical to RoundRobinDiscussion but typed for ERPSimContext
 and ERPSimDecision. Separate class to avoid breaking the simplified path.
+
+Supports two modes:
+1. Legacy: plain discussion → CEO final decision (backward compatible)
+2. ReAct: each agent independently gathers data → discussion → CEO ReAct decision
 """
 
 import asyncio
 import logging
 
 from orgconstruct.agents.erpsim_executive import ERPSimExecutiveAgent
-from orgconstruct.models.erpsim_decision import ERPSimContext, ERPSimDecision
+from orgconstruct.agents.tools.executor import ToolRegistry
+from orgconstruct.models.erpsim_decision import (
+    ERPSimContext,
+    ERPSimDecision,
+    PrivateContext,
+    PublicContext,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -25,7 +35,7 @@ class ERPSimDiscussion:
     def __init__(
         self,
         agents: list[ERPSimExecutiveAgent],
-        max_rounds: int = 2,
+        max_rounds: int = 3,
     ) -> None:
         self.agents = agents
         self.max_rounds = max_rounds
@@ -36,34 +46,173 @@ def __init__(
     def ceo(self) -> ERPSimExecutiveAgent:
         return self._agent_by_role["CEO"]
 
-    async def run(self, context: ERPSimContext) -> ERPSimDecision:
-        """Run discussion rounds and return the CEO's final decision."""
+    async def run(self, context: ERPSimContext) -> tuple[ERPSimDecision, dict]:
+        """Run discussion rounds and return the CEO's final decision.
+
+        Legacy mode: uses ERPSimContext (backward compatible).
+
+        Returns:
+            Tuple of (ERPSimDecision, token_usage dict with prompt/completion/total tokens).
+        """
         self.last_discussion_history = []
+        total_prompt = 0
+        total_completion = 0
 
         for round_num in range(1, self.max_rounds + 1):
             for agent in self.agents:
-                response = await agent.respond(context, self.last_discussion_history)
+                result = await agent.respond(context, self.last_discussion_history)
+                usage = result.get("usage", {})
+                pt = usage.get("prompt_tokens", 0)
+                ct = usage.get("completion_tokens", 0)
+                total_prompt += pt
+                total_completion += ct
                 self.last_discussion_history.append(
                     {
                         "round": round_num,
                         "role": agent.role,
-                        "content": response,
+                        "content": result["content"],
+                        "token_count": pt + ct,
                     }
                 )
-                # Throttle to avoid rate limits on fast sequential calls
                 await asyncio.sleep(_INTER_AGENT_DELAY)
 
-        # Brief pause before final decision
         await asyncio.sleep(_INTER_AGENT_DELAY)
-        decision = await self.ceo.make_final_decision(
+        decision, final_usage = await self.ceo.make_final_decision(
             context,
             self.last_discussion_history,
         )
+        total_prompt += final_usage.get("prompt_tokens", 0)
+        total_completion += final_usage.get("completion_tokens", 0)
+
+        logger.info(
+            "Discussion complete: %d messages, decision has %d prices, tokens=%d",
+            len(self.last_discussion_history),
+            len(decision.pricing),
+            total_prompt + total_completion,
+        )
+
+        token_usage = {
+            "prompt_tokens": total_prompt,
+            "completion_tokens": total_completion,
+            "total_tokens": total_prompt + total_completion,
+        }
+        return decision, token_usage
+
+    async def run_react(
+        self,
+        public_ctx: PublicContext,
+        private_ctx: PrivateContext,
+        tools: ToolRegistry,
+    ) -> tuple[ERPSimDecision, dict]:
+        """ReAct-enhanced discussion: agents gather data independently → discuss → CEO decides.
+
+        Flow:
+        1. Each agent independently runs react_loop to gather data
+        2. Agents share their assessments in N discussion rounds
+        3. CEO runs react_decision for the final structured decision
+
+        Returns:
+            Tuple of (ERPSimDecision, token_usage dict).
+        """
+        self.last_discussion_history = []
+        total_prompt = 0
+        total_completion = 0
+
+        # Phase 1: Independent ReAct (each agent gathers data)
+        agent_assessments: dict[str, str] = {}
+        for agent in self.agents:
+            task = self._get_agent_task(agent.role)
+            assessment = await agent.react_loop(public_ctx, private_ctx, tools, task)
+            agent_assessments[agent.role] = assessment
+            await asyncio.sleep(_INTER_AGENT_DELAY)
+
+        # Phase 2: Discussion rounds (agents share assessments)
+        for round_num in range(1, self.max_rounds + 1):
+            for agent in self.agents:
+                # Build discussion prompt including previous assessments
+                history_text = self._format_history_for_discussion()
+
+                other_assessments = {
+                    role: assessment[:500]
+                    for role, assessment in agent_assessments.items()
+                    if role != agent.role
+                }
+                others_text = "\n".join(
+                    f"{role}: {text}" for role, text in other_assessments.items()
+                )
+
+                prompt = (
+                    f"You are in a team discussion for Round {public_ctx.round_number}.\n\n"
+                    f"Your team members have shared their analyses:\n{others_text}\n\n"
+                    f"Discussion so far:\n{history_text}\n\n"
+                    f"As {agent.display_name}, provide your perspective. "
+                    f"Keep your response concise (2-3 paragraphs)."
+                )
+
+                messages = [
+                    {"role": "user", "content": prompt},
+                ]
+                response = await agent.llm_client.chat(
+                    messages, temperature=0.3, max_tokens=4096
+                )
+                usage = response.usage
+                pt = usage.get("prompt_tokens", 0)
+                ct = usage.get("completion_tokens", 0)
+                total_prompt += pt
+                total_completion += ct
+                self.last_discussion_history.append(
+                    {
+                        "round": round_num,
+                        "role": agent.role,
+                        "content": response.content,
+                        "token_count": pt + ct,
+                    }
+                )
+                await asyncio.sleep(_INTER_AGENT_DELAY)
+
+        # Phase 3: CEO final ReAct decision
+        discussion_summary = self._format_history_for_discussion()
+        decision = await self.ceo.react_decision(
+            public_ctx, private_ctx, tools, discussion_summary
+        )
 
         logger.info(
-            "Discussion complete: %d messages, decision has %d prices",
+            "ReAct discussion complete: %d messages, decision has %d prices, tokens=%d",
             len(self.last_discussion_history),
             len(decision.pricing),
+            total_prompt + total_completion,
+        )
+
+        token_usage = {
+            "prompt_tokens": total_prompt,
+            "completion_tokens": total_completion,
+            "total_tokens": total_prompt + total_completion,
+        }
+        return decision, token_usage
+
+    def _get_agent_task(self, role: str) -> str:
+        """Return a role-specific task description for ReAct."""
+        tasks = {
+            "CEO": (
+                "Analyze the overall business situation. Check financial health, "
+                "production capacity, and market conditions. Identify key risks and opportunities."
+            ),
+            "CFO": (
+                "Analyze the financial situation. Check cash position, loan status, "
+                "interest payments, and revenue trends. Identify cost optimization opportunities."
+            ),
+            "CMO": (
+                "Analyze the market situation. Check sales performance by SKU and DC, "
+                "competitor pricing, market share, and demand patterns."
+            ),
+        }
+        return tasks.get(
+            role, "Analyze the current situation and prepare your assessment."
         )
 
-        return decision
+    def _format_history_for_discussion(self) -> str:
+        """Format discussion history as text."""
+        lines = []
+        for msg in self.last_discussion_history:
+            lines.append(f"{msg['role']}: {msg['content'][:300]}")
+        return "\n".join(lines)