tcm-cli 0.1.0__py3-none-any.whl

tcm/__init__.py

@@ -0,0 +1,3 @@
+"""tcm-cli: An autonomous agent for Traditional Chinese Medicine research and discovery."""
+
+__version__ = "0.1.0"

tcm/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent components: planner, executor, synthesizer, session management."""

tcm/agent/config.py

@@ -0,0 +1,229 @@
+"""
+Configuration management for tcm.
+
+Config is stored at ~/.tcm/config.json and manages:
+- LLM provider settings (Anthropic, OpenAI)
+- Data directory paths (TCMSP, TCMID, etc.)
+- Output preferences
+- Agent settings
+"""
+
+import json
+import os
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from rich.table import Table
+
+CONFIG_DIR = Path.home() / ".tcm"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+VALID_LLM_PROVIDERS = frozenset({"anthropic", "openai"})
+logger = logging.getLogger("tcm.config")
+
+DEFAULTS = {
+    "llm.provider": "anthropic",
+    "llm.model": "claude-sonnet-4-5-20250929",
+    "llm.api_key": None,
+    "llm.openai_api_key": None,
+    "llm.temperature": 0.1,
+
+    "data.base": str(CONFIG_DIR / "data"),
+    "data.tcmsp": None,
+    "data.tcmid": None,
+    "data.herbs": None,
+    "data.formulas": None,
+    "data.batman": None,
+    "data.symmap": None,
+
+    "output.format": "markdown",
+    "output.verbose": False,
+    "output.auto_publish_html_interactive": True,
+    "output.auto_publish_html_batch": False,
+
+    "ui.spinner": "dots",
+    "ui.language": "en",  # "en" or "zh"
+
+    "sandbox.timeout": 30,
+    "sandbox.output_dir": str(Path.cwd() / "outputs"),
+    "sandbox.max_retries": 2,
+
+    "agent.max_iterations": 3,
+    "agent.enable_experimental_tools": False,
+    "agent.executor_max_retries": 2,
+    "agent.executor_loop_limit": 50,
+    "agent.synthesis_max_tokens": 8192,
+    "agent.enforce_grounded_synthesis": True,
+    "agent.confidence_scoring_enabled": True,
+    "agent.min_step_success_rate": 0.5,
+    "agent.allow_creative_hypotheses": True,
+    "agent.max_hypotheses": 3,
+    "agent.profile": "research",
+    "agent.planner_max_tools": 60,
+    "agent.tool_health_enabled": True,
+    "agent.tool_health_fail_threshold": 2,
+    "agent.tool_health_failure_window_s": 1800,
+    "agent.tool_health_suppress_seconds": 900,
+}
+
+AGENT_PROFILE_PRESETS = {
+    "research": {
+        "agent.enforce_grounded_synthesis": True,
+        "agent.allow_creative_hypotheses": True,
+        "agent.confidence_scoring_enabled": True,
+    },
+    "clinical": {
+        "agent.enforce_grounded_synthesis": True,
+        "agent.allow_creative_hypotheses": False,
+        "agent.confidence_scoring_enabled": True,
+    },
+    "education": {
+        "agent.enforce_grounded_synthesis": False,
+        "agent.allow_creative_hypotheses": True,
+        "agent.confidence_scoring_enabled": False,
+    },
+}
+
+
+class Config:
+    """Manages tcm configuration."""
+
+    def __init__(self, data: dict = None):
+        self._data = data or {}
+
+    @classmethod
+    def load(cls) -> "Config":
+        """Load config from ~/.tcm/config.json, falling back to defaults."""
+        if CONFIG_FILE.exists():
+            try:
+                raw = json.loads(CONFIG_FILE.read_text())
+                return cls(data=raw)
+            except (json.JSONDecodeError, OSError) as exc:
+                logger.warning("Failed to load config: %s", exc)
+        return cls()
+
+    def save(self):
+        """Persist config to ~/.tcm/config.json."""
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        CONFIG_FILE.write_text(json.dumps(self._data, indent=2) + "\n")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a config value, falling back to DEFAULTS then the provided default."""
+        if key in self._data:
+            return self._data[key]
+        if key in DEFAULTS:
+            return DEFAULTS[key]
+        return default
+
+    def set(self, key: str, value: Any):
+        """Set a config value.
+
+        Special handling:
+        - llm.provider: validates against known providers.
+        - llm.model: auto-detects and sets the matching provider.
+        - agent.profile: applies profile presets.
+        """
+        if key == "llm.provider" and value not in VALID_LLM_PROVIDERS:
+            raise ValueError(
+                f"Invalid provider '{value}'. Valid: {', '.join(sorted(VALID_LLM_PROVIDERS))}"
+            )
+        if key == "llm.model":
+            from tcm.models.llm import resolve_provider, MODEL_CATALOG
+            provider = resolve_provider(value)
+            if provider:
+                self._data["llm.provider"] = provider
+            if value not in MODEL_CATALOG:
+                logger.warning(
+                    "Model '%s' is not in the catalog — it may still work if your provider supports it.",
+                    value,
+                )
+        if key == "agent.profile":
+            preset = AGENT_PROFILE_PRESETS.get(value)
+            if not preset:
+                raise ValueError(
+                    f"Unknown profile '{value}'. "
+                    f"Valid: {', '.join(sorted(AGENT_PROFILE_PRESETS))}"
+                )
+            for pk, pv in preset.items():
+                self._data[pk] = pv
+        self._data[key] = value
+
+    def llm_api_key(self, provider: str = None) -> Optional[str]:
+        """Get the API key for the given LLM provider."""
+        provider = provider or self.get("llm.provider", "anthropic")
+        if provider == "anthropic":
+            return (
+                self._data.get("llm.api_key")
+                or os.environ.get("ANTHROPIC_API_KEY")
+            )
+        elif provider == "openai":
+            return (
+                self._data.get("llm.openai_api_key")
+                or os.environ.get("OPENAI_API_KEY")
+            )
+        return None
+
+    def validate(self) -> list[str]:
+        """Validate configuration and return a list of issues."""
+        issues = []
+        known_keys = set(DEFAULTS.keys())
+        for key in self._data:
+            if key not in known_keys:
+                issues.append(f"Unknown config key '{key}' (possible typo)")
+        # Type checks
+        for key, value in self._data.items():
+            if key not in DEFAULTS or value is None:
+                continue
+            default = DEFAULTS[key]
+            if default is None:
+                continue
+            expected_type = type(default)
+            if expected_type == bool and not isinstance(value, bool):
+                issues.append(f"'{key}' should be bool, got {type(value).__name__}")
+            elif expected_type in (int, float) and not isinstance(value, (int, float)):
+                issues.append(f"'{key}' should be numeric, got {type(value).__name__}")
+        return issues
+
+    def to_table(self) -> Table:
+        """Render config as a Rich table."""
+        table = Table(title="tcm Configuration")
+        table.add_column("Key", style="cyan")
+        table.add_column("Value")
+        table.add_column("Source", style="dim")
+
+        for key in sorted(DEFAULTS):
+            if key.endswith("api_key"):
+                val = self.get(key)
+                if val:
+                    val = val[:7] + "..." + val[-4:] if len(val) > 11 else "***"
+                else:
+                    val = "(not set)"
+                source = "config" if key in self._data else "default"
+            else:
+                val = str(self.get(key))
+                source = "config" if key in self._data else "default"
+            table.add_row(key, val, source)
+        return table
+
+    def keys_table(self) -> Table:
+        """Show API key status table."""
+        table = Table(title="API Keys")
+        table.add_column("Service", style="cyan")
+        table.add_column("Status")
+        table.add_column("Description")
+
+        # Anthropic
+        key = self.llm_api_key("anthropic")
+        status = "[green]✓ configured[/green]" if key else "[red]✗ missing[/red]"
+        table.add_row("Anthropic", status, "Primary LLM provider")
+
+        # OpenAI
+        key = self.llm_api_key("openai")
+        status = "[green]✓ configured[/green]" if key else "[dim]○ optional[/dim]"
+        table.add_row("OpenAI", status, "Alternative LLM provider")
+
+        return table

tcm/agent/doctor.py

@@ -0,0 +1,92 @@
+"""
+Health checks for tcm CLI.
+"""
+
+import shutil
+import sys
+from rich.table import Table
+
+
+def run_checks(config, session=None) -> list[dict]:
+    """Run all health checks. Returns list of check results."""
+    checks = []
+
+    # Python version
+    py_ver = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    py_ok = sys.version_info >= (3, 10)
+    checks.append({
+        "name": "Python version",
+        "status": "ok" if py_ok else "error",
+        "detail": f"Python {py_ver}" + ("" if py_ok else " (need 3.10+)"),
+    })
+
+    # Anthropic API key
+    key = config.llm_api_key("anthropic")
+    checks.append({
+        "name": "Anthropic API key",
+        "status": "ok" if key else "error",
+        "detail": "configured" if key else "missing — run `tcm setup`",
+    })
+
+    # Core dependencies
+    for pkg in ["anthropic", "rich", "typer", "httpx", "prompt_toolkit"]:
+        try:
+            __import__(pkg)
+            checks.append({"name": f"Package: {pkg}", "status": "ok", "detail": "installed"})
+        except ImportError:
+            checks.append({"name": f"Package: {pkg}", "status": "error", "detail": "not installed"})
+
+    # Optional dependencies
+    for pkg, label in [("pandas", "pandas"), ("numpy", "numpy"), ("rdkit", "RDKit (chemistry)")]:
+        try:
+            __import__(pkg)
+            checks.append({"name": f"Optional: {label}", "status": "ok", "detail": "installed"})
+        except ImportError:
+            checks.append({"name": f"Optional: {label}", "status": "info", "detail": "not installed (optional)"})
+
+    # Tool loading
+    from tcm.tools import ensure_loaded, tool_load_errors
+    ensure_loaded()
+    errors = tool_load_errors()
+    if errors:
+        checks.append({
+            "name": "Tool modules",
+            "status": "warn",
+            "detail": f"{len(errors)} module(s) failed to load: {', '.join(errors.keys())}",
+        })
+    else:
+        from tcm.tools import registry
+        checks.append({
+            "name": "Tool modules",
+            "status": "ok",
+            "detail": f"{len(registry.list_tools())} tools loaded",
+        })
+
+    return checks
+
+
+def to_table(checks: list[dict]) -> Table:
+    """Render checks as a Rich table."""
+    table = Table(title="tcm doctor")
+    table.add_column("Check", style="cyan")
+    table.add_column("Status")
+    table.add_column("Detail")
+
+    for check in checks:
+        status = check["status"]
+        if status == "ok":
+            icon = "[green]✓[/green]"
+        elif status == "warn":
+            icon = "[yellow]⚠[/yellow]"
+        elif status == "info":
+            icon = "[dim]○[/dim]"
+        else:
+            icon = "[red]✗[/red]"
+        table.add_row(check["name"], icon, check["detail"])
+
+    return table
+
+
+def has_errors(checks: list[dict]) -> bool:
+    """Check if any health check failed."""
+    return any(c["status"] == "error" for c in checks)

tcm/agent/executor.py

@@ -0,0 +1,122 @@
+"""
+Plan executor: iterates plan steps, calls tools, handles errors/retries.
+"""
+
+import json
+import logging
+import time
+from rich.console import Console
+from rich.panel import Panel
+
+from tcm.agent.session import Session
+from tcm.tools import registry, ensure_loaded
+
+logger = logging.getLogger("tcm.agent.executor")
+console = Console()
+
+
+def execute_plan(session: Session, plan: dict, verbose: bool = False) -> list[dict]:
+    """Execute a research plan step by step.
+
+    Args:
+        session: Active session with LLM and config.
+        plan: Plan dict with 'steps' list.
+        verbose: Whether to print step details.
+
+    Returns:
+        List of step results.
+    """
+    ensure_loaded()
+    steps = plan.get("steps", [])
+    results = []
+
+    if not steps:
+        # No tool steps — this was a direct LLM response
+        return [{"step": 0, "tool": "llm_direct", "result": plan.get("reasoning", ""), "status": "success"}]
+
+    max_retries = int(session.config.get("agent.executor_max_retries", 2))
+
+    for step in steps:
+        step_num = step.get("step", len(results) + 1)
+        tool_name = step.get("tool", "")
+        parameters = step.get("parameters", {})
+        purpose = step.get("purpose", "")
+
+        if verbose:
+            console.print(f"  [cyan]Step {step_num}[/cyan]: {tool_name} — {purpose}")
+
+        tool = registry.get_tool(tool_name)
+        if not tool:
+            result = {
+                "step": step_num,
+                "tool": tool_name,
+                "status": "error",
+                "error": f"Tool '{tool_name}' not found.",
+            }
+            results.append(result)
+            continue
+
+        # Substitute references to previous results
+        resolved_params = _resolve_params(parameters, results)
+
+        # Execute with retry
+        result = _execute_with_retry(session, tool, resolved_params, max_retries)
+        result["step"] = step_num
+        result["tool"] = tool_name
+        result["purpose"] = purpose
+
+        if verbose:
+            status_icon = "✓" if result["status"] == "success" else "✗"
+            color = "green" if result["status"] == "success" else "red"
+            console.print(f"    [{color}]{status_icon}[/{color}] {result['status']}")
+
+        results.append(result)
+
+    return results
+
+
+def _execute_with_retry(session: Session, tool, parameters: dict, max_retries: int) -> dict:
+    """Execute a tool with retry logic."""
+    for attempt in range(1, max_retries + 1):
+        try:
+            output = tool.run(**parameters)
+            session.record_tool_success(tool.name)
+            return {"status": "success", "output": output}
+        except Exception as e:
+            error_text = str(e)
+            logger.warning("Tool %s failed (attempt %d): %s", tool.name, attempt, error_text)
+            session.record_tool_failure(tool.name, error_text)
+
+            if attempt >= max_retries:
+                return {"status": "error", "error": error_text}
+            time.sleep(1)
+
+    return {"status": "error", "error": "Max retries exceeded"}
+
+
+def _resolve_params(parameters: dict, previous_results: list) -> dict:
+    """Resolve parameter references like '$step1.output.targets' to actual values."""
+    resolved = {}
+    for key, value in parameters.items():
+        if isinstance(value, str) and value.startswith("$step"):
+            try:
+                # Parse reference like "$step1.output.targets"
+                parts = value[1:].split(".")
+                step_ref = int(parts[0].replace("step", "")) - 1
+                if 0 <= step_ref < len(previous_results):
+                    result = previous_results[step_ref]
+                    obj = result
+                    for part in parts[1:]:
+                        if isinstance(obj, dict):
+                            obj = obj.get(part, value)
+                        else:
+                            obj = value
+                            break
+                    resolved[key] = obj
+                else:
+                    resolved[key] = value
+            except (ValueError, IndexError):
+                resolved[key] = value
+        else:
+            resolved[key] = value
+    return resolved

tcm/agent/planner.py

@@ -0,0 +1,90 @@
+"""
+Research planner: takes user query → calls LLM with tool catalog → returns ordered plan.
+"""
+
+import json
+import logging
+from tcm.agent.session import Session
+from tcm.tools import registry, ensure_loaded
+
+logger = logging.getLogger("tcm.agent.planner")
+
+PLANNER_SYSTEM = """You are an expert Traditional Chinese Medicine (TCM) research assistant.
+You have access to a set of computational tools for TCM research.
+
+Given a user's research question, create a step-by-step execution plan.
+
+RULES:
+1. Select only the tools needed to answer the question.
+2. Order steps logically — later steps can depend on earlier results.
+3. Each step must specify exactly one tool and its parameters.
+4. Be conservative — only include steps that directly help answer the question.
+5. If the question is simple and can be answered with 1-2 tools, keep the plan short.
+
+OUTPUT FORMAT (strict JSON):
+{
+  "reasoning": "Brief explanation of your approach",
+  "steps": [
+    {
+      "step": 1,
+      "tool": "category.tool_name",
+      "parameters": {"param1": "value1"},
+      "purpose": "Why this step is needed"
+    }
+  ]
+}
+
+AVAILABLE TOOLS:
+"""
+
+
+def create_plan(session: Session, query: str, mention_context: str = "") -> dict:
+    """Create a research plan for the given query.
+
+    Returns:
+        dict with 'reasoning' and 'steps' keys.
+    """
+    ensure_loaded()
+
+    # Build tool catalog for the planner
+    suppressed = session.tool_health_suppressed_tools()
+    tool_catalog = registry.tool_descriptions_for_llm(
+        exclude_tools=suppressed,
+    )
+
+    system_prompt = PLANNER_SYSTEM + tool_catalog
+
+    if mention_context:
+        system_prompt += f"\n\nUSER CONTEXT:\n{mention_context}"
+
+    messages = [{"role": "user", "content": query}]
+
+    llm = session.get_llm()
+    response = llm.chat(
+        system=system_prompt,
+        messages=messages,
+        temperature=0.1,
+        max_tokens=2048,
+    )
+
+    # Parse the plan from LLM response
+    try:
+        # Try to extract JSON from the response
+        content = response.content.strip()
+        # Handle markdown code blocks
+        if "```json" in content:
+            content = content.split("```json")[1].split("```")[0].strip()
+        elif "```" in content:
+            content = content.split("```")[1].split("```")[0].strip()
+
+        plan = json.loads(content)
+        if "steps" not in plan:
+            plan = {"reasoning": "Direct response", "steps": []}
+        return plan
+    except (json.JSONDecodeError, IndexError):
+        logger.warning("Failed to parse plan JSON, returning raw response")
+        return {
+            "reasoning": response.content,
+            "steps": [],
+            "raw_response": True,
+        }

tcm/agent/session.py

@@ -0,0 +1,129 @@
+"""
+Session management: holds config, LLM clients, and shared state for a tcm session.
+"""
+
+import time
+from pathlib import Path
+from rich.console import Console
+
+from tcm.agent.config import Config
+
+
+class Session:
+    """Manages state for a tcm research session."""
+
+    def __init__(self, config: Config = None, verbose: bool = False, mode: str = "batch"):
+        self.config = config or Config.load()
+        self.verbose = verbose
+        self.mode = mode  # "interactive" or "batch"
+        self.console = Console()
+        self._llm = None
+        self._scratchpad = []
+        self._tool_health_failures: dict[str, list[float]] = {}
+        self._tool_health_suppressed_until: dict[str, float] = {}
+
+    def get_llm(self):
+        """Get or create the LLM client based on config."""
+        if self._llm is None:
+            self._llm = self._create_llm()
+        return self._llm
+
+    def _create_llm(self):
+        """Create LLM client from config."""
+        from tcm.models.llm import LLMClient
+
+        provider = self.config.get("llm.provider", "anthropic")
+        model = self.config.get("llm.model", None)
+        api_key = self.config.llm_api_key(provider)
+
+        return LLMClient(
+            provider=provider,
+            model=model,
+            api_key=api_key,
+        )
+
+    def set_model(self, model: str, provider: str = None):
+        """Switch the LLM model mid-session.
+
+        Provider is auto-detected from the model name if not given.
+        """
+        if provider:
+            self.config.set("llm.provider", provider)
+        # Config.set("llm.model", ...) auto-detects provider
+        self.config.set("llm.model", model)
+        self._llm = None
+
+    @property
+    def current_model(self) -> str:
+        """Return the current model name."""
+        if self._llm:
+            return self._llm.model
+        return self.config.get("llm.model") or "claude-sonnet-4-5-20250929"
+
+    def log(self, message: str):
+        """Log to scratchpad."""
+        self._scratchpad.append(message)
+        if self.verbose:
+            self.console.print(f"  [dim]{message}[/dim]")
+
+    def save_scratchpad(self, path: Path):
+        """Save scratchpad to file for debugging."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("\n".join(self._scratchpad))
+
+    # --- Runtime tool-health tracking ---
+
+    def _tool_health_enabled(self) -> bool:
+        return bool(self.config.get("agent.tool_health_enabled", True))
+
+    def _is_transient_tool_error(self, error_text: str) -> bool:
+        text = str(error_text or "").lower()
+        transient_markers = (
+            "timeout", "timed out", "connection", "dns",
+            "service unavailable", "rate limit", "429",
+            "500", "502", "503", "504",
+        )
+        return any(marker in text for marker in transient_markers)
+
+    def record_tool_success(self, tool_name: str):
+        """Clear runtime failure pressure after a successful execution."""
+        if not tool_name:
+            return
+        self._tool_health_failures.pop(tool_name, None)
+        self._tool_health_suppressed_until.pop(tool_name, None)
+
+    def record_tool_failure(self, tool_name: str, error_text: str = ""):
+        """Record transient tool failures and suppress flaky tools temporarily."""
+        if not self._tool_health_enabled() or not tool_name:
+            return
+        if not self._is_transient_tool_error(error_text):
+            return
+
+        now = time.time()
+        window_s = max(60, int(self.config.get("agent.tool_health_failure_window_s", 1800)))
+        threshold = max(1, int(self.config.get("agent.tool_health_fail_threshold", 2)))
+        suppress_s = max(60, int(self.config.get("agent.tool_health_suppress_seconds", 900)))
+
+        history = [t for t in self._tool_health_failures.get(tool_name, []) if now - t <= window_s]
+        history.append(now)
+        self._tool_health_failures[tool_name] = history
+
+        if len(history) >= threshold:
+            self._tool_health_suppressed_until[tool_name] = now + suppress_s
+
+    def tool_health_suppressed_tools(self) -> set[str]:
+        """Return tools currently suppressed due to repeated transient failures."""
+        if not self._tool_health_enabled():
+            return set()
+        now = time.time()
+        suppressed = set()
+        expired = []
+        for name, until in self._tool_health_suppressed_until.items():
+            if now < until:
+                suppressed.add(name)
+            else:
+                expired.append(name)
+        for name in expired:
+            self._tool_health_suppressed_until.pop(name, None)
+            self._tool_health_failures.pop(name, None)
+        return suppressed