finzdata-huggingface 0.1.0__py3-none-any.whl

finzdata_huggingface/__init__.py

@@ -0,0 +1,108 @@
+"""FinzData for Hugging Face: point-in-time market data, macro and backtests through function calling and MCP.
+
+Built for AI, quants, data scientists and financial analysts who backtest. Clean data. Real insights. Real alpha.
+"""
+import os
+
+from ._core import (FinzDataMCP, FinzDataError, PROFILES, MCP_URL, __version__, ask as _ask,
+                    to_openai_tools, mcp_server_config)
+
+__all__ = ["ask", "openai_tools", "mcp_config", "FinzDataMCP", "FinzDataError", "PROFILES", "MCP_URL",
+           "DEFAULT_BASE_URL", "DEFAULT_MODEL", "__version__", "TOP_MODELS", "smolagents_tools", "smolagents_agent", "tiny_agent_config", "write_tiny_agent"]
+
+DEFAULT_BASE_URL = "https://router.huggingface.co/v1"
+TOP_MODELS = {
+    "qwen": "Qwen/Qwen3.8-2.4T-A95B",
+    "qwen-fast": "Qwen/Qwen3.8-27B",
+    "kimi": "moonshotai/Kimi-K3",
+    "glm": "zai-org/GLM-5.3",
+    "deepseek": "deepseek-ai/DeepSeek-V4-Pro-0813",
+    "deepseek-fast": "deepseek-ai/DeepSeek-V4.1-Flash",
+    "llama": "meta-llama/Llama-3.3-70B-Instruct",
+    "gpt-oss": "openai/gpt-oss-120b",
+    "gemma": "google/gemma-4-26B-A4B-it",
+    "minimax": "MiniMaxAI/MiniMax-M3",
+}
+DEFAULT_MODEL = TOP_MODELS["glm"]
+
+
+def _base_url(base_url=None):
+    return base_url or DEFAULT_BASE_URL
+
+
+def _model(model=None):
+    return model or os.environ.get("FINZDATA_HF_MODEL") or DEFAULT_MODEL
+
+
+def _llm_key(llm_api_key=None):
+    return llm_api_key or os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACEHUB_API_TOKEN")
+
+
+def openai_tools(profile="data", api_key=None):
+    """FinzData's tools in OpenAI function-calling format, fetched live from the FinzData MCP server."""
+    return to_openai_tools(FinzDataMCP(api_key=api_key).tools(profile))
+
+
+def mcp_config(api_key=None):
+    """MCP server entry (``{"mcpServers": {"finzdata": ...}}``) for any MCP-capable agent, IDE or CLI."""
+    return mcp_server_config(api_key)
+
+
+def ask(question, model=None, base_url=None, llm_api_key=None, finzdata_api_key=None, profile="data", **kw):
+    """Ask Hugging Face a market question; the model calls FinzData tools and returns its final answer."""
+    model = TOP_MODELS.get(model, model)
+    return _ask(question, base_url=_base_url(base_url), model=_model(model), llm_api_key=_llm_key(llm_api_key),
+                finzdata_api_key=finzdata_api_key, profile=profile, **kw)
+
+
+def _mcp_params(api_key=None):
+    entry = mcp_server_config(api_key)["mcpServers"]["finzdata"]
+    params = {"url": MCP_URL, "transport": "streamable-http"}
+    if "headers" in entry:
+        params["headers"] = entry["headers"]
+    return params
+
+
+def smolagents_tools(api_key=None, trust_remote_code=True):
+    """smolagents ToolCollection of FinzData tools (use as a context manager)."""
+    from smolagents import ToolCollection
+    return ToolCollection.from_mcp(_mcp_params(api_key), trust_remote_code=trust_remote_code)
+
+
+def smolagents_agent(model_id=None, api_key=None):
+    """Context manager yielding a smolagents CodeAgent wired to FinzData and a Hub model."""
+    import contextlib
+
+    @contextlib.contextmanager
+    def _agent():
+        from smolagents import CodeAgent, InferenceClientModel
+        with smolagents_tools(api_key) as collection:
+            yield CodeAgent(tools=[*collection.tools], add_base_tools=False,
+                            model=InferenceClientModel(model_id=TOP_MODELS.get(model_id, model_id) or DEFAULT_MODEL))
+    return _agent()
+
+
+def tiny_agent_config(model=None, provider="auto", api_key=None):
+    """agent.json for ``tiny-agents run`` (huggingface_hub)."""
+    server = {"type": "http", "url": MCP_URL}
+    entry = mcp_server_config(api_key)["mcpServers"]["finzdata"]
+    if "headers" in entry:
+        server["headers"] = entry["headers"]
+    return {"model": TOP_MODELS.get(model, model) or DEFAULT_MODEL, "provider": provider, "servers": [server]}
+
+
+def write_tiny_agent(directory="finzdata-agent", model=None, provider="auto", api_key=None, instructions=None):
+    """Write agent.json and PROMPT.md into ``directory``; run it with ``tiny-agents run <directory>``."""
+    import json
+    import pathlib
+    from ._core import SYSTEM_PROMPT_TAIL
+    d = pathlib.Path(directory)
+    d.mkdir(parents=True, exist_ok=True)
+    (d / "agent.json").write_text(json.dumps(tiny_agent_config(model, provider, api_key), indent=2))
+    if instructions is None:
+        try:
+            instructions = FinzDataMCP(api_key=api_key).instructions()[:4000]
+        except FinzDataError:
+            instructions = "You are a market research assistant with FinzData's point-in-time market data tools."
+    (d / "PROMPT.md").write_text(instructions + "\n\n" + SYSTEM_PROMPT_TAIL + "\n")
+    return d

finzdata_huggingface/__main__.py

@@ -0,0 +1,20 @@
+import sys
+
+from . import DEFAULT_MODEL, _base_url
+from ._core import main as _main
+
+
+def cli(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if "--write-tiny-agent" in argv:
+        from . import write_tiny_agent
+        i = argv.index("--write-tiny-agent")
+        target = argv[i + 1] if len(argv) > i + 1 else "finzdata-agent"
+        print(f"Tiny Agent written to {write_tiny_agent(target)} - run: tiny-agents run {target}")
+        return 0
+    return _main(argv, defaults={"base_url": _base_url(), "model": DEFAULT_MODEL, "llm_key_env": "HF_TOKEN",
+                                 "model_env": "FINZDATA_HF_MODEL", "profile": "data", "prog": "finzdata-huggingface"})
+
+
+if __name__ == "__main__":
+    sys.exit(cli())

finzdata_huggingface/_core.py

@@ -0,0 +1,434 @@
+"""FinzData open-model bridge: lets any OpenAI-compatible chat model use FinzData's MCP tools.
+
+Stdlib only. Shared verbatim by finzdata-qwen, finzdata-kimi, finzdata-glm, finzdata-deepseek,
+finzdata-huggingface and finzdata-ollama.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import ssl
+import sys
+import time
+import urllib.error
+import urllib.request
+
+__version__ = "0.1.0"
+MCP_URL = "https://api.finzdata.com/mcp"
+USER_AGENT = f"finzdata-openmodels/{__version__}"
+
+_LITE = ("search_datasets", "describe_dataset", "get_bars", "get_macro_vintage", "get_cot", "get_gex")
+PROFILES = {
+    "lite": _LITE,
+    "data": _LITE + (
+        "get_universe", "get_fundamentals_pit", "get_quant_model", "get_13f", "get_events", "get_futures",
+        "get_futures_rolls", "get_crypto", "get_fx", "get_index", "get_global_pulse", "run_backtest",
+        "survivorship_audit", "compare_runs",
+    ),
+    "full": None,
+}
+WRITE_TOOLS = (
+    "publish_strategy", "fork_strategy", "star_strategy", "comment_strategy",
+    "register_strategy", "retire_strategy", "claim_mcp_server",
+)
+SYSTEM_PROMPT_TAIL = (
+    "Use the FinzData tools for any question about markets, prices, positioning, fundamentals, macro data or "
+    "backtests. When several markets match (for example several WTI crude contracts), use the main US benchmark "
+    "contract (NYMEX for WTI crude and natural gas, CME for E-mini equity index futures, COMEX for gold) unless the "
+    "user names another, and say which market you used. When the dataset is obvious (COT, bars, GEX, macro, 13F), call that data tool directly; use "
+    "search_datasets only when you are unsure which dataset fits. Call each tool once with the right arguments rather "
+    "than repeating it. Cite the dataset ids and snapshot ids the tools return. Never invent numbers: if a tool does not "
+    "return a figure, say so. When a result says data is beyond the free window, pass on the links it gives."
+)
+FREE_TIER_NOTE = (
+    "Access: this session uses FinzData's free AI preview - no API key needed. The preview covers the last 6 months of "
+    "data, so questions about recent months are fully answerable: fetch the data and answer with the real figures. "
+    "Never refuse, never use placeholders, and never ask the user to sign up or pay for data that is inside the preview. "
+    "Only when the user asks for something the preview does not cover (older than 6 months, or a tool says it is beyond "
+    "the free window) answer with what the preview has and say so plainly. "
+    "Close every answer with exactly one short line (once, even if a tool result also asks you to mention it): "
+    "'More data: a free FinzData API key (email only) at https://finzdata.com/account gives 12 months; full history at "
+    "https://finzdata.com/shop - then set FINZDATA_API_KEY.'"
+)
+KEYED_NOTE = ("Access: this session uses the user's FinzData API key, so their full plan applies. If a tool says data is "
+              "outside their plan, pass on the link it gives (https://finzdata.com/shop).")
+FINAL_NUDGE = ("You have gathered enough. Do not call any more tools: answer the question now from the tool results "
+               "above, with the figures and the dataset ids.")
+FREE_TIER_LINE = ("More data: a free FinzData API key (email only) at https://finzdata.com/account gives 12 months; "
+                  "full history at https://finzdata.com/shop - then set FINZDATA_API_KEY.")
+CLI_FREE_HINT = ("FinzData free AI preview (last 6 months, no key needed). More data: free API key at "
+                 "https://finzdata.com/account (12 months) or full history at https://finzdata.com/shop - then set FINZDATA_API_KEY.")
+EXAMPLES = (
+    "How are speculators positioned in crude oil futures by the latest COT report?",
+    "Show SPY's dealer gamma, call wall and put wall for the last 30 sessions.",
+    "What did the first-published CPI print say last month, before revisions?",
+    "Backtest a 12-month momentum strategy on US stocks, delisted names included.",
+    "How many ships transited the Strait of Hormuz each day last month?",
+    "Who are the largest 13F holders of NVDA, and who added the most last quarter?",
+)
+MAX_TOOL_CHARS = 12000
+TOOL_BUDGET = 48000
+TRIMMED_CHARS = 1500
+RETRIES = 2
+TIMEOUT_RETRIES = 1
+RETRY_WAIT = 2.0
+_ASSISTANT_KEYS = ("role", "content", "tool_calls")
+
+
+class FinzDataError(RuntimeError):
+    """Raised for transport, HTTP and JSON-RPC failures."""
+
+
+def api_key(explicit=None):
+    return explicit or os.environ.get("FINZDATA_API_KEY") or None
+
+
+_SSL_CTX = None
+
+
+def ssl_context():
+    """System trust store plus the certifi bundle (python.org builds on macOS ship with no root certificates)."""
+    global _SSL_CTX
+    if _SSL_CTX is None:
+        ctx = ssl.create_default_context()
+        try:
+            import certifi
+            ctx.load_verify_locations(certifi.where())
+        except Exception:
+            pass
+        _SSL_CTX = ctx
+    return _SSL_CTX
+
+
+def _post(url, payload, headers, timeout):
+    req = urllib.request.Request(url, data=json.dumps(payload).encode(), method="POST", headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout, context=ssl_context() if url.startswith("https") else None) as r:
+            return r.status, dict(r.headers), r.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", "replace") if e.fp else ""
+        raise FinzDataError(f"HTTP {e.code} from {url}: {body[:300]}") from None
+    except (urllib.error.URLError, TimeoutError, OSError) as e:
+        raise FinzDataError(f"cannot reach {url}: {e}") from None
+
+
+def _parse_rpc(body, content_type, want_id):
+    if not body.strip():
+        return None
+    if "text/event-stream" in (content_type or ""):
+        for line in body.splitlines():
+            if line.startswith("data:"):
+                try:
+                    msg = json.loads(line[5:].strip())
+                except ValueError:
+                    continue
+                if isinstance(msg, dict) and msg.get("id") == want_id:
+                    return msg
+        raise FinzDataError("no matching JSON-RPC message in event stream")
+    try:
+        return json.loads(body)
+    except ValueError:
+        raise FinzDataError(f"server returned non-JSON: {body[:300]}") from None
+
+
+class FinzDataMCP:
+    """Minimal MCP client for FinzData (streamable HTTP, JSON or SSE responses)."""
+
+    def __init__(self, url=MCP_URL, api_key=None, timeout=60, allow_write=False):
+        self.url, self.timeout, self.allow_write = url, timeout, allow_write
+        self._key = globals()["api_key"](api_key)
+        self._id, self._session, self._init, self._tools = 0, None, None, None
+
+    def _headers(self):
+        h = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream",
+             "User-Agent": USER_AGENT}
+        if self._key:
+            h["Authorization"] = f"Bearer {self._key}"
+        if self._session:
+            h["Mcp-Session-Id"] = self._session
+        return h
+
+    def _send(self, payload, want_id):
+        _, headers, body = _post(self.url, payload, self._headers(), self.timeout)
+        low = {k.lower(): v for k, v in headers.items()}
+        if low.get("mcp-session-id"):
+            self._session = low["mcp-session-id"]
+        return _parse_rpc(body, low.get("content-type", ""), want_id)
+
+    def _rpc(self, method, params=None):
+        self._id += 1
+        payload = {"jsonrpc": "2.0", "id": self._id, "method": method}
+        if params is not None:
+            payload["params"] = params
+        msg = self._send(payload, self._id)
+        if not isinstance(msg, dict):
+            raise FinzDataError(f"empty reply to {method}")
+        if msg.get("error"):
+            err = msg["error"]
+            raise FinzDataError(f"{method}: {err.get('message', err) if isinstance(err, dict) else err}")
+        return msg.get("result") or {}
+
+    def initialize(self):
+        if self._init is None:
+            self._init = self._rpc("initialize", {
+                "protocolVersion": "2025-06-18", "capabilities": {},
+                "clientInfo": {"name": "finzdata-openmodels", "version": __version__}})
+            try:
+                self._send({"jsonrpc": "2.0", "method": "notifications/initialized"}, None)
+            except FinzDataError:
+                pass
+        return self._init
+
+    def instructions(self):
+        return self.initialize().get("instructions") or ""
+
+    def list_tools(self):
+        if self._tools is None:
+            self.initialize()
+            self._tools = list(self._rpc("tools/list").get("tools") or [])
+        return self._tools
+
+    def tools(self, profile="data", allow_write=False, include=None):
+        allow = allow_write or self.allow_write
+        tools = self.list_tools()
+        if include is not None:
+            wanted = set(include)
+        elif profile not in PROFILES:
+            raise FinzDataError(f"unknown profile {profile!r}; use one of {sorted(PROFILES)}")
+        else:
+            wanted = None if PROFILES[profile] is None else set(PROFILES[profile])
+        out = []
+        for t in tools:
+            n = t.get("name")
+            if n in WRITE_TOOLS and not allow:
+                continue
+            if wanted is None or n in wanted:
+                out.append(t)
+        return out
+
+    def call(self, name, arguments=None):
+        if name in WRITE_TOOLS and not self.allow_write:
+            raise FinzDataError(f"{name} changes data on FinzData; build the client with allow_write=True to use it")
+        self.initialize()
+        res = self._rpc("tools/call", {"name": name, "arguments": arguments or {}})
+        text = "\n".join(c.get("text", "") for c in res.get("content") or [] if c.get("type") == "text")
+        return ("ERROR: " + text) if res.get("isError") else text
+
+
+def to_openai_tools(mcp_tools):
+    out = []
+    for t in mcp_tools:
+        params = dict(t.get("inputSchema") or {"type": "object", "properties": {}})
+        for k in ("$schema", "title", "additionalProperties"):
+            params.pop(k, None)
+        params.setdefault("type", "object")
+        params.setdefault("properties", {})
+        out.append({"type": "function", "function": {
+            "name": t["name"], "description": (t.get("description") or t.get("title") or "")[:1024],
+            "parameters": params}})
+    return out
+
+
+def chat_completion(base_url, model, messages, tools=None, api_key=None, timeout=150, extra=None):
+    body = {"model": model, "messages": messages}
+    if tools:
+        body["tools"], body["tool_choice"] = tools, "auto"
+    body.update(extra or {})
+    h = {"Content-Type": "application/json", "User-Agent": USER_AGENT}
+    if api_key:
+        h["Authorization"] = f"Bearer {api_key}"
+    url = base_url.rstrip("/") + "/chat/completions"
+    for attempt in range(RETRIES + 1):
+        try:
+            _, _, text = _post(url, body, h, timeout)
+            break
+        except FinzDataError as e:
+            timed_out = "timed out" in str(e)
+            transient = any(f"HTTP {c}" in str(e) for c in (429, 500, 502, 503, 504)) or timed_out
+            if attempt >= (TIMEOUT_RETRIES if timed_out else RETRIES) or not transient:
+                raise
+            time.sleep(RETRY_WAIT * (attempt + 1))
+    try:
+        return json.loads(text)
+    except ValueError:
+        raise FinzDataError(f"model server returned non-JSON: {text[:300]}") from None
+
+
+_TAG_CALL = re.compile(r"<tool_call>\s*(\{.*?\})\s*</tool_call>", re.S)
+# XML-style calls some models print as text, e.g. <invoke name="get_cot"><parameter name="market">..</parameter></invoke>
+_XML_INVOKE = re.compile(r"<(?:[\w-]+:)?invoke\s+name=\"([\w.-]+)\"\s*>(.*?)</(?:[\w-]+:)?invoke>", re.S)
+_XML_PARAM = re.compile(r"<(?:[\w-]+:)?parameter\s+name=\"([\w.-]+)\"\s*>(.*?)</(?:[\w-]+:)?parameter>", re.S)
+_CALL_MARKUP = re.compile(r"<(?:[\w-]+:)?function_calls>.*?</(?:[\w-]+:)?function_calls>|<tool_call>.*?</tool_call>|"
+                          r"<(?:[\w-]+:)?invoke\s.*?</(?:[\w-]+:)?invoke>|to=[\w.]+<\|message\|>", re.S)
+
+
+def _text_calls(content):
+    """Tool calls a model wrote into its text instead of the tool_calls field (Hermes/Qwen JSON or XML invoke)."""
+    out = []
+    for m in _TAG_CALL.finditer(content or ""):
+        try:
+            call = json.loads(m.group(1))
+            out.append((call.get("name", ""), call.get("arguments") or {}))
+        except ValueError:
+            pass
+    for m in _XML_INVOKE.finditer(content or ""):
+        args = {}
+        for k, v in _XML_PARAM.findall(m.group(2)):
+            v = v.strip()
+            try:
+                args[k] = json.loads(v) if v[:1] in "[{" or v in ("true", "false") or re.fullmatch(r"-?\d+(\.\d+)?", v) else v
+            except ValueError:
+                args[k] = v
+        out.append((m.group(1), args))
+    return out
+
+
+_REMINDER_LINE = re.compile(r"^.*finzdata\.com/(account|shop).*$", re.M)
+
+
+def finish_answer(text, keyed):
+    """Exactly one free-tier reminder line at the end when there is no key; never one with a key."""
+    text = _CALL_MARKUP.sub("", text or "").strip()
+    if keyed:
+        return text
+    lines = [ln for ln in text.splitlines() if not (_REMINDER_LINE.match(ln) and len(ln) < 400)]
+    body = "\n".join(lines).rstrip(" -*\n")
+    return (body + "\n\n" + FREE_TIER_LINE).strip()
+
+
+def _parse_args(raw):
+    if isinstance(raw, dict):
+        return raw, None
+    if raw in (None, ""):
+        return {}, None
+    try:
+        val = json.loads(raw)
+        return (val if isinstance(val, dict) else {}), None
+    except (ValueError, TypeError):
+        return None, "ERROR: arguments were not valid JSON"
+
+
+def ask(question, base_url, model, llm_api_key=None, finzdata_api_key=None, profile="data", max_turns=8,
+        system=None, client=None, extra=None, on_tool=None):
+    """Answer `question` with `model`, letting it call FinzData tools. Returns the final text."""
+    mcp = client or FinzDataMCP(api_key=finzdata_api_key)
+    tools = to_openai_tools(mcp.tools(profile))
+    names = {t["function"]["name"] for t in tools}
+    keyed = bool(mcp._key)
+    access = KEYED_NOTE if keyed else FREE_TIER_NOTE
+    sys_msg = (system or mcp.instructions()) + "\n\n" + SYSTEM_PROMPT_TAIL + "\n\n" + access
+    messages = [{"role": "system", "content": sys_msg}, {"role": "user", "content": question}]
+
+    def run(name, raw):
+        args, err = _parse_args(raw)
+        if err:
+            result = err
+        elif name not in names:
+            result = f"ERROR: unknown tool {name}"
+        else:
+            try:
+                result = mcp.call(name, args)
+            except FinzDataError as e:
+                result = f"ERROR: {e}"
+        if on_tool:
+            on_tool(name, args, result)
+        if len(result) > MAX_TOOL_CHARS:
+            result = result[:MAX_TOOL_CHARS] + "\n[truncated: ask for a narrower date range or fewer markets for the rest]"
+        return result
+
+    def trim_context():
+        """Keep long tool sessions fast: once tool output passes TOOL_BUDGET, shorten the oldest results."""
+        tool_msgs = [m for m in messages if m.get("role") == "tool"]
+        total = sum(len(m["content"]) for m in tool_msgs)
+        for m in tool_msgs[:-1]:
+            if total <= TOOL_BUDGET:
+                break
+            if len(m["content"]) > TRIMMED_CHARS:
+                total -= len(m["content"]) - TRIMMED_CHARS
+                m["content"] = m["content"][:TRIMMED_CHARS] + "\n[earlier result trimmed to save context]"
+
+    last, minimal = "", False
+
+    def slim(msgs):
+        return [({k: v for k, v in m.items() if k in _ASSISTANT_KEYS} if m.get("role") == "assistant" else m) for m in msgs]
+
+    for turn in range(max_turns):
+        final = turn == max_turns - 1
+        if final:  # last round: no more tools, answer from what has been gathered
+            messages.append({"role": "user", "content": FINAL_NUDGE})
+        ex = dict(extra or {}, tool_choice="none") if final else extra
+        try:
+            resp = chat_completion(base_url, model, slim(messages) if minimal else messages, tools, llm_api_key, extra=ex)
+        except FinzDataError as e:
+            if minimal or "HTTP 400" not in str(e) or not any(m.get("role") == "assistant" for m in messages):
+                raise
+            minimal = True  # this server rejects extra assistant fields (e.g. reasoning); resend without them
+            resp = chat_completion(base_url, model, slim(messages), tools, llm_api_key, extra=ex)
+        try:
+            msg = resp["choices"][0]["message"]
+        except (KeyError, IndexError, TypeError):
+            raise FinzDataError(f"unexpected model reply: {json.dumps(resp)[:300]}") from None
+        content = msg.get("content") or ""
+        last = content or last
+        calls = msg.get("tool_calls") or []
+        if final:
+            return finish_answer(_CALL_MARKUP.sub("", content).strip() or last or f"Stopped after {max_turns} tool rounds.", keyed)
+        if calls:
+            kept = {k: v for k, v in msg.items() if v is not None or k == "content"}
+            kept["role"] = "assistant"
+            messages.append(kept)  # unchanged, incl. reasoning_content: thinking models (Kimi K3, DeepSeek V4) need it
+            for c in calls:
+                fn = c.get("function") or {}
+                result = run(fn.get("name", ""), fn.get("arguments"))
+                messages.append({"role": "tool", "tool_call_id": c.get("id", ""), "name": fn.get("name", ""),
+                                 "content": result})
+            trim_context()
+            continue
+        text_calls = _text_calls(content)
+        if text_calls:
+            results = [f"<tool_response name=\"{n}\">\n{run(n, a)}\n</tool_response>" for n, a in text_calls]
+            messages.append({"role": "assistant", "content": content})
+            messages.append({"role": "user", "content": "\n".join(results)})
+            continue
+        return finish_answer(content, keyed)
+    return finish_answer(last or f"Stopped after {max_turns} tool rounds.", keyed)
+
+
+def mcp_server_config(api_key=None, name="finzdata"):
+    entry = {"url": MCP_URL, "type": "streamable-http"}
+    key = globals()["api_key"](api_key)
+    if key:
+        entry["headers"] = {"Authorization": f"Bearer {key}"}
+    return {"mcpServers": {name: entry}}
+
+
+def main(argv=None, defaults=None):
+    d = {"base_url": "http://localhost:11434/v1", "model": "qwen3:8b", "llm_key_env": "", "model_env": "",
+         "profile": "data", "prog": "finzdata"}
+    d.update(defaults or {})
+    p = argparse.ArgumentParser(prog=d["prog"], description="Ask an AI model a market question using FinzData data.")
+    p.add_argument("question", nargs="?", default="")
+    p.add_argument("--model", default=(os.environ.get(d["model_env"]) if d["model_env"] else None) or d["model"])
+    p.add_argument("--base-url", default=d["base_url"])
+    p.add_argument("--profile", default=d["profile"], choices=sorted(PROFILES))
+    p.add_argument("--show-tools", action="store_true", help="list the FinzData tools the model will see")
+    a = p.parse_args(argv)
+    try:
+        if a.show_tools:
+            for t in FinzDataMCP().tools(a.profile):
+                print(t["name"])
+            return 0
+        if not a.question:
+            p.error("a question is required")
+        key = os.environ.get(d["llm_key_env"]) if d["llm_key_env"] else None
+        answer = ask(a.question, a.base_url, a.model, llm_api_key=key, profile=a.profile,
+                     on_tool=lambda n, args, r: print(f"-> {n}({json.dumps(args)})", file=sys.stderr))
+        print(answer)
+        if not api_key():
+            print("\n" + CLI_FREE_HINT, file=sys.stderr)
+        return 0
+    except FinzDataError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1

finzdata_huggingface-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: finzdata-huggingface
+Version: 0.1.0
+Summary: FinzData for Hugging Face: point-in-time market data, macro and backtests through function calling and MCP.
+Author-email: FinzData <info@finzdata.com>
+License: MIT
+Project-URL: Homepage, https://finzdata.com/agents
+Project-URL: Documentation, https://finzdata.com/docs
+Project-URL: Source, https://github.com/FinzData/finzdata-huggingface
+Keywords: huggingface,smolagents,tiny-agents,inference-providers,qwen,kimi,glm,llama,gemma,mistral,gpt-oss,finzdata,mcp,market-data,function-calling,backtesting,ai-agents
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+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: certifi
+Provides-Extra: smolagents
+Requires-Dist: smolagents[mcp]; extra == "smolagents"
+Provides-Extra: hub
+Requires-Dist: huggingface_hub[mcp]; extra == "hub"
+Dynamic: license-file
+
+# FinzData for Hugging Face
+
+Built for AI, quants, data scientists and financial analysts who backtest. Clean data. Real insights. Real alpha.
+
+FinzData gives Hugging Face point-in-time market data, macro vintages and server-side backtests through function calling and MCP —
+so the model answers market questions with real numbers it can cite, never guesses.
+
+## No API key needed
+
+FinzData works the moment you install it: no FinzData account and no FinzData key. Your model gets the free AI preview
+(the last 6 months of data) automatically, and it knows to tell you when older or deeper data needs a key.
+When you want more, get a free API key (email only, 12 months of data) at https://finzdata.com/account, or full
+history at https://finzdata.com/shop, then set `FINZDATA_API_KEY`. Nothing else changes.
+
+## Install
+
+```bash
+pip install finzdata-huggingface
+```
+
+## Quick start
+
+```python
+from finzdata_huggingface import ask
+print(ask("How did managed money positioning in crude oil change over the last 3 months?"))   # no FinzData key needed
+```
+
+## What to ask
+
+- "How are speculators positioned in crude oil futures by the latest COT report?"
+- "Show SPY's dealer gamma, call wall and put wall for the last 30 sessions."
+- "What did the first-published CPI print say last month, before revisions?"
+- "Backtest a 12-month momentum strategy on US stocks, delisted names included."
+- "How many ships transited the Strait of Hormuz each day last month?"
+- "Who are the largest 13F holders of NVDA, and who added the most last quarter?"
+
+## Command line
+
+```bash
+finzdata-huggingface "How did managed money positioning in crude oil change over the last 3 months?"
+finzdata-huggingface --show-tools
+```
+
+## Inference Providers
+
+Set `HF_TOKEN` and pick any of the top open models by family name or Hub id:
+
+| family | Hub id |
+|---|---|
+| qwen | `Qwen/Qwen3.8-2.4T-A95B` |
+| qwen-fast | `Qwen/Qwen3.8-27B` |
+| kimi | `moonshotai/Kimi-K3` |
+| glm | `zai-org/GLM-5.3` |
+| deepseek | `deepseek-ai/DeepSeek-V4-Pro-0813` |
+| deepseek-fast | `deepseek-ai/DeepSeek-V4.1-Flash` |
+| llama | `meta-llama/Llama-3.3-70B-Instruct` |
+| gpt-oss | `openai/gpt-oss-120b` |
+| gemma | `google/gemma-4-26B-A4B-it` |
+| minimax | `MiniMaxAI/MiniMax-M3` |
+
+```python
+from finzdata_huggingface import ask
+ask("Which ETFs saw the largest 13F ownership changes last quarter?", model="kimi")
+ask("Plot-ready: SPX gamma flip for the last 20 sessions", model="meta-llama/Llama-3.3-70B-Instruct")
+```
+
+Each id above was live with several Inference Providers in November 2026. Hub ids evolve; any Hub model with tool calling works.
+
+## smolagents
+
+```python
+from finzdata_huggingface import smolagents_agent
+with smolagents_agent("qwen") as agent:
+    agent.run("Backtest a 50/200-day moving-average cross on SPY since 2005 and report the Sharpe ratio.")
+```
+
+Or take the tools alone: `with smolagents_tools() as tc: tools = tc.tools`.
+
+## Tiny Agents
+
+```bash
+finzdata-huggingface --write-tiny-agent finzdata-agent
+tiny-agents run ./finzdata-agent
+```
+
+## Hugging Face Spaces and Gradio
+
+Try it in the browser: https://huggingface.co/spaces/FinzData/finzdata-open-models. The same `ask` call powers a Gradio app in a few lines.
+
+## Llama, Gemma, Mistral, gpt-oss and MiniMax
+
+All of them run through the same `ask(..., model=...)`. Mistral's open models run best on your own machine: see `pip install finzdata-ollama`.
+
+## Use with any OpenAI-compatible server
+
+```python
+from finzdata_huggingface import openai_tools, FinzDataMCP
+tools = openai_tools()          # pass as `tools=` to any chat.completions call
+result = FinzDataMCP().call("get_cot", {"market": "crude"})   # run the tool the model picked
+```
+
+## Tool profiles
+
+`lite` (6 core tools, for small models), `data` (20 data and backtest tools, the default) and `full` (every read tool).
+Tools that change data on FinzData are never exposed unless you ask for them explicitly.
+
+## Coverage
+
+16,000+ US stocks that have traded on NYSE and Nasdaq since January 2000, delisted included, point in time; 5,100+ ETFs; 139 futures markets with every contract since 2007; point-in-time options gamma (GEX) for single stocks, ETFs and the major indexes; CFTC COT since 1986; 13F holdings; SEC fundamentals as filed; end-of-day options chains; 22,700+ macro series with every vintage kept; 512 crypto pairs (Bitcoin since 2013); FX for 79 currency pairs; 123 indexes incl. the VIX term structure; tick trades for 1,100+ US stocks and ETFs; FinzData Global Macro Pulse (ship transits through 28 chokepoints, port calls, flights, toll traffic); 1, 5, 15, 30-minute, hourly and daily bars; server-side backtests.
+
+## Access
+
+No key needed to start: AI/MCP use gives the last 6 months. A free account (email only, https://finzdata.com/account) gives the last 12 months of daily US stock bars, COT, SEC fundamentals, US macro and 13F, and the last 30 days of futures and daily GEX. Full history: https://finzdata.com/shop — $19 one ticker, $49 one futures market, $195 for 5 years of the whole US market.
+
+With a key:
+
+```bash
+export FINZDATA_API_KEY=fz_...   # free at https://finzdata.com/account
+```
+
+or pass `finzdata_api_key="fz_..."` to `ask`.
+
+## Links
+
+- Site: https://finzdata.com
+- Docs: https://finzdata.com/docs
+- MCP server: https://api.finzdata.com/mcp
+- Python client: `pip install finzdata`
+- Contact: the FinzData team, info@finzdata.com

finzdata_huggingface-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+finzdata_huggingface/__init__.py,sha256=0-T39bPy9rSTVhspTuxhOBjZI0O6YhHb1c1cdyWQFhE,4664
+finzdata_huggingface/__main__.py,sha256=cjveS9GtmrhL_LZQrw4KeLrPzsghkVNnpwpLNOBY1b8,748
+finzdata_huggingface/_core.py,sha256=y3ZdqtwjhbaVIj0CTgHarOgI-ZIpKU27l3l_xclE-i4,19868
+finzdata_huggingface-0.1.0.dist-info/licenses/LICENSE,sha256=vsxVRtneGOt7Hno_gT97_iH2M3tsteCip75_rUnHGi8,1065
+finzdata_huggingface-0.1.0.dist-info/METADATA,sha256=L5oSjdE5XR-go2H13dclntqn02qpV_YcTBbZjYRuM9g,6595
+finzdata_huggingface-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+finzdata_huggingface-0.1.0.dist-info/entry_points.txt,sha256=4ukxnj3yQ6QjXGblNwDTLZbvYsWGXWjmHnqzKPwLyJ8,75
+finzdata_huggingface-0.1.0.dist-info/top_level.txt,sha256=DU6t96ZyCxR7UTPS_MWsPRkDMGdtCTOB44ahtojzYlg,21
+finzdata_huggingface-0.1.0.dist-info/RECORD,,

finzdata_huggingface-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

finzdata_huggingface-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+finzdata-huggingface = finzdata_huggingface.__main__:cli

finzdata_huggingface-0.1.0.dist-info/licenses/LICENSE

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

finzdata_huggingface-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+finzdata_huggingface