nemoflow 0.1.0__tar.gz

nemoflow-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Environment
+.env
+
+# IDE
+.vscode/
+.idea/
+
+# Docker
+docker-compose.override.yml
+
+# OS
+.DS_Store

nemoflow-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: nemoflow
+Version: 0.1.0
+Summary: Reliability oracle for AI agents — pick the right tool from the start
+Project-URL: Homepage, https://nemoflow.ai
+Project-URL: Documentation, https://api.nemoflow.ai/docs
+Project-URL: Repository, https://github.com/netvistamedia/nemoflow
+Author-email: NemoFlow <hello@nemoflow.ai>
+License-Expression: MIT
+Keywords: agents,ai,api,llm,reliability,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# NemoFlow Python SDK
+
+Python client for the [NemoFlow API](https://api.nemoflow.ai) — the reliability oracle for AI agents.
+
+## Installation
+
+```bash
+pip install nemoflow
+```
+
+## Quick start — one line of code
+
+The `guard` function wraps any tool call with automatic reliability checking:
+
+```python
+from nemoflow import NemoFlowClient, guard
+
+client = NemoFlowClient(api_key="nf_live_...")
+
+# Wrap any tool call — assesses before, reports after, automatically
+result = guard(client, "https://api.openai.com/v1/chat/completions",
+               lambda: openai.chat.completions.create(model="gpt-4", messages=[...]))
+```
+
+That's it. NemoFlow will:
+1. Check the tool's reliability score before calling
+2. Execute the tool call
+3. Report success/failure back (building the data moat)
+4. Classify errors automatically
+
+## Auto-fallback
+
+When a tool fails, automatically try alternatives:
+
+```python
+result = guard(
+    client,
+    "https://api.openai.com/v1/chat/completions",
+    lambda: openai.chat.completions.create(model="gpt-4", messages=msgs),
+    fallbacks=[
+        ("https://api.anthropic.com/v1/messages",
+         lambda: anthropic.messages.create(model="claude-sonnet-4-20250514", messages=msgs)),
+        ("https://api.groq.com/openai/v1/chat/completions",
+         lambda: groq.chat.completions.create(model="llama-3.3-70b", messages=msgs)),
+    ],
+    min_score=50,  # Skip tools scoring below 50
+)
+```
+
+## Decorator
+
+```python
+from nemoflow import NemoFlowClient, nemoflow_guard
+
+client = NemoFlowClient(api_key="nf_live_...")
+
+@nemoflow_guard(client, "https://api.stripe.com/v1/charges")
+def charge_customer(amount, currency):
+    return stripe.Charge.create(amount=amount, currency=currency)
+
+# Every call is now automatically assessed + reported
+charge_customer(1000, "usd")
+```
+
+## Journey tracking
+
+Report fallback patterns to power hidden gem discovery:
+
+```python
+# First attempt fails
+client.report("https://api.sendgrid.com/v3/mail/send",
+    success=False, error_category="rate_limit",
+    session_id="session-123", attempt_number=1)
+
+# Fallback succeeds
+client.report("https://api.resend.com/emails",
+    success=True, latency_ms=180,
+    session_id="session-123", attempt_number=2,
+    previous_tool="https://api.sendgrid.com/v3/mail/send")
+```
+
+## Discovery
+
+Find hidden gems and fallback chains based on real agent behavior:
+
+```python
+# Tools that shine as fallbacks
+gems = client.discover_hidden_gems(category="email")
+
+# What to try when SendGrid fails
+chain = client.discover_fallback_chain("https://api.sendgrid.com/v3/mail/send")
+```
+
+## Direct API usage
+
+```python
+from nemoflow import NemoFlowClient
+
+client = NemoFlowClient(api_key="nf_live_...")
+
+# Assess
+result = client.assess("https://api.openai.com/v1/chat/completions",
+                        context="customer support chatbot")
+print(result["reliability_score"])      # 89.0
+print(result["predicted_failure_risk"]) # "low"
+print(result["common_pitfalls"])        # ["timeout (8% of failures)"]
+print(result["top_alternatives"])       # [{"tool": "...", "score": 90}]
+
+# Report
+client.report("https://api.openai.com/v1/chat/completions",
+              success=True, latency_ms=2500)
+
+client.close()
+```
+
+## Async support
+
+`AsyncNemoFlowClient` has the same interface — all methods are `async`.
+
+```python
+from nemoflow import AsyncNemoFlowClient
+
+async with AsyncNemoFlowClient(api_key="nf_live_...") as client:
+    result = await client.assess("https://api.openai.com/v1/chat/completions")
+```

nemoflow-0.1.0/README.md

@@ -0,0 +1,125 @@
+# NemoFlow Python SDK
+
+Python client for the [NemoFlow API](https://api.nemoflow.ai) — the reliability oracle for AI agents.
+
+## Installation
+
+```bash
+pip install nemoflow
+```
+
+## Quick start — one line of code
+
+The `guard` function wraps any tool call with automatic reliability checking:
+
+```python
+from nemoflow import NemoFlowClient, guard
+
+client = NemoFlowClient(api_key="nf_live_...")
+
+# Wrap any tool call — assesses before, reports after, automatically
+result = guard(client, "https://api.openai.com/v1/chat/completions",
+               lambda: openai.chat.completions.create(model="gpt-4", messages=[...]))
+```
+
+That's it. NemoFlow will:
+1. Check the tool's reliability score before calling
+2. Execute the tool call
+3. Report success/failure back (building the data moat)
+4. Classify errors automatically
+
+## Auto-fallback
+
+When a tool fails, automatically try alternatives:
+
+```python
+result = guard(
+    client,
+    "https://api.openai.com/v1/chat/completions",
+    lambda: openai.chat.completions.create(model="gpt-4", messages=msgs),
+    fallbacks=[
+        ("https://api.anthropic.com/v1/messages",
+         lambda: anthropic.messages.create(model="claude-sonnet-4-20250514", messages=msgs)),
+        ("https://api.groq.com/openai/v1/chat/completions",
+         lambda: groq.chat.completions.create(model="llama-3.3-70b", messages=msgs)),
+    ],
+    min_score=50,  # Skip tools scoring below 50
+)
+```
+
+## Decorator
+
+```python
+from nemoflow import NemoFlowClient, nemoflow_guard
+
+client = NemoFlowClient(api_key="nf_live_...")
+
+@nemoflow_guard(client, "https://api.stripe.com/v1/charges")
+def charge_customer(amount, currency):
+    return stripe.Charge.create(amount=amount, currency=currency)
+
+# Every call is now automatically assessed + reported
+charge_customer(1000, "usd")
+```
+
+## Journey tracking
+
+Report fallback patterns to power hidden gem discovery:
+
+```python
+# First attempt fails
+client.report("https://api.sendgrid.com/v3/mail/send",
+    success=False, error_category="rate_limit",
+    session_id="session-123", attempt_number=1)
+
+# Fallback succeeds
+client.report("https://api.resend.com/emails",
+    success=True, latency_ms=180,
+    session_id="session-123", attempt_number=2,
+    previous_tool="https://api.sendgrid.com/v3/mail/send")
+```
+
+## Discovery
+
+Find hidden gems and fallback chains based on real agent behavior:
+
+```python
+# Tools that shine as fallbacks
+gems = client.discover_hidden_gems(category="email")
+
+# What to try when SendGrid fails
+chain = client.discover_fallback_chain("https://api.sendgrid.com/v3/mail/send")
+```
+
+## Direct API usage
+
+```python
+from nemoflow import NemoFlowClient
+
+client = NemoFlowClient(api_key="nf_live_...")
+
+# Assess
+result = client.assess("https://api.openai.com/v1/chat/completions",
+                        context="customer support chatbot")
+print(result["reliability_score"])      # 89.0
+print(result["predicted_failure_risk"]) # "low"
+print(result["common_pitfalls"])        # ["timeout (8% of failures)"]
+print(result["top_alternatives"])       # [{"tool": "...", "score": 90}]
+
+# Report
+client.report("https://api.openai.com/v1/chat/completions",
+              success=True, latency_ms=2500)
+
+client.close()
+```
+
+## Async support
+
+`AsyncNemoFlowClient` has the same interface — all methods are `async`.
+
+```python
+from nemoflow import AsyncNemoFlowClient
+
+async with AsyncNemoFlowClient(api_key="nf_live_...") as client:
+    result = await client.assess("https://api.openai.com/v1/chat/completions")
+```

nemoflow-0.1.0/nemoflow/__init__.py

@@ -0,0 +1,5 @@
+from .client import NemoFlowClient, AsyncNemoFlowClient
+from .guard import guard, nemoflow_guard
+
+__all__ = ["NemoFlowClient", "AsyncNemoFlowClient", "guard", "nemoflow_guard"]
+__version__ = "0.1.0"

nemoflow-0.1.0/nemoflow/client.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+_DEFAULT_BASE_URL = "https://api.nemoflow.ai"
+_DEFAULT_TIMEOUT = 30.0
+
+
+class NemoFlowClient:
+    """Synchronous client for the NemoFlow API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={"X-Api-Key": self._api_key},
+            timeout=timeout,
+        )
+
+    # -- endpoints -----------------------------------------------------------
+
+    def assess(
+        self,
+        tool_identifier: str,
+        context: str = "",
+        sample_payload: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Assess a tool's reliability and get recommendations."""
+        body: dict[str, Any] = {
+            "tool_identifier": tool_identifier,
+            "context": context,
+        }
+        if sample_payload is not None:
+            body["sample_payload"] = sample_payload
+
+        resp = self._client.post("/v1/assess", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    def report(
+        self,
+        tool_identifier: str,
+        success: bool,
+        error_category: Optional[str] = None,
+        latency_ms: Optional[int] = None,
+        context: str = "",
+        session_id: Optional[str] = None,
+        attempt_number: Optional[int] = None,
+        previous_tool: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Report a tool execution outcome.
+
+        For journey tracking, include session_id, attempt_number, and
+        previous_tool when retrying after a failure. This data powers
+        the hidden gems and fallback chain features.
+        """
+        body: dict[str, Any] = {
+            "tool_identifier": tool_identifier,
+            "success": success,
+            "context": context,
+        }
+        if error_category is not None:
+            body["error_category"] = error_category
+        if latency_ms is not None:
+            body["latency_ms"] = latency_ms
+        if session_id is not None:
+            body["session_id"] = session_id
+        if attempt_number is not None:
+            body["attempt_number"] = attempt_number
+        if previous_tool is not None:
+            body["previous_tool"] = previous_tool
+
+        resp = self._client.post("/v1/report", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    def discover_hidden_gems(
+        self, category: Optional[str] = None, limit: int = 10
+    ) -> dict[str, Any]:
+        """Find hidden gem tools that shine as fallbacks."""
+        params: dict[str, Any] = {"limit": limit}
+        if category:
+            params["category"] = category
+        resp = self._client.get("/v1/discover/hidden-gems", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    def discover_fallback_chain(
+        self, tool_identifier: str, limit: int = 5
+    ) -> dict[str, Any]:
+        """Get the best fallback tools when this tool fails."""
+        resp = self._client.get(
+            "/v1/discover/fallback-chain",
+            params={"tool_identifier": tool_identifier, "limit": limit},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> NemoFlowClient:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncNemoFlowClient:
+    """Asynchronous client for the NemoFlow API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"X-Api-Key": self._api_key},
+            timeout=timeout,
+        )
+
+    # -- endpoints -----------------------------------------------------------
+
+    async def assess(
+        self,
+        tool_identifier: str,
+        context: str = "",
+        sample_payload: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Assess a tool's reliability and get recommendations."""
+        body: dict[str, Any] = {
+            "tool_identifier": tool_identifier,
+            "context": context,
+        }
+        if sample_payload is not None:
+            body["sample_payload"] = sample_payload
+
+        resp = await self._client.post("/v1/assess", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def report(
+        self,
+        tool_identifier: str,
+        success: bool,
+        error_category: Optional[str] = None,
+        latency_ms: Optional[int] = None,
+        context: str = "",
+        session_id: Optional[str] = None,
+        attempt_number: Optional[int] = None,
+        previous_tool: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Report a tool execution outcome."""
+        body: dict[str, Any] = {
+            "tool_identifier": tool_identifier,
+            "success": success,
+            "context": context,
+        }
+        if error_category is not None:
+            body["error_category"] = error_category
+        if latency_ms is not None:
+            body["latency_ms"] = latency_ms
+        if session_id is not None:
+            body["session_id"] = session_id
+        if attempt_number is not None:
+            body["attempt_number"] = attempt_number
+        if previous_tool is not None:
+            body["previous_tool"] = previous_tool
+
+        resp = await self._client.post("/v1/report", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def discover_hidden_gems(
+        self, category: Optional[str] = None, limit: int = 10
+    ) -> dict[str, Any]:
+        """Find hidden gem tools that shine as fallbacks."""
+        params: dict[str, Any] = {"limit": limit}
+        if category:
+            params["category"] = category
+        resp = await self._client.get("/v1/discover/hidden-gems", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def discover_fallback_chain(
+        self, tool_identifier: str, limit: int = 5
+    ) -> dict[str, Any]:
+        """Get the best fallback tools when this tool fails."""
+        resp = await self._client.get(
+            "/v1/discover/fallback-chain",
+            params={"tool_identifier": tool_identifier, "limit": limit},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- lifecycle -----------------------------------------------------------
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncNemoFlowClient:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()

nemoflow-0.1.0/nemoflow/guard.py

@@ -0,0 +1,176 @@
+"""NemoFlow Guard — one-line reliability wrapper for tool calls.
+
+Usage:
+    from nemoflow import NemoFlowClient, guard
+
+    client = NemoFlowClient("nf_live_...")
+
+    # Wrap any tool call — assess before, report after, auto-fallback
+    result = guard(client, "https://api.openai.com/v1/chat/completions",
+                   lambda: openai.chat.completions.create(...))
+
+    # With fallbacks — tries alternatives if primary scores too low
+    result = guard(client, "https://api.openai.com/v1/chat/completions",
+                   lambda: openai.chat.completions.create(...),
+                   fallbacks=[
+                       ("https://api.anthropic.com/v1/messages",
+                        lambda: anthropic.messages.create(...)),
+                   ])
+
+    # As a decorator
+    @nemoflow_guard(client, "https://api.stripe.com/v1/charges")
+    def charge_customer(amount, currency):
+        return stripe.Charge.create(amount=amount, currency=currency)
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from functools import wraps
+from typing import Any, Callable, TypeVar
+
+from nemoflow.client import NemoFlowClient
+
+T = TypeVar("T")
+
+
+def guard(
+    client: NemoFlowClient,
+    tool_identifier: str,
+    fn: Callable[[], T],
+    *,
+    context: str = "",
+    min_score: float = 0.0,
+    fallbacks: list[tuple[str, Callable[[], T]]] | None = None,
+) -> T:
+    """Execute a tool call with NemoFlow reliability guard.
+
+    1. Assesses the tool's reliability score
+    2. If score < min_score and fallbacks exist, tries the best-scoring fallback
+    3. Executes the tool call
+    4. Reports success/failure back to NemoFlow
+    5. On failure with fallbacks, automatically tries the next option
+
+    Args:
+        client: NemoFlowClient instance
+        tool_identifier: The tool's API identifier
+        fn: The actual tool call to execute (as a callable)
+        context: Workflow context for context-bucketed scoring
+        min_score: Minimum reliability score to proceed (0-100). Default 0 = always try.
+        fallbacks: List of (tool_identifier, callable) pairs to try on failure
+
+    Returns:
+        The result of the successful tool call
+
+    Raises:
+        The exception from the last failed tool call if all options are exhausted
+    """
+    session_id = uuid.uuid4().hex[:16]
+    all_tools = [(tool_identifier, fn)] + (fallbacks or [])
+
+    last_error = None
+
+    for attempt, (ident, call) in enumerate(all_tools, start=1):
+        # Assess
+        try:
+            assessment = client.assess(ident, context=context)
+            score = assessment.get("reliability_score", 100)
+        except Exception:
+            score = 100  # If assess fails, don't block the tool call
+
+        # Skip if score too low and we have more options
+        if score < min_score and attempt < len(all_tools):
+            client.report(
+                ident, success=False, error_category="skipped_low_score",
+                context=context, session_id=session_id,
+                attempt_number=attempt,
+                previous_tool=all_tools[attempt - 2][0] if attempt > 1 else None,
+            )
+            continue
+
+        # Execute
+        start = time.perf_counter()
+        try:
+            result = call()
+            latency_ms = int((time.perf_counter() - start) * 1000)
+
+            # Report success
+            client.report(
+                ident, success=True, latency_ms=latency_ms,
+                context=context, session_id=session_id,
+                attempt_number=attempt,
+                previous_tool=all_tools[attempt - 2][0] if attempt > 1 else None,
+            )
+            return result
+
+        except Exception as e:
+            latency_ms = int((time.perf_counter() - start) * 1000)
+            last_error = e
+
+            # Classify error
+            error_category = _classify_error(e)
+
+            # Report failure
+            client.report(
+                ident, success=False, error_category=error_category,
+                latency_ms=latency_ms, context=context,
+                session_id=session_id, attempt_number=attempt,
+                previous_tool=all_tools[attempt - 2][0] if attempt > 1 else None,
+            )
+
+            # If no more fallbacks, raise
+            if attempt >= len(all_tools):
+                raise
+
+    # Should not reach here, but just in case
+    raise last_error  # type: ignore
+
+
+def nemoflow_guard(
+    client: NemoFlowClient,
+    tool_identifier: str,
+    *,
+    context: str = "",
+    min_score: float = 0.0,
+):
+    """Decorator version of guard.
+
+    Usage:
+        @nemoflow_guard(client, "https://api.stripe.com/v1/charges")
+        def charge(amount, currency):
+            return stripe.Charge.create(amount=amount, currency=currency)
+    """
+    def decorator(fn: Callable[..., T]) -> Callable[..., T]:
+        @wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            return guard(
+                client, tool_identifier,
+                lambda: fn(*args, **kwargs),
+                context=context, min_score=min_score,
+            )
+        return wrapper
+    return decorator
+
+
+def _classify_error(error: Exception) -> str:
+    """Best-effort classification of an exception into NemoFlow error categories."""
+    name = type(error).__name__.lower()
+    message = str(error).lower()
+
+    if "timeout" in name or "timeout" in message or "timed out" in message:
+        return "timeout"
+    if "ratelimit" in name or "rate" in message and "limit" in message or "429" in message or "too many" in message:
+        return "rate_limit"
+    if "auth" in name or "unauthorized" in message or "403" in message or "401" in message:
+        return "auth_failure"
+    if "validation" in name or "invalid" in message or "422" in message:
+        return "validation_error"
+    if "notfound" in name or "not found" in message or "404" in message:
+        return "not_found"
+    if "permission" in name or "forbidden" in message:
+        return "permission_denied"
+    if "connect" in name or "connection" in message or "dns" in message:
+        return "connection_error"
+
+    return "server_error"

nemoflow-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nemoflow"
+version = "0.1.0"
+description = "Reliability oracle for AI agents — pick the right tool from the start"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    {name = "NemoFlow", email = "hello@nemoflow.ai"},
+]
+keywords = ["ai", "agents", "reliability", "tools", "llm", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.urls]
+Homepage = "https://nemoflow.ai"
+Documentation = "https://api.nemoflow.ai/docs"
+Repository = "https://github.com/netvistamedia/nemoflow"