equity-intel-mcp 0.1.0__tar.gz

equity_intel_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Amigo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

equity_intel_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: equity-intel-mcp
+Version: 0.1.0
+Summary: Institutional-grade equity analysis (insider, superinvestor, valuation) over MCP.
+Author-email: Cristian Amigo <cstamigo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cstamigo-droid/equity-intel-mcp
+Project-URL: Repository, https://github.com/cstamigo-droid/equity-intel-mcp
+Project-URL: Bug Tracker, https://github.com/cstamigo-droid/equity-intel-mcp/issues
+Keywords: mcp,model-context-protocol,equity,stocks,sec,edgar,insider-trading,valuation,llm,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: yfinance>=0.2.40
+Requires-Dist: requests>=2.31
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: edgartools>=4.0
+Requires-Dist: pandas>=2.0
+Dynamic: license-file
+
+# equity-intel-mcp
+
+[![equity-intel-mcp MCP server](https://glama.ai/mcp/servers/cstamigo-droid/equity-intel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/cstamigo-droid/equity-intel-mcp)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org) [![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-7C3AED.svg)](https://modelcontextprotocol.io)
+
+![equity-intel-mcp - composite verdict demo](docs/demo.png)
+
+
+**Institutional-grade equity analysis for any LLM, over the Model Context Protocol.**
+
+Most "stock" integrations just echo a price. This one gives an AI agent the
+signals professionals actually look at — **insider buying from SEC filings**,
+**what renowned value investors are holding**, analyst consensus, options-implied
+moves, and valuation — and blends them into a single, confidence-weighted verdict.
+
+It runs entirely on **free / public data** (Yahoo Finance, SEC EDGAR, Dataroma),
+fails gracefully when a source is missing, and never fabricates a signal it
+doesn't have.
+
+```
+# Equity Intelligence — MSFT
+
+## Verdict: Neutral → HOLD
+[........|#.......] +11/100  · confidence 69%  · 5 source(s)
+
+| Source        | Signal       | Score  | Conf | Weight |
+|---------------|--------------|-------:|-----:|-------:|
+| insider       | Bearish      |   -77  |  70% |   0.25 |
+| superinvestor | Lean bullish |   +33  | 100% |   0.30 |
+| analysts      | Bullish      |   +64  |  75% |   0.15 |
+| valuation     | Bullish      |   +91  |  60% |   0.09 |
+| options       | Lean bullish |   +19  |  40% |   0.04 |
+
+- insider: Insiders net selling $13.5M over 180d (62 filings).
+- superinvestor: 38 tracked superinvestors hold MSFT; 19 buys / 18 sells.
+- analysts: 66 analysts: 23 strong buy / 38 buy / 5 hold.
+- valuation: Fair value ~$569 vs $391 (+46% upside); health 84/100.
+- options: 1-month implied move +/-7.6%; put/call OI 0.53.
+```
+
+---
+
+## Tools
+
+| Tool | What it does | Source | Status |
+|------|--------------|--------|:------:|
+| `equity_analyze_ticker` | **Hero tool.** Runs every source in parallel and returns one scored verdict (BUY → AVOID) with a per-source breakdown. | composite | ✅ |
+| `equity_insider_activity` | Net insider buying vs. selling from SEC **Form 4** filings (180-day window), weighted by USD value. | SEC EDGAR | ✅ |
+| `equity_superinvestors` | Which of ~80 tracked value investors hold the stock, plus recent net buying/selling. | Dataroma | ✅ |
+| `equity_get_quote` | Live price snapshot + position in the 52-week range. | Yahoo Finance | ✅ |
+| `equity_analyst_consensus` | Wall Street buy/hold/sell consensus — scored from distribution of strong-buy to strong-sell ratings. | Finnhub | ✅ |
+| `equity_options_signal` | 1-month implied move (straddle/spot) + put/call OI skew. Primary use: risk-sizing. | Yahoo Finance | ✅ |
+| `equity_valuation` | Fair-value estimate (forward EPS × sector P/E) + financial-health score (debt, liquidity, margins). | Yahoo Finance | ✅ |
+
+Every tool returns **Markdown** (human-readable, default) or **JSON**
+(`response_format="json"`) for programmatic use.
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/cstamigo-droid/equity-intel-mcp equity-intel-mcp
+cd equity-intel-mcp
+python -m venv .venv && .venv\Scripts\activate     # Windows
+pip install -r requirements.txt
+
+copy .env.example .env        # then edit .env (set EDGAR_IDENTITY)
+python -m equity_intel_mcp    # starts the MCP server over stdio
+```
+
+**Smoke test** (hits the live sources and prints each signal):
+
+```bash
+python tests/test_smoke.py AAPL
+```
+
+### Configure (`.env`)
+
+```ini
+# Required by SEC fair-access policy — any "Name email@example.com"
+EDGAR_IDENTITY=Your Name you@example.com
+# Required by equity_analyst_consensus (free key at finnhub.io)
+FINNHUB_API_KEY=your-key-here
+```
+
+---
+
+## Use it in Claude Desktop
+
+Add this to `claude_desktop_config.json`
+(`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS),
+then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "equity-intel": {
+      "command": "python",
+      "args": ["-m", "equity_intel_mcp"],
+      "cwd": "C:/path/to/equity-intel-mcp",
+      "env": { "EDGAR_IDENTITY": "Your Name you@example.com" }
+    }
+  }
+}
+```
+
+Then just ask Claude: *"Give me a full read on NVDA"* or *"Are insiders buying PLTR?"*
+
+---
+
+## Why it's built this way
+
+- **Uniform signal contract.** Every source returns the same shape
+  (`score -100..+100`, `confidence 0..1`, `data`, `summary`). That's what lets an
+  LLM reason *across* heterogeneous evidence instead of parsing five formats.
+- **Graceful degradation.** A stock with no Form 4 activity returns *"no signal"*,
+  not a fake bearish score. Missing data lowers confidence; it never invents a call.
+- **Confidence-weighted blending.** The composite weights each source by its
+  importance × its own confidence, so thin signals don't outvote strong ones.
+- **Resilient + cached.** Short per-source TTL caches avoid hammering rate-limited
+  endpoints when an agent calls several tools on the same ticker in one turn.
+
+See [ROADMAP.md](ROADMAP.md) for what's next.
+
+---
+
+## Disclaimer
+
+For research and educational use only. **Not investment advice.** Data comes from
+third-party public sources and may be delayed or incomplete. Do your own due
+diligence.
+
+## License
+
+MIT

equity_intel_mcp-0.1.0/README.md

@@ -0,0 +1,137 @@
+# equity-intel-mcp
+
+[![equity-intel-mcp MCP server](https://glama.ai/mcp/servers/cstamigo-droid/equity-intel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/cstamigo-droid/equity-intel-mcp)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org) [![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-7C3AED.svg)](https://modelcontextprotocol.io)
+
+![equity-intel-mcp - composite verdict demo](docs/demo.png)
+
+
+**Institutional-grade equity analysis for any LLM, over the Model Context Protocol.**
+
+Most "stock" integrations just echo a price. This one gives an AI agent the
+signals professionals actually look at — **insider buying from SEC filings**,
+**what renowned value investors are holding**, analyst consensus, options-implied
+moves, and valuation — and blends them into a single, confidence-weighted verdict.
+
+It runs entirely on **free / public data** (Yahoo Finance, SEC EDGAR, Dataroma),
+fails gracefully when a source is missing, and never fabricates a signal it
+doesn't have.
+
+```
+# Equity Intelligence — MSFT
+
+## Verdict: Neutral → HOLD
+[........|#.......] +11/100  · confidence 69%  · 5 source(s)
+
+| Source        | Signal       | Score  | Conf | Weight |
+|---------------|--------------|-------:|-----:|-------:|
+| insider       | Bearish      |   -77  |  70% |   0.25 |
+| superinvestor | Lean bullish |   +33  | 100% |   0.30 |
+| analysts      | Bullish      |   +64  |  75% |   0.15 |
+| valuation     | Bullish      |   +91  |  60% |   0.09 |
+| options       | Lean bullish |   +19  |  40% |   0.04 |
+
+- insider: Insiders net selling $13.5M over 180d (62 filings).
+- superinvestor: 38 tracked superinvestors hold MSFT; 19 buys / 18 sells.
+- analysts: 66 analysts: 23 strong buy / 38 buy / 5 hold.
+- valuation: Fair value ~$569 vs $391 (+46% upside); health 84/100.
+- options: 1-month implied move +/-7.6%; put/call OI 0.53.
+```
+
+---
+
+## Tools
+
+| Tool | What it does | Source | Status |
+|------|--------------|--------|:------:|
+| `equity_analyze_ticker` | **Hero tool.** Runs every source in parallel and returns one scored verdict (BUY → AVOID) with a per-source breakdown. | composite | ✅ |
+| `equity_insider_activity` | Net insider buying vs. selling from SEC **Form 4** filings (180-day window), weighted by USD value. | SEC EDGAR | ✅ |
+| `equity_superinvestors` | Which of ~80 tracked value investors hold the stock, plus recent net buying/selling. | Dataroma | ✅ |
+| `equity_get_quote` | Live price snapshot + position in the 52-week range. | Yahoo Finance | ✅ |
+| `equity_analyst_consensus` | Wall Street buy/hold/sell consensus — scored from distribution of strong-buy to strong-sell ratings. | Finnhub | ✅ |
+| `equity_options_signal` | 1-month implied move (straddle/spot) + put/call OI skew. Primary use: risk-sizing. | Yahoo Finance | ✅ |
+| `equity_valuation` | Fair-value estimate (forward EPS × sector P/E) + financial-health score (debt, liquidity, margins). | Yahoo Finance | ✅ |
+
+Every tool returns **Markdown** (human-readable, default) or **JSON**
+(`response_format="json"`) for programmatic use.
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/cstamigo-droid/equity-intel-mcp equity-intel-mcp
+cd equity-intel-mcp
+python -m venv .venv && .venv\Scripts\activate     # Windows
+pip install -r requirements.txt
+
+copy .env.example .env        # then edit .env (set EDGAR_IDENTITY)
+python -m equity_intel_mcp    # starts the MCP server over stdio
+```
+
+**Smoke test** (hits the live sources and prints each signal):
+
+```bash
+python tests/test_smoke.py AAPL
+```
+
+### Configure (`.env`)
+
+```ini
+# Required by SEC fair-access policy — any "Name email@example.com"
+EDGAR_IDENTITY=Your Name you@example.com
+# Required by equity_analyst_consensus (free key at finnhub.io)
+FINNHUB_API_KEY=your-key-here
+```
+
+---
+
+## Use it in Claude Desktop
+
+Add this to `claude_desktop_config.json`
+(`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS),
+then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "equity-intel": {
+      "command": "python",
+      "args": ["-m", "equity_intel_mcp"],
+      "cwd": "C:/path/to/equity-intel-mcp",
+      "env": { "EDGAR_IDENTITY": "Your Name you@example.com" }
+    }
+  }
+}
+```
+
+Then just ask Claude: *"Give me a full read on NVDA"* or *"Are insiders buying PLTR?"*
+
+---
+
+## Why it's built this way
+
+- **Uniform signal contract.** Every source returns the same shape
+  (`score -100..+100`, `confidence 0..1`, `data`, `summary`). That's what lets an
+  LLM reason *across* heterogeneous evidence instead of parsing five formats.
+- **Graceful degradation.** A stock with no Form 4 activity returns *"no signal"*,
+  not a fake bearish score. Missing data lowers confidence; it never invents a call.
+- **Confidence-weighted blending.** The composite weights each source by its
+  importance × its own confidence, so thin signals don't outvote strong ones.
+- **Resilient + cached.** Short per-source TTL caches avoid hammering rate-limited
+  endpoints when an agent calls several tools on the same ticker in one turn.
+
+See [ROADMAP.md](ROADMAP.md) for what's next.
+
+---
+
+## Disclaimer
+
+For research and educational use only. **Not investment advice.** Data comes from
+third-party public sources and may be delayed or incomplete. Do your own due
+diligence.
+
+## License
+
+MIT

equity_intel_mcp-0.1.0/equity_intel_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""equity_intel_mcp — institutional-grade equity analysis over the Model Context Protocol.
+
+Gives any MCP client (Claude Desktop, Claude Code, agents) clean tools for:
+insider activity (SEC Form 4), superinvestor holdings (Dataroma), Wall Street
+consensus, options-implied moves, valuation & financial health, and a composite
+scored verdict — all from free/public data sources with graceful degradation.
+"""
+
+__version__ = "0.1.0"

equity_intel_mcp-0.1.0/equity_intel_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m equity_intel_mcp` to launch the server."""
+from .server import main
+
+if __name__ == "__main__":
+    main()

equity_intel_mcp-0.1.0/equity_intel_mcp/analyze.py

@@ -0,0 +1,90 @@
+"""Composite verdict — blends every directional source into one scored call.
+
+The blend is a confidence-weighted average: each source's directional score is
+weighted by (source importance x its own confidence), so a high-conviction
+insider signal moves the needle more than a thin, low-confidence one. Sources
+that returned no data are simply absent from the average — missing data lowers
+overall confidence but never drags the score toward a false bearish/bullish read.
+"""
+from __future__ import annotations
+
+from statistics import mean
+from typing import Any
+
+from .signal import Signal, clamp
+
+# Relative importance of each directional source in the final verdict.
+# Sources not yet implemented are listed so `coverage` reflects the full design.
+SOURCE_WEIGHTS: dict[str, float] = {
+    "insider": 0.35,
+    "superinvestor": 0.30,
+    "analysts": 0.20,
+    "valuation": 0.15,
+    "options": 0.10,
+}
+
+
+def _verdict(score: float) -> tuple[str, str]:
+    """Map a composite score to (verdict label, recommended action)."""
+    if score >= 40:
+        return "Bullish", "BUY"
+    if score >= 15:
+        return "Lean bullish", "ACCUMULATE"
+    if score > -15:
+        return "Neutral", "HOLD"
+    if score > -40:
+        return "Lean bearish", "TRIM"
+    return "Bearish", "AVOID"
+
+
+def composite(signals: list[Signal]) -> dict[str, Any]:
+    """Blend directional signals into a single verdict.
+
+    Returns a dict: score (-100..100), confidence (0..1), verdict, action,
+    n_sources, coverage, and a per-source breakdown list.
+    """
+    directional = [s for s in signals if s.directional and s.ok]
+    if not directional:
+        return {
+            "score": 0.0,
+            "confidence": 0.0,
+            "verdict": "No data",
+            "action": "INSUFFICIENT DATA",
+            "n_sources": 0,
+            "coverage": 0.0,
+            "breakdown": [],
+        }
+
+    num = den = 0.0
+    breakdown = []
+    for s in directional:
+        weight = SOURCE_WEIGHTS.get(s.source, 0.1) * s.confidence
+        num += s.score * weight
+        den += weight
+        breakdown.append(
+            {
+                "source": s.source,
+                "score": s.score,
+                "confidence": s.confidence,
+                "effective_weight": round(weight, 3),
+                "summary": s.summary,
+            }
+        )
+
+    score = clamp(num / den if den else 0.0, -100.0, 100.0)
+    verdict, action = _verdict(score)
+
+    # Confidence reflects both per-source quality and how many of the designed
+    # sources actually reported (coverage).
+    coverage = len(directional) / len(SOURCE_WEIGHTS)
+    confidence = mean(s.confidence for s in directional) * (0.5 + 0.5 * coverage)
+
+    return {
+        "score": round(score, 1),
+        "confidence": round(confidence, 2),
+        "verdict": verdict,
+        "action": action,
+        "n_sources": len(directional),
+        "coverage": round(coverage, 2),
+        "breakdown": breakdown,
+    }

equity_intel_mcp-0.1.0/equity_intel_mcp/cache.py

@@ -0,0 +1,41 @@
+"""Tiny thread-safe TTL cache.
+
+External data sources (Yahoo, SEC, Dataroma) are slow and rate-limited. A short
+in-process cache means an agent that calls several tools on the same ticker in
+one turn — or the composite `analyze_ticker` that fans out to every source —
+doesn't refetch the same data seconds apart. TTLs are per-source (a quote ages
+in 60s; a 13F holding list can live for an hour).
+"""
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable
+
+_lock = threading.Lock()
+_store: dict[str, tuple[float, Any]] = {}
+
+
+def get_or_fetch(key: str, ttl_s: float, fetch: Callable[[], Any]) -> Any:
+    """Return a cached value if fresh, otherwise call `fetch()` and store it.
+
+    `fetch` runs OUTSIDE the lock so a slow network call never blocks other
+    cache readers. A rare duplicate fetch under concurrency is acceptable.
+    """
+    now = time.monotonic()
+    with _lock:
+        hit = _store.get(key)
+        if hit is not None and (now - hit[0]) < ttl_s:
+            return hit[1]
+
+    value = fetch()
+
+    with _lock:
+        _store[key] = (time.monotonic(), value)
+    return value
+
+
+def clear() -> None:
+    """Drop all cached entries (used by tests)."""
+    with _lock:
+        _store.clear()

equity_intel_mcp-0.1.0/equity_intel_mcp/formatting.py

@@ -0,0 +1,124 @@
+"""Render Signals as Markdown (human) or JSON (machine) for MCP tool output."""
+from __future__ import annotations
+
+import json
+from enum import Enum
+
+from .signal import Signal, clamp, label
+
+
+class ResponseFormat(str, Enum):
+    """Output format for tool responses."""
+
+    MARKDOWN = "markdown"
+    JSON = "json"
+
+
+def _gauge(score: float) -> str:
+    """A compact ASCII gauge for a -100..+100 score.
+
+    Bearish fills left of center, bullish fills right, e.g.
+    -100 -> `[########|........]`, +50 -> `[........|####....]`.
+    """
+    n = 8  # half-width
+    s = clamp(score, -100, 100)
+    filled = int(round(abs(s) / 100 * n))
+    if s < 0:
+        left, right = "." * (n - filled) + "#" * filled, "." * n
+    elif s > 0:
+        left, right = "." * n, "#" * filled + "." * (n - filled)
+    else:
+        left = right = "." * n
+    return f"[{left}|{right}]"
+
+
+def render(signal: Signal, title: str, fmt: ResponseFormat) -> str:
+    """Format a single Signal for return to an MCP client."""
+    if fmt == ResponseFormat.JSON:
+        return json.dumps(signal.to_dict(), indent=2, default=str)
+
+    lines = [f"# {title}"]
+    if not signal.ok:
+        lines += ["", f"⚠️ No signal available — {signal.error}"]
+        return "\n".join(lines)
+
+    if signal.directional:
+        lines += [
+            "",
+            f"**Signal:** {label(signal.score)}  "
+            f"`{_gauge(signal.score)}` {signal.score:+.0f}/100  "
+            f"· confidence {signal.confidence:.0%}",
+        ]
+    if signal.summary:
+        lines += ["", signal.summary]
+
+    if signal.data:
+        lines += ["", "## Details"]
+        for k, v in signal.data.items():
+            if v is None or k == "url":
+                continue
+            lines.append(f"- **{k.replace('_', ' ')}:** {_fmt_value(v)}")
+        url = signal.data.get("url")
+        if url:
+            lines += ["", f"Source: {url}"]
+
+    return "\n".join(lines)
+
+
+def render_composite(ticker: str, result: dict, signals: list[Signal], fmt: ResponseFormat) -> str:
+    """Render the composite `analyze_ticker` verdict plus its source breakdown."""
+    if fmt == ResponseFormat.JSON:
+        return json.dumps(
+            {"ticker": ticker, "verdict": result, "signals": [s.to_dict() for s in signals]},
+            indent=2,
+            default=str,
+        )
+
+    lines = [
+        f"# Equity Intelligence — {ticker}",
+        "",
+        f"## Verdict: {result['verdict']} → **{result['action']}**",
+        f"`{_gauge(result['score'])}` {result['score']:+.0f}/100  "
+        f"· confidence {result['confidence']:.0%}  "
+        f"· {result['n_sources']} source(s), {result['coverage']:.0%} coverage",
+    ]
+
+    quote_sig = next((s for s in signals if s.source == "quote" and s.ok), None)
+    if quote_sig:
+        lines += ["", f"**Price context:** {quote_sig.summary}"]
+
+    if result["breakdown"]:
+        lines += [
+            "",
+            "## Signal breakdown",
+            "| Source | Signal | Score | Conf | Weight |",
+            "|---|---|---:|---:|---:|",
+        ]
+        for b in result["breakdown"]:
+            lines.append(
+                f"| {b['source']} | {label(b['score'])} | {b['score']:+.0f} "
+                f"| {b['confidence']:.0%} | {b['effective_weight']:.2f} |"
+            )
+        lines += ["", "## What each source says"]
+        for b in result["breakdown"]:
+            lines.append(f"- **{b['source']}:** {b['summary']}")
+
+    skipped = [s for s in signals if s.directional and not s.ok]
+    if skipped:
+        lines += ["", "## No signal (data unavailable)"]
+        for s in skipped:
+            lines.append(f"- **{s.source}:** {s.error}")
+
+    return "\n".join(lines)
+
+
+def _fmt_value(v: object) -> str:
+    if isinstance(v, bool):
+        return "yes" if v else "no"
+    if isinstance(v, float):
+        return f"{v:,.2f}"
+    if isinstance(v, int):
+        return f"{v:,}"
+    if isinstance(v, list):
+        return ", ".join(str(x) for x in v[:12]) + (" …" if len(v) > 12 else "")
+    return str(v)