naragate-mcp 0.3.0__tar.gz

naragate_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devid HW
+
+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.

naragate_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: naragate-mcp
+Version: 0.3.0
+Summary: MCP server exposing the Naragate reality-gap evidence engine to any MCP-capable agent (desktop, CLI, IDE).
+Author-email: Devid HW <devid.wahid@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/masdevid/naragate
+Project-URL: Repository, https://github.com/masdevid/naragate
+Project-URL: Issues, https://github.com/masdevid/naragate/issues
+Project-URL: Changelog, https://github.com/masdevid/naragate/releases
+Project-URL: Documentation, https://github.com/masdevid/naragate/blob/master/mcp/README.md
+Keywords: mcp,model-context-protocol,ai-agents,claude,cursor,opencode,codex,stock,indonesia,idx,sectors,fact-check
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+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 :: 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<2,>=1.2
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Dynamic: license-file
+
+# Naragate MCP Server
+
+One portable tool layer so the **same Naragate experience** works on the custom web UI *and* on any
+MCP-capable agent surface — Claude Code, Claude Desktop, Cursor, Windsurf, Zed, VS Code, opencode,
+Codex, or your own harness.
+
+```
+                 ┌─ custom web UI (Angular)
+Naragate backend ├─ MCP server  ──► any MCP harness (desktop / CLI / IDE)
+(FastAPI+cache)  └─ Pi agent harness
+```
+
+## The three layers (what a user actually needs)
+
+| Layer | Path | Required? | Role |
+|---|---|---|---|
+| **MCP server** | `mcp/` (this package) | **Yes** for non-web | The tools: analyze, history, trend, precheck, usage |
+| **Skills** | `skills/` | **Yes** | Domain instructions: how to parse, challenge and score a claim |
+| **Agents** | `agents/` | No | Optional orchestration for harnesses with subagents |
+
+Skills alone can't fetch data (they declare tools but don't ship them); agents+skills add
+orchestration but still have no data. **The MCP bundle is the data layer** — with it, skills run
+anywhere.
+
+## Credit safety (hard requirement)
+
+This server **never talks to Sectors directly**. Every tool is a thin client over the Naragate
+backend, so evidence gathering, the Evidence Graph cache and credit accounting live in exactly one
+place. A warm re-run costs **0 additional Sectors calls**, identical to the web UI. There is a test
+asserting the MCP package never references the Sectors API.
+
+## Install
+
+```bash
+uvx naragate-mcp           # run without installing (recommended)
+pip install naragate-mcp   # or install into your environment
+pipx install naragate-mcp
+```
+
+From a checkout: `pip install -e mcp`.
+
+Point it at your backend (default `http://127.0.0.1:5678`):
+
+```bash
+export NARAGATE_BACKEND_URL="http://127.0.0.1:5678"
+naragate-mcp
+```
+
+Transport is **stdio**.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `analyze_narrative(narrative)` | Verify a narrative end-to-end → Reality Gap score, verdict, evidence sections, policy signal, skeptic summary |
+| `analyze_template(template_id)` | Run one of the 12 curated dashboard templates by id |
+| `list_templates()` | The 12 curated narratives (same tiles as the web dashboard) |
+| `get_claim(claim_id)` | Full stored record (claim, evidence, skeptic, score, policy) |
+| `get_reality_gap(claim_id)` | Compact report for a stored claim |
+| `list_history(limit)` | Recent analyses, most recent first |
+| `get_trend_summary()` | Totals, average score, verdict distribution, per-ticker history |
+| `get_policy_precheck(sector)` | Policy→price pre-check, scoped to the claim's sector |
+| `get_usage()` | Sectors/LLM credit usage, cache hits, remaining budget |
+
+### Low-level tools — full `tools.yaml` parity
+
+Every primitive declared in `skills/*/tools.yaml` is also exposed, for harnesses that want to compose
+per-agent exactly like the Pi pipeline (check the cache, then fetch on a miss and merge back):
+
+| Tool | What it does |
+|---|---|
+| `sectors_company_report(ticker, sections)` | Sectors v2 company report (valuation/overview/financials) |
+| `sectors_subsector_report(sub_sector, sections)` | Sectors v2 subsector report |
+| `sectors_quarterly_financials(ticker, n_quarters)` | Sectors v2 quarterly financials |
+| `sectors_daily_transaction(ticker, start, end)` | Sectors v2 daily price/volume (Sectors caps a call at 90 days) |
+| `sectors_news(ticker, limit)` | Sectors v2 news headlines |
+| `sectors_corporate_actions(ticker)` | Sectors v2 corporate actions |
+| `sectors_filings(ticker, filing_type)` | Sectors v2 insider-trade filings |
+| `evidence_cache_get(ticker)` | Read the Evidence Graph (null on miss) |
+| `evidence_cache_merge(ticker, key, value, ttl?)` | Merge one section into the cache |
+| `llm_complete(prompt, system?, response_format?, role?)` | One-shot completion on Naragate's configured LLM |
+
+A test (`tests/test_parity.py`) asserts that **every** tool declared in any `skills/*/tools.yaml`
+exists on the server, so this can't drift.
+
+## Resources
+
+- `naragate://templates`
+- `naragate://usage`
+- `naragate://history`
+- `naragate://claim/{claim_id}`
+
+## Harness configuration
+
+### Claude Code
+
+```bash
+claude mcp add naragate -e NARAGATE_BACKEND_URL=http://127.0.0.1:5678 -- uvx naragate-mcp
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "naragate": {
+      "command": "uvx",
+      "args": ["naragate-mcp"],
+      "env": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678" }
+    }
+  }
+}
+```
+
+### opencode (`opencode.json`)
+
+```json
+{
+  "mcp": {
+    "naragate": {
+      "type": "local",
+      "command": ["uvx", "naragate-mcp"],
+      "enabled": true,
+      "environment": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678" }
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`) / Windsurf / Zed / VS Code
+
+```json
+{
+  "mcpServers": {
+    "naragate": {
+      "command": "uvx",
+      "args": ["naragate-mcp"],
+      "env": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678" }
+    }
+  }
+}
+```
+
+### Codex (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.naragate]
+command = "uvx"
+args = ["naragate-mcp"]
+env = { NARAGATE_BACKEND_URL = "http://127.0.0.1:5678" }
+```
+
+## Example prompts
+
+- *"Use naragate to verify: PE BBCA mahal di 25x."*
+- *"List the naragate templates and run the nickel policy one."*
+- *"Show my last 10 naragate analyses and the trend summary."*
+- *"What's my Sectors credit usage?"*
+
+## Tests
+
+```bash
+cd mcp
+python -m pytest -q
+```
+
+Covers the REST client (mock transport), the tool surface, compact-report shaping, and the
+credit-safety guarantee. No live backend or Sectors access required.
+
+## Publishing
+
+Releases publish automatically via [`.github/workflows/publish-mcp.yml`](https://github.com/masdevid/naragate/blob/master/.github/workflows/publish-mcp.yml)
+when a GitHub release is published (using the `PYPI_TOKEN` repository secret), or locally:
+
+```bash
+mcp/publish.sh              # PyPI
+mcp/publish.sh testpypi     # TestPyPI
+```
+
+`publish.sh` reads `PYPI_TOKEN` from the environment or the repo-root `.env`, builds with
+`python -m build`, validates with `twine check`, and uploads — the token is never echoed. Manual
+equivalent:
+
+```bash
+python -m build
+python -m twine check dist/*
+TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN" python -m twine upload dist/*
+```
+
+## Related
+
+- [Naragate README](https://github.com/masdevid/naragate#readme) — project overview and the "Use Naragate from any MCP agent" section
+- [Skills](https://github.com/masdevid/naragate/blob/master/skills/README.md) — the 13 skills whose `tools.yaml` this server satisfies
+- [Agents](https://github.com/masdevid/naragate/blob/master/agents/README.md) — optional subagent topology for harnesses that support it
+- [Parity test](https://github.com/masdevid/naragate/blob/master/mcp/tests/test_parity.py) — enforces that every `skills/*/tools.yaml` tool is exposed here

naragate_mcp-0.3.0/README.md

@@ -0,0 +1,195 @@
+# Naragate MCP Server
+
+One portable tool layer so the **same Naragate experience** works on the custom web UI *and* on any
+MCP-capable agent surface — Claude Code, Claude Desktop, Cursor, Windsurf, Zed, VS Code, opencode,
+Codex, or your own harness.
+
+```
+                 ┌─ custom web UI (Angular)
+Naragate backend ├─ MCP server  ──► any MCP harness (desktop / CLI / IDE)
+(FastAPI+cache)  └─ Pi agent harness
+```
+
+## The three layers (what a user actually needs)
+
+| Layer | Path | Required? | Role |
+|---|---|---|---|
+| **MCP server** | `mcp/` (this package) | **Yes** for non-web | The tools: analyze, history, trend, precheck, usage |
+| **Skills** | `skills/` | **Yes** | Domain instructions: how to parse, challenge and score a claim |
+| **Agents** | `agents/` | No | Optional orchestration for harnesses with subagents |
+
+Skills alone can't fetch data (they declare tools but don't ship them); agents+skills add
+orchestration but still have no data. **The MCP bundle is the data layer** — with it, skills run
+anywhere.
+
+## Credit safety (hard requirement)
+
+This server **never talks to Sectors directly**. Every tool is a thin client over the Naragate
+backend, so evidence gathering, the Evidence Graph cache and credit accounting live in exactly one
+place. A warm re-run costs **0 additional Sectors calls**, identical to the web UI. There is a test
+asserting the MCP package never references the Sectors API.
+
+## Install
+
+```bash
+uvx naragate-mcp           # run without installing (recommended)
+pip install naragate-mcp   # or install into your environment
+pipx install naragate-mcp
+```
+
+From a checkout: `pip install -e mcp`.
+
+Point it at your backend (default `http://127.0.0.1:5678`):
+
+```bash
+export NARAGATE_BACKEND_URL="http://127.0.0.1:5678"
+naragate-mcp
+```
+
+Transport is **stdio**.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `analyze_narrative(narrative)` | Verify a narrative end-to-end → Reality Gap score, verdict, evidence sections, policy signal, skeptic summary |
+| `analyze_template(template_id)` | Run one of the 12 curated dashboard templates by id |
+| `list_templates()` | The 12 curated narratives (same tiles as the web dashboard) |
+| `get_claim(claim_id)` | Full stored record (claim, evidence, skeptic, score, policy) |
+| `get_reality_gap(claim_id)` | Compact report for a stored claim |
+| `list_history(limit)` | Recent analyses, most recent first |
+| `get_trend_summary()` | Totals, average score, verdict distribution, per-ticker history |
+| `get_policy_precheck(sector)` | Policy→price pre-check, scoped to the claim's sector |
+| `get_usage()` | Sectors/LLM credit usage, cache hits, remaining budget |
+
+### Low-level tools — full `tools.yaml` parity
+
+Every primitive declared in `skills/*/tools.yaml` is also exposed, for harnesses that want to compose
+per-agent exactly like the Pi pipeline (check the cache, then fetch on a miss and merge back):
+
+| Tool | What it does |
+|---|---|
+| `sectors_company_report(ticker, sections)` | Sectors v2 company report (valuation/overview/financials) |
+| `sectors_subsector_report(sub_sector, sections)` | Sectors v2 subsector report |
+| `sectors_quarterly_financials(ticker, n_quarters)` | Sectors v2 quarterly financials |
+| `sectors_daily_transaction(ticker, start, end)` | Sectors v2 daily price/volume (Sectors caps a call at 90 days) |
+| `sectors_news(ticker, limit)` | Sectors v2 news headlines |
+| `sectors_corporate_actions(ticker)` | Sectors v2 corporate actions |
+| `sectors_filings(ticker, filing_type)` | Sectors v2 insider-trade filings |
+| `evidence_cache_get(ticker)` | Read the Evidence Graph (null on miss) |
+| `evidence_cache_merge(ticker, key, value, ttl?)` | Merge one section into the cache |
+| `llm_complete(prompt, system?, response_format?, role?)` | One-shot completion on Naragate's configured LLM |
+
+A test (`tests/test_parity.py`) asserts that **every** tool declared in any `skills/*/tools.yaml`
+exists on the server, so this can't drift.
+
+## Resources
+
+- `naragate://templates`
+- `naragate://usage`
+- `naragate://history`
+- `naragate://claim/{claim_id}`
+
+## Harness configuration
+
+### Claude Code
+
+```bash
+claude mcp add naragate -e NARAGATE_BACKEND_URL=http://127.0.0.1:5678 -- uvx naragate-mcp
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "naragate": {
+      "command": "uvx",
+      "args": ["naragate-mcp"],
+      "env": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678" }
+    }
+  }
+}
+```
+
+### opencode (`opencode.json`)
+
+```json
+{
+  "mcp": {
+    "naragate": {
+      "type": "local",
+      "command": ["uvx", "naragate-mcp"],
+      "enabled": true,
+      "environment": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678" }
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`) / Windsurf / Zed / VS Code
+
+```json
+{
+  "mcpServers": {
+    "naragate": {
+      "command": "uvx",
+      "args": ["naragate-mcp"],
+      "env": { "NARAGATE_BACKEND_URL": "http://127.0.0.1:5678" }
+    }
+  }
+}
+```
+
+### Codex (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.naragate]
+command = "uvx"
+args = ["naragate-mcp"]
+env = { NARAGATE_BACKEND_URL = "http://127.0.0.1:5678" }
+```
+
+## Example prompts
+
+- *"Use naragate to verify: PE BBCA mahal di 25x."*
+- *"List the naragate templates and run the nickel policy one."*
+- *"Show my last 10 naragate analyses and the trend summary."*
+- *"What's my Sectors credit usage?"*
+
+## Tests
+
+```bash
+cd mcp
+python -m pytest -q
+```
+
+Covers the REST client (mock transport), the tool surface, compact-report shaping, and the
+credit-safety guarantee. No live backend or Sectors access required.
+
+## Publishing
+
+Releases publish automatically via [`.github/workflows/publish-mcp.yml`](https://github.com/masdevid/naragate/blob/master/.github/workflows/publish-mcp.yml)
+when a GitHub release is published (using the `PYPI_TOKEN` repository secret), or locally:
+
+```bash
+mcp/publish.sh              # PyPI
+mcp/publish.sh testpypi     # TestPyPI
+```
+
+`publish.sh` reads `PYPI_TOKEN` from the environment or the repo-root `.env`, builds with
+`python -m build`, validates with `twine check`, and uploads — the token is never echoed. Manual
+equivalent:
+
+```bash
+python -m build
+python -m twine check dist/*
+TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN" python -m twine upload dist/*
+```
+
+## Related
+
+- [Naragate README](https://github.com/masdevid/naragate#readme) — project overview and the "Use Naragate from any MCP agent" section
+- [Skills](https://github.com/masdevid/naragate/blob/master/skills/README.md) — the 13 skills whose `tools.yaml` this server satisfies
+- [Agents](https://github.com/masdevid/naragate/blob/master/agents/README.md) — optional subagent topology for harnesses that support it
+- [Parity test](https://github.com/masdevid/naragate/blob/master/mcp/tests/test_parity.py) — enforces that every `skills/*/tools.yaml` tool is exposed here

naragate_mcp-0.3.0/naragate_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Naragate MCP server package."""
+
+from naragate_mcp.client import NaragateClient, NaragateError
+
+__all__ = ["NaragateClient", "NaragateError"]
+__version__ = "0.3.0"

naragate_mcp-0.3.0/naragate_mcp/client.py

@@ -0,0 +1,134 @@
+"""Thin REST client for the Naragate backend.
+
+Every non-web surface (MCP tools, scripts) goes through the backend so that
+evidence caching and credit accounting live in exactly one place. Configure the
+backend with `NARAGATE_BACKEND_URL` (default `http://127.0.0.1:5678`).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "http://127.0.0.1:5678"
+
+
+class NaragateError(RuntimeError):
+    """Raised when the Naragate backend is unreachable or returns an error."""
+
+    def __init__(self, message: str, status: int | None = None, detail: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.detail = detail
+
+
+class NaragateClient:
+    def __init__(self, base_url: str | None = None, timeout: float = 600.0, transport: httpx.BaseTransport | None = None):
+        self.base_url = (
+            base_url or os.environ.get("NARAGATE_BACKEND_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self._transport = transport
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        url = f"{self.base_url}{path}"
+        try:
+            with httpx.Client(timeout=self.timeout, transport=self._transport) as client:
+                resp = client.request(method, url, **kwargs)
+        except httpx.HTTPError as exc:  # network / timeout
+            raise NaragateError(
+                f"cannot reach Naragate backend at {self.base_url}: {exc}"
+            ) from exc
+
+        if resp.status_code >= 400:
+            detail: Any
+            try:
+                detail = resp.json().get("detail")
+            except Exception:  # noqa: BLE001 — non-JSON error body
+                detail = resp.text
+            raise NaragateError(
+                f"{method} {path} -> HTTP {resp.status_code}: {detail}",
+                status=resp.status_code,
+                detail=detail,
+            )
+        return resp.json()
+
+    # ---- high-level, credit-safe operations (all reuse the backend pipeline) ----
+
+    def analyze(self, narrative: str) -> dict[str, Any]:
+        return self._request("POST", "/api/v1/analyze", json={"narrative": narrative})
+
+    def get_claim(self, claim_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/claims/{claim_id}")
+
+    def list_history(self, limit: int = 20) -> list[dict[str, Any]]:
+        return self._request("GET", "/api/v1/claims/", params={"limit": limit})
+
+    def get_summary(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/claims/summary")
+
+    def get_precheck(self, sector: str | None = None) -> dict[str, Any]:
+        params = {"sector": sector} if sector else None
+        return self._request("GET", "/api/v1/precheck/", params=params)
+
+    def list_templates(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/templates")
+
+    def get_usage(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/usage")
+
+    # ---- low-level agent tools (parity with skills/*/tools.yaml) ----
+
+    def sectors_company_report(self, ticker: str, sections: list[str] | None = None) -> dict[str, Any]:
+        params = {"ticker": ticker, "sections": ",".join(sections)} if sections else {"ticker": ticker}
+        return self._request("GET", "/api/v1/tools/sectors/company-report", params=params)
+
+    def sectors_subsector_report(self, sub_sector: str, sections: list[str] | None = None) -> dict[str, Any]:
+        params = {"sub_sector": sub_sector}
+        if sections:
+            params["sections"] = ",".join(sections)
+        return self._request("GET", "/api/v1/tools/sectors/subsector-report", params=params)
+
+    def sectors_quarterly_financials(self, ticker: str, n_quarters: int = 8) -> list[dict[str, Any]]:
+        return self._request("GET", "/api/v1/tools/sectors/quarterly-financials",
+                             params={"ticker": ticker, "n_quarters": n_quarters})
+
+    def sectors_daily_transaction(self, ticker: str, start: str | None = None, end: str | None = None) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"ticker": ticker}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        return self._request("GET", "/api/v1/tools/sectors/daily-transaction", params=params)
+
+    def sectors_news(self, ticker: str, limit: int = 20) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/tools/sectors/news", params={"ticker": ticker, "limit": limit})
+
+    def sectors_corporate_actions(self, ticker: str) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/tools/sectors/corporate-actions", params={"ticker": ticker})
+
+    def sectors_filings(self, ticker: str, filing_type: str | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"ticker": ticker}
+        if filing_type:
+            params["filing_type"] = filing_type
+        return self._request("GET", "/api/v1/tools/sectors/filings", params=params)
+
+    def evidence_cache_get(self, ticker: str) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/tools/evidence-cache", params={"ticker": ticker})
+
+    def evidence_cache_merge(self, ticker: str, key: str, value: Any, ttl: int | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"ticker": ticker, "key": key, "value": value}
+        if ttl:
+            body["ttl"] = ttl
+        return self._request("POST", "/api/v1/tools/evidence-cache", json=body)
+
+    def llm_complete(self, prompt: str, system: str | None = None,
+                     response_format: dict | None = None, role: str = "default") -> dict[str, Any]:
+        body: dict[str, Any] = {"prompt": prompt, "role": role}
+        if system:
+            body["system"] = system
+        if response_format:
+            body["response_format"] = response_format
+        return self._request("POST", "/api/v1/tools/llm-complete", json=body)