tuningengines-cli 0.3.6 → 0.4.2

package/packages/tuning-agents/README.md

@@ -0,0 +1,168 @@
+# tuning-agents
+
+Governed agent runtime adapters for Tuning Engines.
+
+This package keeps orchestration outside Rails while making agent runtimes use
+Tuning Engines for the things it already does well:
+
+- OpenAI-compatible model access through the inference gateway
+- MCP tool discovery and execution through `/v1/mcp/tools*`
+- A2A tenant-agent dispatch through `/v1/agents/{name}/message`
+- Agent/skill OpenAI tool specs that line up with proxy RBAC and AGT policy
+- Registry/RBAC/governance enforcement at the gateway
+- Usage, request capture, auditability, and token economics
+- Client-side causal traces for LLM calls, MCP calls, LangGraph runs, and
+  Temporal activities
+
+## Install
+
+```bash
+pip install tuning-agents[langgraph]
+pip install tuning-agents[temporal]
+```
+
+From this repository:
+
+```bash
+pip install -e packages/tuning-agents[langgraph,temporal]
+```
+
+## LangGraph
+
+LangGraph provides the actual agent loop, checkpoints, memory, interrupts, and
+human-in-the-loop workflow. Tuning Engines remains the governed model/tool
+gateway.
+
+```python
+from langgraph.checkpoint.memory import InMemorySaver
+
+from tuning_agents import TuningClient
+from tuning_agents.langgraph import create_tuning_langgraph_agent, invoke_with_trace
+
+client = TuningClient(api_key="sk-te-...", inference_url="https://api.tuningengines.com/v1")
+
+agent = create_tuning_langgraph_agent(
+    client,
+    model="llama-3.3-70b-fp8",
+    agent_names=["billing-escalation"],
+    checkpointer=InMemorySaver(),
+    interrupt_before=["tools"],  # optional approval gate before tool execution
+)
+
+result = invoke_with_trace(
+    client,
+    agent,
+    [{"role": "user", "content": "Use the registry tools to summarize my latest jobs."}],
+    thread_id="customer-123",
+)
+
+print(result)
+print(client.trace.as_dict())
+
+# Store the runtime trace in Tuning Engines.
+client.flush_trace(name="ticket-triage", runtime="langgraph", status="succeeded")
+```
+
+The LangGraph adapter exposes two executable resource classes:
+
+- MCP tools discovered from the Tuning Engines proxy
+- Registered tenant agents passed via `agent_names`, executed through
+  `/v1/agents/{name}/message`
+
+Skills are different: they are governed prompt/workflow bundles represented as
+OpenAI tool specs. Use `ResourceManifest.openai_tools()` when you want the proxy
+to enforce skill access on a direct chat-completions call.
+
+```python
+from tuning_agents.resources import ResourceManifest
+
+manifest = ResourceManifest(
+    model="llama-3.3-70b-fp8",
+    agents={"billing-escalation": "Escalate complex billing issues."},
+    skills={"analytics": "Run the tenant analytics skill."},
+)
+
+resp = client.chat(
+    model=manifest.model,
+    messages=[{"role": "user", "content": "Analyze this ticket and escalate if needed."}],
+    tools=manifest.openai_tools(),
+)
+```
+
+## Temporal
+
+Temporal provides durable execution, retries, resume-after-crash, schedules, and
+workflow history. The provided workflow is intentionally small: each LLM turn and
+MCP tool call runs as an activity, so Temporal owns durability and Tuning Engines
+owns model/tool governance.
+
+```python
+from temporalio.client import Client
+from temporalio.worker import Worker
+
+from tuning_agents.temporal import (
+    AgentRunInput,
+    agent_message_activity,
+    chat_completion_activity,
+    define_temporal_workflow,
+    mcp_tool_activity,
+)
+
+TuningAgentWorkflow = define_temporal_workflow()
+
+async def main():
+    temporal = await Client.connect("localhost:7233")
+    worker = Worker(
+        temporal,
+        task_queue="tuning-agents",
+        workflows=[TuningAgentWorkflow],
+        activities=[chat_completion_activity, mcp_tool_activity, agent_message_activity],
+    )
+    await worker.run()
+```
+
+Start a run:
+
+```python
+handle = await temporal.start_workflow(
+    TuningAgentWorkflow.run,
+    AgentRunInput(
+        api_key="sk-te-...",
+        model="llama-3.3-70b-fp8",
+        messages=[{"role": "user", "content": "Check available tools and answer."}],
+    ),
+    id="agent-run-001",
+    task_queue="tuning-agents",
+)
+```
+
+## Trace Semantics
+
+This SDK captures the full client/runtime-side causal trace:
+
+- LangGraph agent creation/invocation
+- LLM calls
+- MCP tool discovery and execution
+- A2A agent dispatches
+- Temporal workflow activities
+- Errors and latency metadata
+
+Rails/proxy already capture the gateway side: inference usage, request capture,
+audit logs, policy decisions, token counts, and billing attribution. The SDK
+captures the runtime side and can persist it with:
+
+```python
+client.flush_trace(name="support-agent", runtime="langgraph", status="succeeded")
+```
+
+That sends events to `POST /api/v1/traces` using the same `TE_API_KEY` auth as
+the CLI/MCP server.
+
+## Why this exists
+
+The Rails app stays the control plane. This package gives customers a portable
+runtime layer:
+
+- LangGraph for agent loops, state, memory, interrupts, and checkpoints
+- Temporal for crash-proof durable execution
+- Tuning Engines for governance, registries, agents, skills, MCP, routing, usage, and economics

package/packages/tuning-agents/examples/langgraph_agent.py

@@ -0,0 +1,25 @@
+from langgraph.checkpoint.memory import InMemorySaver
+
+from tuning_agents import TuningClient
+from tuning_agents.langgraph import create_tuning_langgraph_agent, invoke_with_trace
+
+
+client = TuningClient()
+
+agent = create_tuning_langgraph_agent(
+    client,
+    model="llama-3.3-70b-fp8",
+    agent_names=["billing-escalation"],
+    checkpointer=InMemorySaver(),
+    interrupt_before=["tools"],
+)
+
+result = invoke_with_trace(
+    client,
+    agent,
+    [{"role": "user", "content": "List the available governed tools and summarize what you can do."}],
+    thread_id="demo-thread",
+)
+
+print(result)
+print(client.trace.as_dict())

package/packages/tuning-agents/examples/temporal_worker.py

@@ -0,0 +1,27 @@
+import asyncio
+
+from temporalio.client import Client
+from temporalio.worker import Worker
+
+from tuning_agents.temporal import (
+    agent_message_activity,
+    chat_completion_activity,
+    define_temporal_workflow,
+    mcp_tool_activity,
+)
+
+
+async def main() -> None:
+    temporal = await Client.connect("localhost:7233")
+    workflow = define_temporal_workflow()
+    worker = Worker(
+        temporal,
+        task_queue="tuning-agents",
+        workflows=[workflow],
+        activities=[chat_completion_activity, mcp_tool_activity, agent_message_activity],
+    )
+    await worker.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/packages/tuning-agents/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tuning-agents"
+version = "0.1.0"
+description = "Governed agent runtime adapters for Tuning Engines, LangGraph, Temporal, and MCP."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Tuning Engines" }]
+dependencies = [
+  "httpx>=0.27",
+  "openai>=1.40",
+  "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+langgraph = [
+  "langgraph>=0.2",
+  "langchain-openai>=0.1.20",
+  "langchain-core>=0.2.30",
+]
+temporal = [
+  "temporalio>=1.7",
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["tuning_agents"]
+
+[tool.ruff]
+line-length = 100

package/packages/tuning-agents/tests/test_mcp.py

@@ -0,0 +1,40 @@
+from tuning_agents.mcp import agent_tool_spec, normalize_mcp_tools, pydantic_model_from_json_schema, skill_tool_spec
+
+
+def test_normalize_flat_tools():
+    tools = normalize_mcp_tools({"tools": [{"name": "x", "server_name": "s"}]})
+
+    assert tools == [{"name": "x", "server_name": "s"}]
+
+
+def test_normalize_grouped_tools():
+    tools = normalize_mcp_tools({"servers": [{"name": "s", "tools": [{"name": "x"}]}]})
+
+    assert tools == [{"name": "x", "server_name": "s"}]
+
+
+def test_pydantic_model_from_json_schema():
+    model = pydantic_model_from_json_schema(
+        "Args",
+        {
+            "type": "object",
+            "required": ["query"],
+            "properties": {
+                "query": {"type": "string"},
+                "limit": {"type": "integer"},
+            },
+        },
+    )
+
+    parsed = model(query="hello", limit=3)
+
+    assert parsed.query == "hello"
+    assert parsed.limit == 3
+
+
+def test_agent_and_skill_tool_specs():
+    agent = agent_tool_spec("billing-escalation")
+    skill = skill_tool_spec("analytics")
+
+    assert agent["function"]["name"] == "billing-escalation"
+    assert skill["function"]["name"] == "analytics"

package/packages/tuning-agents/tests/test_trace.py

@@ -0,0 +1,14 @@
+from tuning_agents.trace import TraceRecorder
+
+
+def test_trace_recorder_lifecycle():
+    trace = TraceRecorder(run_id="run_test")
+    span = trace.start("unit", {"ok": True})
+    trace.finish(span, {"duration_ms": 1})
+
+    data = trace.as_dict()
+
+    assert data["run_id"] == "run_test"
+    assert len(data["events"]) == 2
+    assert data["events"][0]["metadata"]["ok"] is True
+    assert data["events"][1]["parent_id"] == span

package/packages/tuning-agents/tuning_agents/__init__.py

@@ -0,0 +1,11 @@
+from .trace import TraceEvent, TraceRecorder
+
+__all__ = ["TuningClient", "TraceEvent", "TraceRecorder"]
+
+
+def __getattr__(name: str):
+    if name == "TuningClient":
+        from .client import TuningClient
+
+        return TuningClient
+    raise AttributeError(name)

package/packages/tuning-agents/tuning_agents/client.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+from openai import OpenAI
+
+from .trace import TraceRecorder
+
+
+class TuningError(RuntimeError):
+    pass
+
+
+@dataclass(slots=True)
+class TuningClient:
+    """Small client for Tuning Engines control-plane and inference APIs.
+
+    The API key can be a long-lived inference key (`sk-te-...`) when talking
+    directly to the proxy, or a platform API token when using `/api/v1/*`.
+    """
+
+    api_key: str | None = None
+    api_url: str = "https://app.tuningengines.com"
+    inference_url: str = "https://api.tuningengines.com/v1"
+    timeout: float = 60.0
+    user_agent: str = "tuning-agents/0.1.0"
+    trace: TraceRecorder = field(default_factory=TraceRecorder)
+
+    def __post_init__(self) -> None:
+        self.api_key = self.api_key or os.getenv("TE_API_KEY")
+        if not self.api_key:
+            raise ValueError("api_key is required or TE_API_KEY must be set")
+        self.api_url = self.api_url.rstrip("/")
+        self.inference_url = self.inference_url.rstrip("/")
+
+    @property
+    def openai(self) -> OpenAI:
+        return OpenAI(api_key=self.api_key, base_url=self.inference_url, timeout=self.timeout)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        base_url: str | None = None,
+        trace_type: str = "http",
+    ) -> Any:
+        url = f"{(base_url or self.api_url).rstrip('/')}/{path.lstrip('/')}"
+        span_id = self.trace.start(trace_type, {"method": method, "url": url})
+        started = time.perf_counter()
+        try:
+            with httpx.Client(timeout=self.timeout, headers=self._headers()) as client:
+                response = client.request(method, url, json=json)
+            payload = self._parse_response(response)
+            self.trace.finish(
+                span_id,
+                {
+                    "status_code": response.status_code,
+                    "duration_ms": round((time.perf_counter() - started) * 1000, 2),
+                },
+            )
+            return payload
+        except Exception as exc:
+            self.trace.error(span_id, exc)
+            raise
+
+    async def arequest(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        base_url: str | None = None,
+        trace_type: str = "http",
+    ) -> Any:
+        url = f"{(base_url or self.api_url).rstrip('/')}/{path.lstrip('/')}"
+        span_id = self.trace.start(trace_type, {"method": method, "url": url})
+        started = time.perf_counter()
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout, headers=self._headers()) as client:
+                response = await client.request(method, url, json=json)
+            payload = self._parse_response(response)
+            self.trace.finish(
+                span_id,
+                {
+                    "status_code": response.status_code,
+                    "duration_ms": round((time.perf_counter() - started) * 1000, 2),
+                },
+            )
+            return payload
+        except Exception as exc:
+            self.trace.error(span_id, exc)
+            raise
+
+    def chat(self, *, model: str, messages: list[dict[str, Any]], **kwargs: Any) -> Any:
+        span_id = self.trace.start("llm", {"model": model})
+        try:
+            clean_kwargs = {key: value for key, value in kwargs.items() if value is not None}
+            response = self.openai.chat.completions.create(model=model, messages=messages, **clean_kwargs)
+            usage = getattr(response, "usage", None)
+            self.trace.finish(
+                span_id,
+                {
+                    "model": getattr(response, "model", model),
+                    "usage": usage.model_dump() if hasattr(usage, "model_dump") else usage,
+                },
+            )
+            return response
+        except Exception as exc:
+            self.trace.error(span_id, exc)
+            raise
+
+    def list_models(self) -> Any:
+        return self.request("GET", "/api/v1/inference/models", trace_type="control")
+
+    def list_training_agents(
+        self,
+        *,
+        category: str | None = None,
+        include_disabled: bool = False,
+    ) -> Any:
+        params = []
+        if category:
+            params.append(f"category={category}")
+        if include_disabled:
+            params.append("include_disabled=true")
+        query = f"?{'&'.join(params)}" if params else ""
+        return self.request("GET", f"/api/v1/agents{query}", trace_type="control")
+
+    def list_usage(self, *, model: str | None = None, limit: int | None = None) -> Any:
+        params = []
+        if model:
+            params.append(f"model={model}")
+        if limit:
+            params.append(f"limit={limit}")
+        query = f"?{'&'.join(params)}" if params else ""
+        return self.request("GET", f"/api/v1/inference/usage{query}", trace_type="control")
+
+    def bulk_import_resources(
+        self,
+        *,
+        target_type: str,
+        rows: list[Mapping[str, Any]],
+        dry_run: bool = True,
+    ) -> Any:
+        return self.request(
+            "POST",
+            "/api/v1/bulk_imports",
+            json={"target_type": target_type, "rows": rows, "dry_run": dry_run},
+            trace_type="control",
+        )
+
+    def flush_trace(
+        self,
+        *,
+        name: str | None = None,
+        runtime: str = "custom",
+        status: str = "running",
+        metadata: Mapping[str, Any] | None = None,
+    ) -> Any:
+        trace = self.trace.as_dict()
+        return self.request(
+            "POST",
+            "/api/v1/traces",
+            json={
+                "run_id": trace["run_id"],
+                "name": name,
+                "runtime": runtime,
+                "status": status,
+                "metadata": dict(metadata or {}),
+                "events": trace["events"],
+            },
+            trace_type="control",
+        )
+
+    def call_agent(
+        self,
+        *,
+        agent_name: str,
+        message: str,
+        context: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return self.request(
+            "POST",
+            f"/v1/agents/{agent_name}/message",
+            base_url=self.inference_url.removesuffix("/v1"),
+            json={"message": message, "context": dict(context or {})},
+            trace_type="agent",
+        )
+
+    async def acall_agent(
+        self,
+        *,
+        agent_name: str,
+        message: str,
+        context: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return await self.arequest(
+            "POST",
+            f"/v1/agents/{agent_name}/message",
+            base_url=self.inference_url.removesuffix("/v1"),
+            json={"message": message, "context": dict(context or {})},
+            trace_type="agent",
+        )
+
+    def list_mcp_tools(self) -> Any:
+        return self.request("GET", "/v1/mcp/tools", base_url=self.inference_url.removesuffix("/v1"), trace_type="mcp")
+
+    def call_mcp_tool(
+        self,
+        *,
+        server_name: str,
+        tool_name: str,
+        arguments: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return self.request(
+            "POST",
+            "/v1/mcp/tools/call",
+            base_url=self.inference_url.removesuffix("/v1"),
+            json={
+                "server_name": server_name,
+                "tool_name": tool_name,
+                "arguments": dict(arguments or {}),
+            },
+            trace_type="mcp",
+        )
+
+    async def acall_mcp_tool(
+        self,
+        *,
+        server_name: str,
+        tool_name: str,
+        arguments: Mapping[str, Any] | None = None,
+    ) -> Any:
+        return await self.arequest(
+            "POST",
+            "/v1/mcp/tools/call",
+            base_url=self.inference_url.removesuffix("/v1"),
+            json={
+                "server_name": server_name,
+                "tool_name": tool_name,
+                "arguments": dict(arguments or {}),
+            },
+            trace_type="mcp",
+        )
+
+    def new_run_id(self, prefix: str = "run") -> str:
+        return f"{prefix}_{uuid.uuid4().hex}"
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": self.user_agent,
+        }
+
+    @staticmethod
+    def _parse_response(response: httpx.Response) -> Any:
+        text = response.text
+        try:
+            payload = response.json() if text else {}
+        except ValueError:
+            payload = text
+        if response.status_code >= 400:
+            message = payload.get("error") if isinstance(payload, dict) else payload
+            raise TuningError(f"Tuning Engines API error {response.status_code}: {message}")
+        return payload