aria-code 4.1.3__py3-none-any.whl

memory_manager.py

@@ -0,0 +1,245 @@
+"""
+memory_manager.py — Aria Code 全局用户 memory 系统
+
+存储位置：~/.arthera/memory/
+  MEMORY.md                ← 索引（每次启动加载）
+  user_profile.md          ← 用户偏好、交易风格
+  project_<slug>.md        ← /project load 时自动建档
+  research_<topic>.md      ← 研究主题（用户触发时创建）
+
+公开 API：
+  MemoryManager.load_context(max_chars)  → 注入 system prompt
+  MemoryManager.append(slug, content)    → 追加一条事实
+  MemoryManager.upsert_project(name, facts) → 项目建档
+  MemoryManager.list_all()               → 所有条目
+  MemoryManager.clear_all()              → 清空全局 memory
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_MEMORY_DIR = Path.home() / ".arthera" / "memory"
+_INDEX_FILE = _MEMORY_DIR / "MEMORY.md"
+
+_PREF_PATTERNS = [
+    (r"(我?不喜欢|我?喜欢|prefer(?:ence)?s?|I always|I never|我总是|我通常)", "preference"),
+    (r"(我的风险|风险偏好|risk.*(?:低|高|中|保守|激进)|conservative|aggressive)", "risk_profile"),
+    (r"(?:关注|研究|在看|tracking|watching)\s*([A-Z0-9，,、和与&/\s]{2,40})", "watchlist"),
+    (r"(我的策略|my strategy|我用|I use)\s+(.{4,40})", "strategy"),
+]
+
+_SENSITIVE_PATTERN = re.compile(
+    r"(\d+[\.,]\d{2,}(?:%|元|USD|HKD|CNY|万|亿)?|持仓|盈亏|亏损|盈利|买入|卖出|成本价)"
+)
+
+
+def _slugify(name: str) -> str:
+    name = re.sub(r"[^\w\-]", "_", name.lower())
+    return re.sub(r"_+", "_", name).strip("_")[:40]
+
+
+class MemoryManager:
+    def __init__(self, root: Optional[Path] = None):
+        self.root = root or _MEMORY_DIR
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._index = self.root / "MEMORY.md"
+
+    # ── Index management ──────────────────────────────────────────────────────
+
+    def _read_index(self) -> list[dict]:
+        if not self._index.exists():
+            return []
+        entries = []
+        for line in self._index.read_text(encoding="utf-8").splitlines():
+            m = re.match(r"-\s+\[(.+?)\]\((.+?)\)\s*—\s*(.*)", line)
+            if m:
+                entries.append({"title": m.group(1), "file": m.group(2), "summary": m.group(3)})
+        return entries
+
+    def _write_index(self, entries: list[dict]) -> None:
+        lines = ["# Aria Memory Index\n"]
+        for e in entries:
+            lines.append(f"- [{e['title']}]({e['file']}) — {e['summary']}")
+        self._index.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    def _upsert_index(self, file: str, title: str, summary: str) -> None:
+        entries = self._read_index()
+        for e in entries:
+            if e["file"] == file:
+                e["title"] = title
+                e["summary"] = summary
+                self._write_index(entries)
+                return
+        entries.append({"title": title, "file": file, "summary": summary})
+        self._write_index(entries)
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def load_context(self, max_chars: int = 500) -> str:
+        """Return a compact memory block for injection into the system prompt."""
+        if not self._index.exists():
+            return ""
+        snippets = []
+        for entry in self._read_index():
+            fpath = self.root / entry["file"]
+            if not fpath.exists():
+                continue
+            text = fpath.read_text(encoding="utf-8").strip()
+            lines = [l for l in text.splitlines() if l.strip() and not l.startswith("#")]
+            snippets.extend(lines[:6])
+
+        if not snippets:
+            return ""
+
+        block = "\n".join(snippets)
+        if len(block) > max_chars:
+            block = block[:max_chars] + "…"
+        return f"## User Memory\n{block}\n"
+
+    def append(self, slug: str, content: str, title: Optional[str] = None) -> None:
+        """Append a fact to slug.md, creating the file if needed."""
+        if _SENSITIVE_PATTERN.search(content):
+            logger.debug("Memory: skipping sensitive content: %s…", content[:40])
+            return
+
+        slug = _slugify(slug)
+        fpath = self.root / f"{slug}.md"
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+
+        if not fpath.exists():
+            _title = title or slug.replace("_", " ").title()
+            fpath.write_text(f"# {_title}\n\n", encoding="utf-8")
+            self._upsert_index(fpath.name, _title, content[:80])
+
+        with fpath.open("a", encoding="utf-8") as f:
+            f.write(f"- [{ts}] {content}\n")
+
+        entry = next((e for e in self._read_index() if e["file"] == fpath.name), None)
+        if entry:
+            entry["summary"] = content[:80]
+            self._write_index(self._read_index())
+
+        logger.debug("Memory: appended to %s: %s", fpath.name, content[:60])
+
+    def upsert_project(self, name: str, facts: dict) -> None:
+        """Create or refresh a project memory file."""
+        slug = f"project_{_slugify(name)}"
+        fpath = self.root / f"{slug}.md"
+        langs = ", ".join(facts.get("languages", [])[:4]) or "unknown"
+        ptype = facts.get("type", "unknown")
+        root  = facts.get("root", "")
+        ts    = facts.get("last_loaded", datetime.now().isoformat())[:10]
+        syms  = ", ".join(facts.get("default_symbols", [])[:5])
+
+        lines = [
+            f"# Project: {name}",
+            f"",
+            f"- **type**: {ptype}",
+            f"- **languages**: {langs}",
+            f"- **root**: {root}",
+            f"- **last loaded**: {ts}",
+        ]
+        if syms:
+            lines.append(f"- **default symbols**: {syms}")
+
+        fpath.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        summary = f"{ptype} · {langs} · last {ts}"
+        self._upsert_index(fpath.name, f"Project: {name}", summary)
+        logger.debug("Memory: upserted project %s", name)
+
+    def list_all(self) -> list[dict]:
+        """Return all memory entries with their file content."""
+        result = []
+        for entry in self._read_index():
+            fpath = self.root / entry["file"]
+            content = fpath.read_text(encoding="utf-8").strip() if fpath.exists() else ""
+            result.append({**entry, "content": content})
+        return result
+
+    def clear_all(self) -> int:
+        """Delete all memory files and reset the index. Returns count deleted."""
+        count = 0
+        for fpath in self.root.glob("*.md"):
+            if fpath.name != "MEMORY.md":
+                fpath.unlink()
+                count += 1
+        self._index.write_text("# Aria Memory Index\n", encoding="utf-8")
+        return count
+
+    def fact_count(self) -> int:
+        return len(self._read_index())
+
+
+# ── Preference signal extractor (rule-based, zero LLM cost) ──────────────────
+
+# Patterns that signal a user revealed an actionable fact mid-conversation
+_MID_CONV_PATTERNS = [
+    # Explicit remember requests
+    (r"(记住|帮我记|remember that|please remember|note that)\s+(.{5,80})", "user_note"),
+    # Risk / style preferences revealed mid-chat
+    (r"(我(的)?风险|my risk|风险偏好|risk preference|risk tolerance)[^。.]{0,40}(低|高|中|保守|激进|低风险|高风险)", "risk_profile"),
+    (r"(我(喜欢|偏好|倾向|通常用)|I (prefer|like|usually use|always use))\s*(.{4,60})", "preference"),
+    # Symbols the user says they're tracking (single or multiple)
+    (r"(我(在看|关注|持有|跟踪)|I('m)? (watching|tracking|holding))\s*(.{2,40})", "watchlist"),
+    # Explicit remember / 记住 requests
+    (r"(记住|帮我记|please remember|note that)\s*(.{4,80})", "user_note"),
+    # Stop-loss / take-profit thresholds
+    (r"(止损|止盈|stop[- ]loss|take[- ]profit)[^\d]{0,10}(\d+\.?\d*\s*%)", "trading_rule"),
+    # Portfolio size hint (non-sensitive: just "大仓位" not actual amounts)
+    (r"(大仓|小仓|主仓|重仓|满仓|空仓|half position|full position|light position)", "position_style"),
+]
+
+_SENSITIVE_PATTERN_STRICT = re.compile(
+    r"(\d[\d,，.]+(?:万|亿|元|USD|CNY|HKD|K|M)?|\b\d{5,}\b|持仓金额|账户余额|本金)"
+)
+
+
+def extract_preference_signal(user_msg: str, assistant_response: str) -> Optional[str]:
+    """Detect preference/fact signals worth persisting from a user message.
+
+    Returns a single-line fact string or None. Conservative by design —
+    most queries return None. Skips anything containing sensitive amounts.
+    """
+    # CJK characters are each 1 codepoint but convey more meaning per char,
+    # so use a shorter minimum (8 chars) to avoid filtering valid short acks.
+    if len(assistant_response) < 8:
+        return None
+    if _SENSITIVE_PATTERN.search(user_msg) or _SENSITIVE_PATTERN_STRICT.search(user_msg):
+        return None
+
+    for pattern, category in _PREF_PATTERNS + _MID_CONV_PATTERNS:
+        m = re.search(pattern, user_msg, re.IGNORECASE)
+        if m:
+            snippet = user_msg[:120].strip().replace("\n", " ")
+            return f"[{category}] {snippet}"
+
+    return None
+
+
+def auto_capture_from_turn(
+    user_msg: str,
+    assistant_response: str,
+    memory: "MemoryManager",
+) -> Optional[str]:
+    """Called after each agent turn to auto-persist any detectable user preferences.
+
+    Returns the captured fact string if something was saved, else None.
+    This is intentionally lightweight: it runs synchronously after every turn
+    and must not block or throw.
+    """
+    try:
+        fact = extract_preference_signal(user_msg, assistant_response)
+        if fact:
+            memory.append("user_preferences", fact, title="用户偏好与设置")
+            return fact
+    except Exception:
+        pass
+    return None

model_capability.py

@@ -0,0 +1,416 @@
+"""
+model_capability.py — Aria Code model capability registry & tool-call adapter.
+
+Responsibilities:
+  - Know which local models support native tool calling vs text-based <tool_call>
+  - Normalise tool call output across Ollama-native / XML-tag / JSON-fenced formats
+  - Inject the correct tool schema format into the Ollama payload
+  - Detect capability dynamically when a model is not in the registry
+
+Usage::
+
+    from model_capability import get_model_capability, build_ollama_tool_payload
+
+    caps = get_model_capability("qwen2.5-coder:7b")
+    # {"tool_calls": True, "format": "ollama_native", "context_window": 32768, ...}
+
+    calls = parse_tool_calls_from_response(full_text, native_tool_calls)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+# ---------------------------------------------------------------------------
+# Capability catalogue
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ModelCapability:
+    # Whether the model reliably produces structured tool calls
+    tool_calls: bool = False
+    # "ollama_native"  → Ollama's message.tool_calls list
+    # "xml_tags"       → <tool_call>{"name":…,"arguments":{…}}</tool_call>
+    # "json_fence"     → ```json\n{"tool":…,"arguments":{…}}\n```
+    # "text_only"      → no tool calling; prompt must ask for plain-text answers
+    # "router_only"    → model is only suitable for intent classification / routing;
+    #                    MUST NOT handle coding, analysis, or multi-step tasks
+    format: str = "text_only"
+    context_window: int = 8192
+    thinking: bool = False          # extended-reasoning / <think> tokens
+    vision: bool = False            # supports image / multimodal input
+    finance_tuned: bool = False     # model has finance-domain fine-tuning
+    # Recommended sampling params
+    temperature: float = 0.3
+    top_p: float = 0.9
+    # Maximum simultaneous tool calls per round (safety limit)
+    max_parallel_tools: int = 1
+    # Minimum model size class: "nano" <1B / "small" 1-4B / "medium" 4-14B / "large" >14B
+    size_class: str = "medium"
+    # Extra notes shown in /models list
+    notes: str = ""
+
+
+def is_router_only(cap: "ModelCapability") -> bool:
+    """Return True if this model must NOT handle complex tasks (coding/analysis)."""
+    return cap.format == "router_only"
+
+
+def can_handle_coding(cap: "ModelCapability") -> bool:
+    """Return True if the model is large/capable enough for code generation tasks."""
+    return (
+        cap.format in ("ollama_native", "xml_tags", "anthropic_native")
+        and cap.context_window >= 8192
+        and cap.size_class not in ("nano",)
+    )
+
+
+def can_handle_analysis(cap: "ModelCapability") -> bool:
+    """Return True if the model can handle multi-step financial analysis."""
+    return (
+        cap.format not in ("router_only",)
+        and cap.context_window >= 4096
+        and cap.size_class not in ("nano",)
+    )
+
+
+# Prefix → capability mapping.  Longest prefix wins.
+_CAPABILITY_TABLE: Dict[str, ModelCapability] = {
+    # ── Qwen family ────────────────────────────────────────────────────────
+    "qwen2.5-coder:32b":    ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.2, size_class="large",  notes="Best local code+finance model"),
+    "qwen2.5-coder:14b":    ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.2, size_class="large"),
+    "qwen2.5-coder:7b":     ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.2, size_class="medium"),
+    "qwen2.5-coder:3b":     ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3, size_class="small"),
+    # 1.5B — too small for reliable tool calls; use text_only to prevent JSON hallucination
+    "qwen2.5-coder:1.5b":  ModelCapability(tool_calls=False, format="text_only",     context_window=8192,   temperature=0.4, size_class="small", notes="1.5B — no tools; simple Q&A only"),
+    # 0.5B — nano class; only suitable for routing/classification, never complex tasks
+    "qwen2.5-coder:0.5b":  ModelCapability(tool_calls=False, format="router_only",   context_window=4096,   temperature=0.5, size_class="nano",  notes="0.5B nano — routing/intent only"),
+    "qwen2.5-coder":        ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.2, size_class="medium"),
+    "qwen2.5:72b":          ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.2, notes="Strongest Qwen general model"),
+    "qwen2.5:32b":          ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.2),
+    "qwen2.5:14b":          ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.2),
+    "qwen2.5:7b":           ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "qwen2.5":              ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3),
+    "qwen3":                ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, thinking=True),
+    "qwq":                  ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, thinking=True, notes="Math/reasoning focused"),
+    # ── DeepSeek family ────────────────────────────────────────────────────
+    "deepseek-r1:671b":     ModelCapability(tool_calls=False, format="xml_tags",      context_window=131072, temperature=0.3, thinking=True, notes="State-of-the-art reasoning"),
+    "deepseek-r1:70b":      ModelCapability(tool_calls=False, format="xml_tags",      context_window=131072, temperature=0.3, thinking=True),
+    "deepseek-r1:32b":      ModelCapability(tool_calls=False, format="xml_tags",      context_window=32768,  temperature=0.3, thinking=True),
+    "deepseek-r1:14b":      ModelCapability(tool_calls=False, format="xml_tags",      context_window=32768,  temperature=0.3, thinking=True),
+    "deepseek-r1:8b":       ModelCapability(tool_calls=False, format="xml_tags",      context_window=32768,  temperature=0.3, thinking=True),
+    "deepseek-r1:7b":       ModelCapability(tool_calls=False, format="xml_tags",      context_window=32768,  temperature=0.3, thinking=True),
+    "deepseek-r1":          ModelCapability(tool_calls=False, format="xml_tags",      context_window=32768,  temperature=0.3, thinking=True),
+    "deepseek-v3.1":        ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, notes="DeepSeek V3.1 671B"),
+    "deepseek-v3":          ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "deepseek-v2.5":        ModelCapability(tool_calls=True,  format="ollama_native", context_window=65536,  temperature=0.3),
+    "deepseek-coder-v2":    ModelCapability(tool_calls=True,  format="ollama_native", context_window=65536,  temperature=0.2),
+    # ── LLaMA family ───────────────────────────────────────────────────────
+    "llama3.3:70b":         ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, notes="Meta flagship 2024"),
+    "llama3.2:90b":         ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True,  notes="Multimodal, image+text"),
+    "llama3.2:11b":         ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True,  notes="Multimodal, image+text"),
+    "llama3.2:3b":          ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "llama3.2":             ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "llama3.1:405b":        ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "llama3.1:70b":         ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "llama3.1:8b":          ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "llama3.1":             ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "llama3":               ModelCapability(tool_calls=False, format="text_only",     context_window=8192,   temperature=0.3),
+    # ── Mistral family ─────────────────────────────────────────────────────
+    "mistral-nemo":         ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "mistral-large":        ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3),
+    "mistral-small":        ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3),
+    "mistral:7b":           ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3),
+    "mistral":              ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3),
+    "mixtral":              ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3),
+    # ── Phi family ─────────────────────────────────────────────────────────
+    "phi4:14b":             ModelCapability(tool_calls=True,  format="ollama_native", context_window=16384,  temperature=0.3, notes="Microsoft Phi4, compact+capable"),
+    "phi4":                 ModelCapability(tool_calls=True,  format="ollama_native", context_window=16384,  temperature=0.3),
+    "phi3.5":               ModelCapability(tool_calls=True,  format="ollama_native", context_window=16384,  temperature=0.3),
+    "phi3":                 ModelCapability(tool_calls=False, format="text_only",     context_window=8192,   temperature=0.3),
+    # ── Google Gemma ───────────────────────────────────────────────────────
+    "gemma3:27b":           ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True),
+    "gemma3:12b":           ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True),
+    "gemma3:4b":            ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True),
+    "gemma3":               ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True),
+    "gemma2":               ModelCapability(tool_calls=False, format="text_only",     context_window=8192,   temperature=0.3),
+    # ── Vision / multimodal models ─────────────────────────────────────────────
+    "llava:34b":            ModelCapability(tool_calls=False, format="text_only",     context_window=4096,   temperature=0.3, vision=True,  notes="LLaVA 34B vision-language"),
+    "llava:13b":            ModelCapability(tool_calls=False, format="text_only",     context_window=4096,   temperature=0.3, vision=True),
+    "llava:7b":             ModelCapability(tool_calls=False, format="text_only",     context_window=4096,   temperature=0.3, vision=True),
+    "llava":                ModelCapability(tool_calls=False, format="text_only",     context_window=4096,   temperature=0.3, vision=True),
+    "bakllava":             ModelCapability(tool_calls=False, format="text_only",     context_window=4096,   temperature=0.3, vision=True),
+    "moondream":            ModelCapability(tool_calls=False, format="text_only",     context_window=2048,   temperature=0.3, vision=True,  size_class="small", notes="Tiny vision model"),
+    "minicpm-v":            ModelCapability(tool_calls=False, format="text_only",     context_window=8192,   temperature=0.3, vision=True,  size_class="small"),
+    "qwen2-vl:72b":         ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True,  notes="Qwen2-VL 72B multimodal"),
+    "qwen2-vl:7b":          ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3, vision=True),
+    "qwen2-vl":             ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3, vision=True),
+    "qwen2.5vl:72b":        ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True,  notes="Qwen2.5-VL 72B"),
+    "qwen2.5vl:7b":         ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3, vision=True),
+    "qwen2.5vl":            ModelCapability(tool_calls=True,  format="ollama_native", context_window=32768,  temperature=0.3, vision=True),
+    # ── Finance-specific ───────────────────────────────────────────────────
+    "finma":                ModelCapability(tool_calls=False, format="text_only",     context_window=4096,   temperature=0.3, finance_tuned=True),
+    "fingpt":               ModelCapability(tool_calls=False, format="text_only",     context_window=4096,   temperature=0.3, finance_tuned=True),
+    "bloomberggpt":         ModelCapability(tool_calls=False, format="text_only",     context_window=2048,   temperature=0.2, finance_tuned=True),
+    # ── Aria own models ────────────────────────────────────────────────────
+    # aria-sonata-3b: primary local production model — 3B, good for finance Q&A + tool calls
+    "aria-sonata-3b":            ModelCapability(tool_calls=False, format="xml_tags", context_window=16384, temperature=0.3, size_class="small", finance_tuned=True, notes="3B local production model"),
+    # aria-sonata 1.x/0.5B series — GGUF Ollama models; xml_tags for text-based tool parsing
+    "aria-sonata:4.5-thinking":  ModelCapability(tool_calls=False, format="xml_tags", context_window=8192,  temperature=0.3, size_class="small", thinking=True,  finance_tuned=True),
+    "aria-sonata:4.5-verbose":   ModelCapability(tool_calls=False, format="xml_tags", context_window=8192,  temperature=0.3, size_class="small",                finance_tuned=True),
+    "aria-sonata:4.6-thinking":  ModelCapability(tool_calls=False, format="xml_tags", context_window=8192,  temperature=0.3, size_class="small", thinking=True,  finance_tuned=True),
+    "aria-sonata":               ModelCapability(tool_calls=False, format="xml_tags", context_window=8192,  temperature=0.3, size_class="small",                finance_tuned=True),
+    # aria-prelude: nano router model — ONLY for intent classification and routing
+    "aria-prelude":              ModelCapability(tool_calls=False, format="router_only", context_window=4096, temperature=0.2, size_class="nano", finance_tuned=True, notes="Nano router — intent classification only"),
+    # ── Anthropic Claude (cloud API via providers/llm/anthropic.py) ───────
+    # format="anthropic_native" → tool calling via Anthropic SDK, not Ollama
+    # All Claude 3+ models share 200K context and native vision support.
+    "claude-opus-4-8":              ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True, thinking=True,  notes="Claude Opus 4.8 — most capable"),
+    "claude-opus-4":                ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True, thinking=True),
+    "claude-sonnet-4-6":            ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True),
+    "claude-sonnet-4":              ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True),
+    "claude-haiku-4-5":             ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="medium", vision=True,               notes="Claude Haiku 4.5 — fast/cheap"),
+    "claude-haiku-4":               ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="medium", vision=True),
+    # Claude 3.x legacy — still widely used
+    "claude-3-7-sonnet":            ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True, thinking=True),
+    "claude-3-5-sonnet":            ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True),
+    "claude-3-5-haiku":             ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="medium", vision=True),
+    "claude-3-opus":                ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True, thinking=True),
+    "claude-3-sonnet":              ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True),
+    "claude-3-haiku":               ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="medium", vision=True),
+    # Generic prefix catch-all for future Claude versions (longest-prefix matching ensures
+    # specific entries above still win over this fallback)
+    "claude":                       ModelCapability(tool_calls=True, format="anthropic_native", context_window=200000, temperature=0.3, size_class="large",  vision=True),
+    # ── Arthera cloud-routed models (large, run via cloud API) ────────────
+    "gpt-oss:120b":             ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True, notes="GPT-OSS 120B cloud"),
+    "gpt-oss":                  ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, vision=True, notes="GPT-OSS cloud"),
+    "deepseek-v3.1:671b-cloud": ModelCapability(tool_calls=True,  format="ollama_native", context_window=131072, temperature=0.3, notes="DeepSeek V3.1 671B cloud"),
+}
+
+# Default fallback when model is unknown
+_DEFAULT_CAPABILITY = ModelCapability(
+    tool_calls=False, format="text_only", context_window=4096, temperature=0.5,
+    notes="Unknown model — conservative settings applied",
+)
+
+
+def get_model_capability(model_name: str) -> ModelCapability:
+    """
+    Return capability for *model_name* using longest-prefix matching.
+
+    Examples::
+
+        get_model_capability("qwen2.5-coder:7b-instruct-q4_K_M")
+        # → same as "qwen2.5-coder:7b" entry
+    """
+    name = (model_name or "").strip().lower()
+    # Strip GGUF quantisation suffixes like :q4_k_m, :f16, etc.
+    clean = re.sub(r":[qfQ][0-9].*$", "", name)
+    # Also strip common instruct/chat/gguf tags appended after the size
+    clean = re.sub(r"-(instruct|chat|gguf|base|it)$", "", clean)
+
+    best_prefix = ""
+    best_cap = _DEFAULT_CAPABILITY
+    for prefix, cap in _CAPABILITY_TABLE.items():
+        if clean.startswith(prefix.lower()) and len(prefix) > len(best_prefix):
+            best_prefix = prefix
+            best_cap = cap
+
+    return best_cap
+
+
+# ---------------------------------------------------------------------------
+# Tool schema injection helpers
+# ---------------------------------------------------------------------------
+
+def build_ollama_tool_payload(
+    tools_schema: List[Dict],
+    model_name: str,
+) -> Optional[List[Dict]]:
+    """
+    Return the `tools` field for an Ollama /api/chat request, or None when the
+    model does not support native tool calling.
+
+    When format == "ollama_native" the schema is passed as-is.
+    When format == "xml_tags" we skip the field and rely on prompt injection.
+    """
+    cap = get_model_capability(model_name)
+    if not cap.tool_calls or cap.format != "ollama_native":
+        return None
+    return tools_schema
+
+
+def build_tool_system_prompt(
+    tools_schema: List[Dict],
+    model_name: str,
+) -> str:
+    """
+    For models that do NOT support native tool calls (xml_tags / text_only),
+    return a system-prompt block that instructs the model to emit
+    ``<tool_call>{"name":…,"arguments":{…}}</tool_call>`` tags.
+    """
+    cap = get_model_capability(model_name)
+    if cap.tool_calls and cap.format == "ollama_native":
+        return ""  # handled by native API
+
+    tool_list = []
+    for t in tools_schema:
+        fn = t.get("function", t)
+        params = fn.get("parameters", {}).get("properties", {})
+        required = fn.get("parameters", {}).get("required", [])
+        param_str = ", ".join(
+            f"{k}: {v.get('type','any')}{'*' if k in required else ''}"
+            for k, v in params.items()
+        )
+        tool_list.append(f"  - {fn['name']}({param_str}): {fn.get('description','')}")
+
+    tools_block = "\n".join(tool_list)
+    return (
+        "\n\n## Available Tools\n\n"
+        "When you need to call a tool, output EXACTLY this format (nothing else on the line):\n\n"
+        '<tool_call>{"name": "tool_name", "arguments": {"param": "value"}}</tool_call>\n\n'
+        "Tools available:\n"
+        f"{tools_block}\n\n"
+        "Rules:\n"
+        "1. Call ONE tool at a time. Wait for the result before calling the next.\n"
+        "2. After receiving a tool result, continue your analysis or call another tool.\n"
+        "3. When done with all tools, write your final answer in plain text.\n"
+        "4. Never make up tool results — always call the tool.\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tool call parsers
+# ---------------------------------------------------------------------------
+
+def parse_tool_calls_from_response(
+    text: str,
+    native_calls: Optional[List[Dict]] = None,
+    model_name: str = "",
+) -> List[Dict[str, Any]]:
+    """
+    Unified parser.  Returns list of {"tool": str, "params": dict}.
+
+    Priority:
+      1. native_calls (Ollama tool_calls list) — most reliable
+      2. XML tags  <tool_call>…</tool_call>
+      3. JSON code fences  ```json … ```
+      4. Raw JSON object containing "name"/"arguments" keys
+    """
+    # 1. Native Ollama tool calls
+    if native_calls:
+        result = []
+        for tc in native_calls:
+            fn = tc.get("function", tc)
+            name = fn.get("name", "")
+            args = fn.get("arguments", {})
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except json.JSONDecodeError:
+                    args = {}
+            if name:
+                result.append({"tool": name, "params": args})
+        if result:
+            return result
+
+    if not text:
+        return []
+
+    results: List[Dict[str, Any]] = []
+
+    # 2. XML tag format: <tool_call>…</tool_call>
+    xml_pattern = re.compile(
+        r"<tool_call>\s*(.*?)\s*</tool_call>", re.DOTALL | re.IGNORECASE
+    )
+    for m in xml_pattern.finditer(text):
+        tc = _try_parse_json(m.group(1))
+        if tc:
+            results.append(_normalise_call(tc))
+
+    if results:
+        return results
+
+    # 3. JSON fence: ```json … ``` or ``` … ```
+    fence_pattern = re.compile(
+        r"```(?:json)?\s*(\{.*?\})\s*```", re.DOTALL | re.IGNORECASE
+    )
+    for m in fence_pattern.finditer(text):
+        tc = _try_parse_json(m.group(1))
+        if tc and ("name" in tc or "tool" in tc):
+            results.append(_normalise_call(tc))
+
+    if results:
+        return results
+
+    # 4. Bare JSON object anywhere in text
+    json_pattern = re.compile(r"\{[^{}]*\"(?:name|tool)\"[^{}]*\}", re.DOTALL)
+    for m in json_pattern.finditer(text):
+        tc = _try_parse_json(m.group(0))
+        if tc and ("name" in tc or "tool" in tc):
+            results.append(_normalise_call(tc))
+
+    return results
+
+
+def _try_parse_json(s: str) -> Optional[Dict]:
+    try:
+        return json.loads(s.strip())
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+
+def _normalise_call(tc: Dict) -> Dict[str, Any]:
+    """Normalise various key naming conventions → {"tool": …, "params": …}."""
+    name = tc.get("name") or tc.get("tool") or tc.get("function", {}).get("name", "")
+    args = (
+        tc.get("arguments")
+        or tc.get("params")
+        or tc.get("parameters")
+        or tc.get("function", {}).get("arguments", {})
+        or {}
+    )
+    if isinstance(args, str):
+        args = _try_parse_json(args) or {}
+    return {"tool": name, "params": args}
+
+
+# ---------------------------------------------------------------------------
+# Recommended local models for finance work
+# ---------------------------------------------------------------------------
+
+RECOMMENDED_FINANCE_MODELS: List[Dict[str, str]] = [
+    {
+        "model":       "qwen2.5-coder:7b",
+        "reason":      "Best balance of tool calling + code generation for finance scripts",
+        "install":     "ollama pull qwen2.5-coder:7b",
+        "vram_gb":     "5",
+    },
+    {
+        "model":       "qwen2.5:14b",
+        "reason":      "Strong quantitative reasoning, multi-turn strategy analysis",
+        "install":     "ollama pull qwen2.5:14b",
+        "vram_gb":     "10",
+    },
+    {
+        "model":       "deepseek-r1:14b",
+        "reason":      "Deep reasoning for complex factor models (slow but thorough)",
+        "install":     "ollama pull deepseek-r1:14b",
+        "vram_gb":     "10",
+    },
+    {
+        "model":       "llama3.2:3b",
+        "reason":      "Ultra-fast for quick quotes and simple questions",
+        "install":     "ollama pull llama3.2:3b",
+        "vram_gb":     "2",
+    },
+    {
+        "model":       "phi4:14b",
+        "reason":      "Math-strong, good for Greeks / derivative pricing",
+        "install":     "ollama pull phi4",
+        "vram_gb":     "9",
+    },
+]