tensorfeed 2.0.0__tar.gz → 2.1.0__tar.gz

{tensorfeed-2.0.0 → tensorfeed-2.1.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tensorfeed
-Version: 2.0.0
-Summary: Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, agent payments via USDC on Base (optional web3 auto-send)
+Version: 2.1.0
+Summary: Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, LangChain/CrewAI tool factories, agent payments via USDC on Base (optional web3 auto-send)
 Author-email: "TensorFeed.ai" <feedback@tensorfeed.ai>
 License-Expression: MIT
 Project-URL: Homepage, https://tensorfeed.ai
@@ -197,6 +197,34 @@ print(tf.balance())
 rec = tf.routing(task="code")
 ```
 
+## Framework Tools (LangChain, CrewAI)
+
+Drop TensorFeed into an agent framework as ready-made tools.
+
+```bash
+pip install 'tensorfeed[langchain]'   # or 'tensorfeed[crewai]'
+```
+
+```python
+from tensorfeed.langchain import tensorfeed_tools, tensorfeed_premium_tools
+
+# Five free tools (news, status, attention, harnesses, routing preview)
+free = tensorfeed_tools()
+
+# Free plus the paid catalog (whats_new, full routing, compare models,
+# cost projection, news search, provider deep dive, status leaderboard)
+all_tools = tensorfeed_tools(token="YOUR_TOKEN", include_premium=True)
+
+# Just the paid catalog
+paid = tensorfeed_premium_tools(token="YOUR_TOKEN")
+```
+
+CrewAI is identical: `from tensorfeed.crewai import tensorfeed_tools, tensorfeed_premium_tools`.
+
+The default `tensorfeed_tools()` stays free-only and unchanged, so existing code keeps working. Premium is opt-in via `include_premium=True`.
+
+**Payment posture.** The premium tools never move funds. Attach them with or without a token: called without spendable credits they return a short, actionable guidance string (explaining that an operator provisions credits out of band) instead of paying or raising. There is no code path from a tool call to the wallet or the web3 signer. Credit purchases stay an explicit, per-action operator decision, by design. This is enforced in one shared module and covered by tests, including a static guard that fails if a future change introduces an autonomous-payment path.
+
 ## Error Handling
 
 ```python

{tensorfeed-2.0.0 → tensorfeed-2.1.0}/README.md

@@ -164,6 +164,34 @@ print(tf.balance())
 rec = tf.routing(task="code")
 ```
 
+## Framework Tools (LangChain, CrewAI)
+
+Drop TensorFeed into an agent framework as ready-made tools.
+
+```bash
+pip install 'tensorfeed[langchain]'   # or 'tensorfeed[crewai]'
+```
+
+```python
+from tensorfeed.langchain import tensorfeed_tools, tensorfeed_premium_tools
+
+# Five free tools (news, status, attention, harnesses, routing preview)
+free = tensorfeed_tools()
+
+# Free plus the paid catalog (whats_new, full routing, compare models,
+# cost projection, news search, provider deep dive, status leaderboard)
+all_tools = tensorfeed_tools(token="YOUR_TOKEN", include_premium=True)
+
+# Just the paid catalog
+paid = tensorfeed_premium_tools(token="YOUR_TOKEN")
+```
+
+CrewAI is identical: `from tensorfeed.crewai import tensorfeed_tools, tensorfeed_premium_tools`.
+
+The default `tensorfeed_tools()` stays free-only and unchanged, so existing code keeps working. Premium is opt-in via `include_premium=True`.
+
+**Payment posture.** The premium tools never move funds. Attach them with or without a token: called without spendable credits they return a short, actionable guidance string (explaining that an operator provisions credits out of band) instead of paying or raising. There is no code path from a tool call to the wallet or the web3 signer. Credit purchases stay an explicit, per-action operator decision, by design. This is enforced in one shared module and covered by tests, including a static guard that fails if a future change introduces an autonomous-payment path.
+
 ## Error Handling
 
 ```python

{tensorfeed-2.0.0 → tensorfeed-2.1.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tensorfeed"
-version = "2.0.0"
-description = "Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, agent payments via USDC on Base (optional web3 auto-send)"
+version = "2.1.0"
+description = "Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, LangChain/CrewAI tool factories, agent payments via USDC on Base (optional web3 auto-send)"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.9"

{tensorfeed-2.0.0 → tensorfeed-2.1.0}/tensorfeed/__init__.py

@@ -21,4 +21,4 @@ __all__ = [
     "PaymentRequired",
     "RateLimited",
 ]
-__version__ = "1.29.0"
+__version__ = "2.1.0"

tensorfeed-2.1.0/tensorfeed/_premium_tools.py

@@ -0,0 +1,341 @@
+"""Shared premium-tool plumbing for the framework adapters.
+
+Internal module. Powers ``tensorfeed.langchain.tensorfeed_premium_tools()``
+and ``tensorfeed.crewai.tensorfeed_premium_tools()``. It is framework
+agnostic: it owns the canonical tool descriptions, the result
+formatters, and the one piece of behavior that must never drift between
+frameworks, the payment posture.
+
+Payment posture (load-bearing, do not weaken):
+
+  These tools never move funds. A premium call made without a valid
+  token returns a clear, actionable guidance string explaining how an
+  operator provisions credits out of band. The tool does not, and will
+  not, initiate a USDC transfer on its own. Autonomous payment from
+  inside a tool call is a deliberate non-feature: credit purchases stay
+  an explicit, per-action operator decision. Centralizing this here (and
+  testing it once) keeps every framework binding honest.
+
+Each adapter writes its own thin, explicitly typed function or tool
+class so the framework gets a good argument schema for the model, then
+routes the call through ``safe_call`` with the shared formatter. The
+descriptions are shared verbatim so LangChain and CrewAI surface
+identical copy to the agent.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .client import PaymentRequired, RateLimited, TensorFeedError
+
+
+# The exact, actionable message an agent sees when a premium tool is
+# called without spendable credits. It tells the model what is true
+# (this needs credits), what will not happen (no automatic payment),
+# and what the path is (an operator provisions a token out of band).
+PREMIUM_PAYMENT_GUIDANCE = (
+    "This is a paid TensorFeed endpoint (1 credit) and no spendable "
+    "credit token is available. This tool will not buy credits or move "
+    "any funds on its own, by design. To enable it, an operator must "
+    "provision credits out of band (buy_credits() then confirm() with a "
+    "USDC payment on Base, or the documented x402 flow) and pass the "
+    "resulting token when constructing the tools, for example "
+    "tensorfeed_premium_tools(token='...'). Until then, prefer the free "
+    "TensorFeed tools (news, status, attention, harnesses, routing "
+    "preview) for this question."
+)
+
+
+def _billing_line(result: dict[str, Any]) -> str:
+    """One-line cost footer if the response carries billing metadata."""
+    billing = result.get("billing")
+    if not isinstance(billing, dict):
+        return ""
+    charged = billing.get("credits_charged")
+    remaining = billing.get("balance")
+    bits = []
+    if charged is not None:
+        bits.append(f"{charged} credit(s) charged")
+    if remaining is not None:
+        bits.append(f"{remaining} remaining")
+    return f"\n[{', '.join(bits)}]" if bits else ""
+
+
+def safe_call(
+    invoke: Callable[[], dict[str, Any]],
+    formatter: Callable[[dict[str, Any]], str],
+) -> str:
+    """Run a premium client call and return agent-readable text.
+
+    Never raises for the expected money and quota cases. A raised
+    exception inside an agent tool call usually aborts the agent or
+    produces an opaque trace; a structured guidance string lets the
+    model reason about what to do next (typically: tell the user it
+    needs credits, or fall back to a free tool).
+
+      * no token / token rejected (402): the payment guidance string
+      * rate limited (429): a short back-off message
+      * other API error: a concise one-line error
+      * success: the tool's own formatter output
+
+    The PaymentRequired and missing-token paths are exactly where an
+    autonomous-payment bug would hide. There is intentionally no code
+    path here that touches the wallet or the web3 signer.
+    """
+    try:
+        result = invoke()
+    except PaymentRequired as e:
+        hint = ""
+        payload = getattr(e, "payload", None)
+        if isinstance(payload, dict):
+            need = payload.get("credits_required")
+            if need is not None:
+                hint = f" (endpoint requires {need} credit(s))"
+        return PREMIUM_PAYMENT_GUIDANCE + hint
+    except ValueError:
+        # client raises ValueError when no token is set on the client
+        return PREMIUM_PAYMENT_GUIDANCE
+    except RateLimited:
+        return (
+            "TensorFeed rate limit hit. Wait and retry, or reduce call "
+            "frequency. Free public endpoints allow 120 requests/minute "
+            "per IP; bearer tokens are exempt."
+        )
+    except TensorFeedError as e:
+        return f"TensorFeed API error {e.status_code}: {e}"
+    try:
+        return formatter(result) + _billing_line(result)
+    except Exception:  # defensive: a shape change must not break the agent
+        return (
+            "TensorFeed returned a response in an unexpected shape. Raw "
+            f"top-level keys: {sorted(result) if isinstance(result, dict) else type(result).__name__}."
+        )
+
+
+# ── Shared descriptions (identical copy across frameworks) ─────────────
+#
+# Every description states the credit cost up front so the model can
+# weigh it before calling, and what the tool is uniquely good for so it
+# is picked for the right question.
+
+DESCRIPTIONS: dict[str, str] = {
+    "tensorfeed_whats_new": (
+        "PAID, 1 credit. The agent boot brief: a single curated summary "
+        "of AI model pricing changes, new and removed models, service "
+        "incidents that started or resolved, current operational counts, "
+        "and the top news headlines, over the last 1 to 7 days. Call "
+        "this once at startup instead of polling many free endpoints. "
+        "Inputs: days (1-7, default 1), news_limit (1-25, default 10)."
+    ),
+    "tensorfeed_routing": (
+        "PAID, 1 credit. Full ranked model routing: the top-N AI models "
+        "for a task with a complete score breakdown (quality, "
+        "availability, cost, latency). Use this when the free top-1 "
+        "preview is not enough. Inputs: task (code|reasoning|creative|"
+        "general), budget (optional max blended USD per 1M tokens), "
+        "top_n (1-10, default 5)."
+    ),
+    "tensorfeed_compare_models": (
+        "PAID, 1 credit. Side-by-side comparison of 2 to 5 AI models: "
+        "pricing, normalized benchmarks, live provider status, context "
+        "window, capabilities, recent news, plus rankings for cheapest "
+        "blended and most context. Input: ids (comma-separated model "
+        "ids or display names, 2 to 5)."
+    ),
+    "tensorfeed_cost_projection": (
+        "PAID, 1 credit. Project the cost of a token-usage workload "
+        "across 1 to 10 models over day, week, month, and year, with a "
+        "cheapest-monthly ranking. Inputs: models (comma-separated), "
+        "input_tokens_per_day, output_tokens_per_day, horizon (optional)."
+    ),
+    "tensorfeed_news_search": (
+        "PAID, 1 credit. Full-text search over the TensorFeed AI news "
+        "corpus with relevance scoring and a recency boost. Filter by "
+        "query, date range, provider, and category. Use this instead of "
+        "the free latest-news feed when you need to find specific "
+        "coverage. Inputs: q, from_date, to_date, provider, category, "
+        "limit (1-100, default 25)."
+    ),
+    "tensorfeed_provider_deepdive": (
+        "PAID, 1 credit. One AI provider's full profile in a single "
+        "call: live status, every model with pricing and benchmarks "
+        "joined in, recent news, and agent-traffic attribution. Doing "
+        "this from free endpoints takes several round-trips and a "
+        "non-trivial join. Input: provider (id or display name)."
+    ),
+    "tensorfeed_status_leaderboard": (
+        "PAID, 1 credit. Cross-provider AI uptime leaderboard over the "
+        "full 90-day retention window, with incident_count and "
+        "mttr_minutes per provider. Built for vendor selection and "
+        "post-incident review. Inputs: from_date, to_date (optional, "
+        "default last 30 days)."
+    ),
+}
+
+PREMIUM_TOOL_NAMES: list[str] = list(DESCRIPTIONS)
+
+
+# ── Shared result formatters ───────────────────────────────────────────
+#
+# Compact, deterministic, defensive. They turn a response dict into a
+# short text block an LLM can read. Lists are truncated. Missing keys
+# degrade to a sane default rather than raising (safe_call also guards
+# the formatter, this is belt and suspenders).
+
+
+def format_whats_new(r: dict[str, Any]) -> str:
+    w = r.get("window", {})
+    s = r.get("summary", {})
+    lines = [f"What's new ({w.get('days', '?')}d window):"]
+    pricing = r.get("pricing", {}) or {}
+    changed = pricing.get("changes", []) or []
+    added = pricing.get("new_models", []) or []
+    removed = pricing.get("removed_models", []) or []
+    lines.append(
+        f"  pricing: {len(changed)} changes, {len(added)} new, "
+        f"{len(removed)} removed models"
+    )
+    for c in changed[:5]:
+        lines.append(
+            f"    {c.get('model', '?')} {c.get('field', '')}: "
+            f"{c.get('from')} -> {c.get('to')}"
+        )
+    status = r.get("status", {}) or {}
+    incidents = status.get("incidents", []) or []
+    lines.append(f"  status: {len(incidents)} incident(s) in window")
+    for i in incidents[:3]:
+        lines.append(
+            f"    {i.get('provider', '?')}: {i.get('state', i.get('status', ''))}"
+        )
+    news = r.get("news", []) or []
+    lines.append(f"  news: {len(news)} headlines")
+    for n in news[:5]:
+        lines.append(f"    - {n.get('title', '')} ({n.get('source', '')})")
+    if s:
+        lines.append(f"  counts: {s}")
+    return "\n".join(lines)
+
+
+def format_routing(r: dict[str, Any]) -> str:
+    recs = r.get("recommendations") or r.get("recommendation") or []
+    if isinstance(recs, dict):
+        recs = [recs]
+    if not recs:
+        return "No routing recommendation returned."
+    lines = ["Model routing (ranked):"]
+    for x in recs[:10]:
+        model = x.get("model", {})
+        name = model.get("name") if isinstance(model, dict) else model
+        score = x.get("composite_score", x.get("score"))
+        try:
+            score_s = f"{float(score):.3f}"
+        except (TypeError, ValueError):
+            score_s = str(score)
+        lines.append(
+            f"  #{x.get('rank', '?')} {name}  score={score_s}"
+            f"  provider={x.get('provider', model.get('provider') if isinstance(model, dict) else '')}"
+        )
+    return "\n".join(lines)
+
+
+def format_compare_models(r: dict[str, Any]) -> str:
+    models = r.get("models", []) or []
+    lines = [f"Compared {len(models)} model(s):"]
+    for m in models[:5]:
+        name = m.get("name") or m.get("id") or "?"
+        if m.get("unmatched"):
+            lines.append(f"  {name}: (no match)")
+            continue
+        pricing = m.get("pricing", {}) or {}
+        lines.append(
+            f"  {name}: in {pricing.get('inputPrice', '?')} / "
+            f"out {pricing.get('outputPrice', '?')} per 1M, "
+            f"ctx {m.get('context_window', '?')}"
+        )
+    rankings = r.get("rankings", {}) or {}
+    if rankings.get("cheapest_blended"):
+        lines.append(f"  cheapest blended: {rankings['cheapest_blended']}")
+    if rankings.get("most_context"):
+        lines.append(f"  most context: {rankings['most_context']}")
+    return "\n".join(lines)
+
+
+def format_cost_projection(r: dict[str, Any]) -> str:
+    proj = r.get("projections", []) or []
+    lines = ["Cost projection (per model):"]
+    for p in proj[:10]:
+        name = p.get("model", "?")
+        monthly = p.get("monthly", p.get("monthly_cost"))
+        lines.append(f"  {name}: ~{monthly}/month")
+    ranked = r.get("ranked_cheapest_monthly", []) or []
+    if ranked:
+        head = ranked[0]
+        name = head.get("model") if isinstance(head, dict) else head
+        lines.append(f"  cheapest monthly: {name}")
+    return "\n".join(lines)
+
+
+def format_news_search(r: dict[str, Any]) -> str:
+    results = r.get("results", []) or []
+    lines = [
+        f"News search: {r.get('matched', len(results))} matched, "
+        f"showing {len(results)}"
+    ]
+    for a in results[:10]:
+        lines.append(
+            f"  - {a.get('title', '')} ({a.get('source', '')}, "
+            f"{a.get('published_at', '')}) {a.get('url', '')}"
+        )
+    return "\n".join(lines)
+
+
+def format_provider_deepdive(r: dict[str, Any]) -> str:
+    prov = r.get("provider", "?")
+    status = r.get("status", {})
+    st = status.get("status") if isinstance(status, dict) else status
+    models = r.get("models", []) or []
+    lines = [
+        f"{prov}: status={st}, {len(models)} model(s), "
+        f"{r.get('recent_news_count', 0)} recent news, "
+        f"{r.get('agent_traffic_24h', 0)} agent hits/24h"
+    ]
+    for m in models[:6]:
+        lines.append(
+            f"  {m.get('name', m.get('id', '?'))}: "
+            f"tier {m.get('tier', '?')}, ctx {m.get('context_window', '?')}"
+        )
+    for n in (r.get("recent_news", []) or [])[:5]:
+        lines.append(f"  news: {n.get('title', '')} ({n.get('source', '')})")
+    return "\n".join(lines)
+
+
+def format_status_leaderboard(r: dict[str, Any]) -> str:
+    entries = r.get("entries", []) or []
+    if not entries:
+        return (
+            "No leaderboard data for the requested window "
+            f"({r.get('error', 'no_data')})."
+        )
+    lines = ["AI provider uptime leaderboard:"]
+    for e in entries[:15]:
+        lines.append(
+            f"  #{e.get('rank', '?')} {e.get('provider', '?')}: "
+            f"{e.get('uptime_pct', '?')}% uptime, "
+            f"{e.get('incident_count', 0)} incidents, "
+            f"MTTR {e.get('mttr_minutes', '?')}m"
+        )
+    return "\n".join(lines)
+
+
+# Maps tool name -> (client method name, formatter). The adapters use
+# this so the call target and the formatter never drift apart.
+FORMATTERS: dict[str, Callable[[dict[str, Any]], str]] = {
+    "tensorfeed_whats_new": format_whats_new,
+    "tensorfeed_routing": format_routing,
+    "tensorfeed_compare_models": format_compare_models,
+    "tensorfeed_cost_projection": format_cost_projection,
+    "tensorfeed_news_search": format_news_search,
+    "tensorfeed_provider_deepdive": format_provider_deepdive,
+    "tensorfeed_status_leaderboard": format_status_leaderboard,
+}

{tensorfeed-2.0.0 → tensorfeed-2.1.0}/tensorfeed/crewai.py

@@ -11,6 +11,11 @@ Provides a set of CrewAI-compatible tools:
     * ``tensorfeed_harnesses_tool()`` - coding harness leaderboard
     * ``tensorfeed_routing_tool()``   - top model recommendation
 
+Plus the paid catalog via ``tensorfeed_premium_tools()`` (1 credit per
+call). Premium tools never move funds: called without a credit token
+they return a clear guidance string instead of paying or raising.
+Provisioning credits stays an explicit operator action.
+
 Usage::
 
     from crewai import Agent
@@ -33,6 +38,7 @@ import json
 from typing import Any
 
 from .client import TensorFeed
+from ._premium_tools import DESCRIPTIONS, FORMATTERS, safe_call
 
 
 def _require_crewai() -> Any:
@@ -163,12 +169,140 @@ def tensorfeed_routing_tool(token: str | None = None) -> Any:
     return _Tool()
 
 
-def tensorfeed_tools(token: str | None = None) -> list[Any]:
-    """Convenience: returns the full TensorFeed CrewAI tool list."""
-    return [
+def tensorfeed_tools(
+    token: str | None = None,
+    *,
+    include_premium: bool = False,
+) -> list[Any]:
+    """Convenience: the TensorFeed CrewAI tool list.
+
+    Returns the five free tools by default. Pass
+    ``include_premium=True`` to also attach the paid catalog (1 credit
+    per call). Premium tools are safe to attach without a token: called
+    with no credits they return guidance instead of paying or raising.
+    """
+    tools = [
         tensorfeed_news_tool(token),
         tensorfeed_status_tool(token),
         tensorfeed_attention_tool(token),
         tensorfeed_harnesses_tool(token),
         tensorfeed_routing_tool(token),
     ]
+    if include_premium:
+        tools.extend(tensorfeed_premium_tools(token))
+    return tools
+
+
+# ── Premium tools (paid, 1 credit each, never auto-pay) ───────────────
+#
+# Each is a thin CrewAI BaseTool whose _run routes through the shared
+# safe_call, so the payment posture and formatting match the LangChain
+# binding exactly and are tested once in test_premium_tools.py.
+
+
+def _premium_tool(token: str | None, tool_name: str, runner) -> Any:
+    BaseTool = _require_crewai()
+    fmt = FORMATTERS[tool_name]
+
+    class _Tool(BaseTool):  # type: ignore[misc, valid-type]
+        name: str = tool_name
+        description: str = DESCRIPTIONS[tool_name]
+
+        def _run(self, **kwargs: Any) -> str:
+            return safe_call(lambda: runner(_client(token), kwargs), fmt)
+
+    return _Tool()
+
+
+def tensorfeed_whats_new_tool(token: str | None = None) -> Any:
+    return _premium_tool(
+        token,
+        "tensorfeed_whats_new",
+        lambda c, kw: c.whats_new(
+            days=kw.get("days", 1), news_limit=kw.get("news_limit", 10)
+        ),
+    )
+
+
+def tensorfeed_routing_full_tool(token: str | None = None) -> Any:
+    return _premium_tool(
+        token,
+        "tensorfeed_routing",
+        lambda c, kw: c.routing(
+            task=kw.get("task", "general"),
+            budget=kw.get("budget"),
+            top_n=kw.get("top_n", 5),
+        ),
+    )
+
+
+def tensorfeed_compare_models_tool(token: str | None = None) -> Any:
+    return _premium_tool(
+        token,
+        "tensorfeed_compare_models",
+        lambda c, kw: c.compare_models(ids=kw.get("ids", "")),
+    )
+
+
+def tensorfeed_cost_projection_tool(token: str | None = None) -> Any:
+    return _premium_tool(
+        token,
+        "tensorfeed_cost_projection",
+        lambda c, kw: c.cost_projection(
+            models=kw.get("models", ""),
+            input_tokens_per_day=kw.get("input_tokens_per_day", 0),
+            output_tokens_per_day=kw.get("output_tokens_per_day", 0),
+            horizon=kw.get("horizon"),
+        ),
+    )
+
+
+def tensorfeed_news_search_tool(token: str | None = None) -> Any:
+    return _premium_tool(
+        token,
+        "tensorfeed_news_search",
+        lambda c, kw: c.news_search(
+            q=kw.get("q"),
+            from_date=kw.get("from_date"),
+            to_date=kw.get("to_date"),
+            provider=kw.get("provider"),
+            category=kw.get("category"),
+            limit=kw.get("limit", 25),
+        ),
+    )
+
+
+def tensorfeed_provider_deepdive_tool(token: str | None = None) -> Any:
+    return _premium_tool(
+        token,
+        "tensorfeed_provider_deepdive",
+        lambda c, kw: c.provider_deepdive(kw.get("provider", "")),
+    )
+
+
+def tensorfeed_status_leaderboard_tool(token: str | None = None) -> Any:
+    return _premium_tool(
+        token,
+        "tensorfeed_status_leaderboard",
+        lambda c, kw: c.status_leaderboard(
+            from_date=kw.get("from_date"), to_date=kw.get("to_date")
+        ),
+    )
+
+
+def tensorfeed_premium_tools(token: str | None = None) -> list[Any]:
+    """The paid TensorFeed CrewAI tool catalog (1 credit per call).
+
+    Safe to attach without a token: each tool returns actionable
+    guidance instead of paying or raising when no credits are
+    available. None of these tools move funds.
+    """
+    return [
+        tensorfeed_whats_new_tool(token),
+        tensorfeed_routing_full_tool(token),
+        tensorfeed_compare_models_tool(token),
+        tensorfeed_cost_projection_tool(token),
+        tensorfeed_news_search_tool(token),
+        tensorfeed_provider_deepdive_tool(token),
+        tensorfeed_status_leaderboard_tool(token),
+    ]

{tensorfeed-2.0.0 → tensorfeed-2.1.0}/tensorfeed/langchain.py

@@ -11,7 +11,12 @@ Provides:
     * ``TensorFeedAttentionTool`` - tool wrapping ``/api/attention``
     * ``TensorFeedHarnessesTool`` - tool wrapping ``/api/harnesses``
     * ``TensorFeedNewsLoader``  - LangChain document loader for news articles
-    * ``tensorfeed_tools()``    - convenience: returns the full tool list
+    * ``tensorfeed_tools()``    - convenience: free tools, optionally premium
+    * ``tensorfeed_premium_tools()`` - the paid catalog (1 credit each)
+
+The premium tools never move funds. Called without a credit token they
+return a clear guidance string instead of paying or raising. Provisioning
+credits stays an explicit operator action; see ``_premium_tools``.
 
 Usage::
 
@@ -32,6 +37,7 @@ import json
 from typing import Any
 
 from .client import TensorFeed
+from ._premium_tools import DESCRIPTIONS, FORMATTERS, safe_call
 
 
 def _require_langchain() -> tuple[Any, Any]:
@@ -194,15 +200,184 @@ def TensorFeedHarnessesTool(token: str | None = None):
     )
 
 
-def tensorfeed_tools(token: str | None = None) -> list[Any]:
-    """Convenience: returns all TensorFeed LangChain tools."""
-    return [
+def tensorfeed_tools(
+    token: str | None = None,
+    *,
+    include_premium: bool = False,
+) -> list[Any]:
+    """Convenience: the TensorFeed LangChain tools.
+
+    Returns the five free tools by default. Pass
+    ``include_premium=True`` to also attach the paid catalog (1 credit
+    per call). The premium tools are safe to attach even without a
+    token: called with no credits they return guidance instead of
+    paying or raising, so an agent can still reason about them.
+
+    Args:
+        token: Optional bearer token for premium calls. Free tools
+            ignore it.
+        include_premium: Append the premium tools as well.
+    """
+    tools = [
         TensorFeedNewsTool(token),
         TensorFeedStatusTool(token),
         TensorFeedRoutingTool(token),
         TensorFeedAttentionTool(token),
         TensorFeedHarnessesTool(token),
     ]
+    if include_premium:
+        tools.extend(tensorfeed_premium_tools(token))
+    return tools
+
+
+# ── Premium tools (paid, 1 credit each, never auto-pay) ───────────────
+#
+# Each tool has an explicit typed signature so LangChain builds a clean
+# argument schema for the model. The call is routed through the shared
+# ``safe_call`` so the payment posture and result formatting are
+# identical to the CrewAI binding and tested once.
+
+
+def _premium_structured_tool(name: str, fn):
+    StructuredTool, _ = _require_langchain()
+    return StructuredTool.from_function(
+        func=fn, name=name, description=DESCRIPTIONS[name]
+    )
+
+
+def TensorFeedWhatsNewTool(token: str | None = None):
+    """Paid agent boot brief. 1 credit. Will not auto-pay."""
+
+    def _whats_new(days: int = 1, news_limit: int = 10) -> str:
+        return safe_call(
+            lambda: _client(token).whats_new(days=days, news_limit=news_limit),
+            FORMATTERS["tensorfeed_whats_new"],
+        )
+
+    return _premium_structured_tool("tensorfeed_whats_new", _whats_new)
+
+
+def TensorFeedRoutingFullTool(token: str | None = None):
+    """Paid full ranked routing. 1 credit. Will not auto-pay."""
+
+    def _routing(
+        task: str = "general",
+        budget: float | None = None,
+        top_n: int = 5,
+    ) -> str:
+        return safe_call(
+            lambda: _client(token).routing(task=task, budget=budget, top_n=top_n),
+            FORMATTERS["tensorfeed_routing"],
+        )
+
+    return _premium_structured_tool("tensorfeed_routing", _routing)
+
+
+def TensorFeedCompareModelsTool(token: str | None = None):
+    """Paid 2-5 model comparison. 1 credit. Will not auto-pay."""
+
+    def _compare(ids: str) -> str:
+        return safe_call(
+            lambda: _client(token).compare_models(ids=ids),
+            FORMATTERS["tensorfeed_compare_models"],
+        )
+
+    return _premium_structured_tool("tensorfeed_compare_models", _compare)
+
+
+def TensorFeedCostProjectionTool(token: str | None = None):
+    """Paid workload cost projection. 1 credit. Will not auto-pay."""
+
+    def _cost(
+        models: str,
+        input_tokens_per_day: float,
+        output_tokens_per_day: float,
+        horizon: str | None = None,
+    ) -> str:
+        return safe_call(
+            lambda: _client(token).cost_projection(
+                models=models,
+                input_tokens_per_day=input_tokens_per_day,
+                output_tokens_per_day=output_tokens_per_day,
+                horizon=horizon,
+            ),
+            FORMATTERS["tensorfeed_cost_projection"],
+        )
+
+    return _premium_structured_tool("tensorfeed_cost_projection", _cost)
+
+
+def TensorFeedNewsSearchTool(token: str | None = None):
+    """Paid full-text news search. 1 credit. Will not auto-pay."""
+
+    def _search(
+        q: str | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        provider: str | None = None,
+        category: str | None = None,
+        limit: int = 25,
+    ) -> str:
+        return safe_call(
+            lambda: _client(token).news_search(
+                q=q,
+                from_date=from_date,
+                to_date=to_date,
+                provider=provider,
+                category=category,
+                limit=limit,
+            ),
+            FORMATTERS["tensorfeed_news_search"],
+        )
+
+    return _premium_structured_tool("tensorfeed_news_search", _search)
+
+
+def TensorFeedProviderDeepDiveTool(token: str | None = None):
+    """Paid one-call provider profile. 1 credit. Will not auto-pay."""
+
+    def _deepdive(provider: str) -> str:
+        return safe_call(
+            lambda: _client(token).provider_deepdive(provider),
+            FORMATTERS["tensorfeed_provider_deepdive"],
+        )
+
+    return _premium_structured_tool("tensorfeed_provider_deepdive", _deepdive)
+
+
+def TensorFeedStatusLeaderboardTool(token: str | None = None):
+    """Paid 90-day uptime leaderboard. 1 credit. Will not auto-pay."""
+
+    def _leaderboard(
+        from_date: str | None = None,
+        to_date: str | None = None,
+    ) -> str:
+        return safe_call(
+            lambda: _client(token).status_leaderboard(
+                from_date=from_date, to_date=to_date
+            ),
+            FORMATTERS["tensorfeed_status_leaderboard"],
+        )
+
+    return _premium_structured_tool("tensorfeed_status_leaderboard", _leaderboard)
+
+
+def tensorfeed_premium_tools(token: str | None = None) -> list[Any]:
+    """The paid TensorFeed tool catalog (1 credit per call).
+
+    Safe to attach without a token: each tool returns actionable
+    guidance instead of paying or raising when no credits are
+    available. None of these tools move funds.
+    """
+    return [
+        TensorFeedWhatsNewTool(token),
+        TensorFeedRoutingFullTool(token),
+        TensorFeedCompareModelsTool(token),
+        TensorFeedCostProjectionTool(token),
+        TensorFeedNewsSearchTool(token),
+        TensorFeedProviderDeepDiveTool(token),
+        TensorFeedStatusLeaderboardTool(token),
+    ]
 
 
 # ── Document loader ───────────────────────────────────────────────

{tensorfeed-2.0.0 → tensorfeed-2.1.0}/tensorfeed.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tensorfeed
-Version: 2.0.0
-Summary: Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, agent payments via USDC on Base (optional web3 auto-send)
+Version: 2.1.0
+Summary: Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, LangChain/CrewAI tool factories, agent payments via USDC on Base (optional web3 auto-send)
 Author-email: "TensorFeed.ai" <feedback@tensorfeed.ai>
 License-Expression: MIT
 Project-URL: Homepage, https://tensorfeed.ai
@@ -197,6 +197,34 @@ print(tf.balance())
 rec = tf.routing(task="code")
 ```
 
+## Framework Tools (LangChain, CrewAI)
+
+Drop TensorFeed into an agent framework as ready-made tools.
+
+```bash
+pip install 'tensorfeed[langchain]'   # or 'tensorfeed[crewai]'
+```
+
+```python
+from tensorfeed.langchain import tensorfeed_tools, tensorfeed_premium_tools
+
+# Five free tools (news, status, attention, harnesses, routing preview)
+free = tensorfeed_tools()
+
+# Free plus the paid catalog (whats_new, full routing, compare models,
+# cost projection, news search, provider deep dive, status leaderboard)
+all_tools = tensorfeed_tools(token="YOUR_TOKEN", include_premium=True)
+
+# Just the paid catalog
+paid = tensorfeed_premium_tools(token="YOUR_TOKEN")
+```
+
+CrewAI is identical: `from tensorfeed.crewai import tensorfeed_tools, tensorfeed_premium_tools`.
+
+The default `tensorfeed_tools()` stays free-only and unchanged, so existing code keeps working. Premium is opt-in via `include_premium=True`.
+
+**Payment posture.** The premium tools never move funds. Attach them with or without a token: called without spendable credits they return a short, actionable guidance string (explaining that an operator provisions credits out of band) instead of paying or raising. There is no code path from a tool call to the wallet or the web3 signer. Credit purchases stay an explicit, per-action operator decision, by design. This is enforced in one shared module and covered by tests, including a static guard that fails if a future change introduces an autonomous-payment path.
+
 ## Error Handling
 
 ```python

{tensorfeed-2.0.0 → tensorfeed-2.1.0}/tensorfeed.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 README.md
 pyproject.toml
 tensorfeed/__init__.py
+tensorfeed/_premium_tools.py
 tensorfeed/client.py
 tensorfeed/crewai.py
 tensorfeed/langchain.py
@@ -10,4 +11,5 @@ tensorfeed.egg-info/PKG-INFO
 tensorfeed.egg-info/SOURCES.txt
 tensorfeed.egg-info/dependency_links.txt
 tensorfeed.egg-info/requires.txt
-tensorfeed.egg-info/top_level.txt
+tensorfeed.egg-info/top_level.txt
+tests/test_premium_tools.py

tensorfeed-2.1.0/tests/test_premium_tools.py

@@ -0,0 +1,213 @@
+"""Tests for the shared premium-tool plumbing.
+
+Network-free. Covers the safe_call behavior matrix, the formatters,
+the framework bindings (skipped if the framework is not installed),
+and a static guard that the premium-tool path can never reach the
+wallet or the web3 signer.
+
+Run from sdk/python::
+
+    python -m unittest discover -s tests -t .
+"""
+
+from __future__ import annotations
+
+import inspect
+import unittest
+
+from tensorfeed import PaymentRequired, RateLimited, TensorFeed, TensorFeedError
+from tensorfeed import _premium_tools as pt
+
+
+class SafeCallBehavior(unittest.TestCase):
+    def test_payment_required_returns_guidance_not_raise(self):
+        def boom():
+            raise PaymentRequired(402, {})
+
+        out = pt.safe_call(boom, lambda r: "unreachable")
+        self.assertIn("will not", out.lower())
+        self.assertIn("credit", out.lower())
+        # The whole point: no exception escapes a tool call.
+        self.assertIsInstance(out, str)
+
+    def test_payment_required_appends_credits_hint(self):
+        def boom():
+            raise PaymentRequired(402, {"credits_required": 2})
+
+        out = pt.safe_call(boom, lambda r: "unreachable")
+        self.assertIn("2 credit", out)
+
+    def test_missing_token_value_error_returns_guidance(self):
+        def boom():
+            raise ValueError("whats_new() requires a token.")
+
+        out = pt.safe_call(boom, lambda r: "unreachable")
+        self.assertEqual(out, pt.PREMIUM_PAYMENT_GUIDANCE)
+
+    def test_rate_limited_returns_backoff_message(self):
+        def boom():
+            raise RateLimited(429, {})
+
+        out = pt.safe_call(boom, lambda r: "unreachable")
+        self.assertIn("rate limit", out.lower())
+
+    def test_other_api_error_is_concise(self):
+        def boom():
+            raise TensorFeedError(500, {"error": "kaboom"})
+
+        out = pt.safe_call(boom, lambda r: "unreachable")
+        self.assertIn("500", out)
+        self.assertNotIn("Traceback", out)
+
+    def test_success_runs_formatter_and_billing_footer(self):
+        result = {"value": 1, "billing": {"credits_charged": 1, "balance": 49}}
+        out = pt.safe_call(lambda: result, lambda r: f"value={r['value']}")
+        self.assertIn("value=1", out)
+        self.assertIn("1 credit(s) charged", out)
+        self.assertIn("49 remaining", out)
+
+    def test_formatter_exception_is_contained(self):
+        def bad_formatter(r):
+            raise KeyError("missing")
+
+        out = pt.safe_call(lambda: {"a": 1}, bad_formatter)
+        self.assertIn("unexpected shape", out)
+        self.assertIn("'a'", out)  # surfaced the real keys
+
+
+class GuidanceContract(unittest.TestCase):
+    def test_guidance_states_no_autonomous_payment(self):
+        g = pt.PREMIUM_PAYMENT_GUIDANCE.lower()
+        self.assertIn("will not", g)
+        self.assertTrue("move any funds" in g or "move funds" in g)
+        self.assertIn("operator", g)
+
+
+class NoAutonomousPaymentStaticGuard(unittest.TestCase):
+    """A future edit must not be able to wire payment into a tool call.
+
+    The premium-tool module is the single chokepoint for every paid
+    tool. If it never references the web3 signer or the purchase path,
+    no tool can autonomously spend. This asserts that invariant at the
+    source level so it fails loudly if someone changes it.
+    """
+
+    def test_premium_tools_source_has_no_payment_path(self):
+        src = inspect.getsource(pt)
+        for forbidden in ("web3_signer", "purchase_credits", "private_key"):
+            self.assertNotIn(forbidden, src)
+
+
+class Formatters(unittest.TestCase):
+    def test_each_formatter_smoke(self):
+        samples = {
+            "tensorfeed_whats_new": {
+                "window": {"days": 1},
+                "pricing": {
+                    "changes": [{"model": "X", "field": "blended", "from": 1, "to": 2}],
+                    "new_models": [],
+                    "removed_models": [],
+                },
+                "status": {"incidents": [{"provider": "openai", "state": "down"}]},
+                "news": [{"title": "T", "source": "S"}],
+                "summary": {"total": 1},
+            },
+            "tensorfeed_routing": {
+                "recommendations": [
+                    {"rank": 1, "model": {"name": "Opus", "provider": "anthropic"},
+                     "composite_score": 0.91}
+                ]
+            },
+            "tensorfeed_compare_models": {
+                "models": [{"name": "A", "pricing": {"inputPrice": 1, "outputPrice": 2},
+                            "context_window": 200000}],
+                "rankings": {"cheapest_blended": "A"},
+            },
+            "tensorfeed_cost_projection": {
+                "projections": [{"model": "A", "monthly": 12.5}],
+                "ranked_cheapest_monthly": [{"model": "A"}],
+            },
+            "tensorfeed_news_search": {
+                "matched": 3,
+                "results": [{"title": "T", "source": "S", "published_at": "2026-05-17",
+                             "url": "u"}],
+            },
+            "tensorfeed_provider_deepdive": {
+                "provider": "anthropic",
+                "status": {"status": "operational"},
+                "models": [{"name": "Opus", "tier": "flagship", "context_window": 200000}],
+                "recent_news_count": 2,
+                "recent_news": [{"title": "T", "source": "S"}],
+                "agent_traffic_24h": 100,
+            },
+            "tensorfeed_status_leaderboard": {
+                "entries": [{"rank": 1, "provider": "Anthropic", "uptime_pct": 99.9,
+                             "incident_count": 0, "mttr_minutes": 0}]
+            },
+        }
+        for name, fmt in pt.FORMATTERS.items():
+            with self.subTest(tool=name):
+                text = fmt(samples[name])
+                self.assertIsInstance(text, str)
+                self.assertTrue(text.strip())
+
+    def test_status_leaderboard_handles_no_data(self):
+        out = pt.format_status_leaderboard({"entries": [], "error": "no_data"})
+        self.assertIn("no_data", out)
+
+    def test_names_and_descriptions_and_formatters_align(self):
+        self.assertEqual(set(pt.DESCRIPTIONS), set(pt.FORMATTERS))
+        self.assertEqual(set(pt.PREMIUM_TOOL_NAMES), set(pt.DESCRIPTIONS))
+        for name, desc in pt.DESCRIPTIONS.items():
+            self.assertIn("1 credit", desc, msg=name)
+
+
+class ClientIntegrationOffline(unittest.TestCase):
+    """End-to-end through the real client, no network.
+
+    A tokenless client raises ValueError from _require_token BEFORE any
+    HTTP call, so routing it through safe_call exercises the real
+    no-credit path offline and proves no network and no payment occur.
+    """
+
+    def test_tokenless_premium_call_yields_guidance_no_network(self):
+        tf = TensorFeed()  # no token
+        out = pt.safe_call(
+            lambda: tf.whats_new(), pt.FORMATTERS["tensorfeed_whats_new"]
+        )
+        self.assertEqual(out, pt.PREMIUM_PAYMENT_GUIDANCE)
+
+
+class FrameworkBindings(unittest.TestCase):
+    def test_langchain_premium_tools_build(self):
+        try:
+            from tensorfeed.langchain import tensorfeed_premium_tools, tensorfeed_tools
+        except Exception as e:  # pragma: no cover
+            self.skipTest(f"langchain import failed: {e}")
+        try:
+            tools = tensorfeed_premium_tools(token=None)
+        except ImportError:
+            self.skipTest("langchain_core not installed")
+        names = {t.name for t in tools}
+        self.assertEqual(names, set(pt.DESCRIPTIONS))
+        # Default tool list stays free-only (backward compatible).
+        free = tensorfeed_tools()
+        self.assertTrue(all(t.name not in pt.DESCRIPTIONS for t in free))
+        combined = {t.name for t in tensorfeed_tools(include_premium=True)}
+        self.assertTrue(set(pt.DESCRIPTIONS).issubset(combined))
+
+    def test_crewai_premium_tools_build(self):
+        try:
+            from tensorfeed.crewai import tensorfeed_premium_tools
+        except Exception as e:  # pragma: no cover
+            self.skipTest(f"crewai import failed: {e}")
+        try:
+            tools = tensorfeed_premium_tools(token=None)
+        except ImportError:
+            self.skipTest("crewai not installed")
+        names = {t.name for t in tools}
+        self.assertEqual(names, set(pt.DESCRIPTIONS))
+
+
+if __name__ == "__main__":
+    unittest.main()