tuningengines-cli 0.3.6 → 0.4.2

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

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .client import TuningClient
+from .mcp import make_agent_langchain_tools, make_langchain_tools
+
+
+def create_tuning_langgraph_agent(
+    client: TuningClient,
+    *,
+    model: str = "auto",
+    prompt: str | None = None,
+    server_names: set[str] | None = None,
+    tool_names: set[str] | None = None,
+    agent_names: list[str] | set[str] | None = None,
+    agent_descriptions: dict[str, str] | None = None,
+    checkpointer: Any | None = None,
+    interrupt_before: list[str] | None = None,
+    **agent_kwargs: Any,
+) -> Any:
+    """Create a LangGraph ReAct agent backed by Tuning Engines.
+
+    This gives callers a real agent loop while Tuning Engines remains the
+    governed gateway for models, MCP tool execution, RBAC, policy, audit,
+    request capture, and token economics.
+    """
+
+    try:
+        from langchain_openai import ChatOpenAI
+        from langgraph.prebuilt import create_react_agent
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError("Install tuning-agents[langgraph] to use the LangGraph adapter") from exc
+
+    llm = ChatOpenAI(
+        model=model,
+        api_key=client.api_key,
+        base_url=client.inference_url,
+        timeout=client.timeout,
+    )
+    tools = make_langchain_tools(client, server_names=server_names, tool_names=tool_names)
+    if agent_names:
+        tools.extend(
+            make_agent_langchain_tools(
+                client,
+                agent_names=agent_names,
+                descriptions=agent_descriptions,
+            )
+        )
+
+    kwargs: dict[str, Any] = dict(agent_kwargs)
+    if checkpointer is not None:
+        kwargs["checkpointer"] = checkpointer
+    if interrupt_before is not None:
+        kwargs["interrupt_before"] = interrupt_before
+    if prompt is not None:
+        kwargs["prompt"] = prompt
+
+    span_id = client.trace.start(
+        "langgraph.agent.create",
+        {"model": model, "tools": [getattr(tool, "name", None) for tool in tools]},
+    )
+    try:
+        agent = create_react_agent(llm, tools, **kwargs)
+        client.trace.finish(span_id, {"tool_count": len(tools)})
+        return agent
+    except Exception as exc:
+        client.trace.error(span_id, exc)
+        raise
+
+
+def invoke_with_trace(
+    client: TuningClient,
+    agent: Any,
+    messages: list[dict[str, str]],
+    *,
+    thread_id: str | None = None,
+    **config: Any,
+) -> Any:
+    span_id = client.trace.start("langgraph.agent.invoke", {"thread_id": thread_id})
+    try:
+        runnable_config = dict(config)
+        if thread_id:
+            runnable_config.setdefault("configurable", {})["thread_id"] = thread_id
+        result = agent.invoke({"messages": messages}, runnable_config or None)
+        client.trace.finish(span_id, {"thread_id": thread_id})
+        return result
+    except Exception as exc:
+        client.trace.error(span_id, exc)
+        raise
+
+
+def invoke_and_flush_trace(
+    client: TuningClient,
+    agent: Any,
+    messages: list[dict[str, str]],
+    *,
+    thread_id: str | None = None,
+    name: str | None = None,
+    **config: Any,
+) -> Any:
+    try:
+        result = invoke_with_trace(client, agent, messages, thread_id=thread_id, **config)
+        client.flush_trace(name=name, runtime="langgraph", status="succeeded", metadata={"thread_id": thread_id})
+        return result
+    except Exception:
+        client.flush_trace(name=name, runtime="langgraph", status="failed", metadata={"thread_id": thread_id})
+        raise

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

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field, create_model
+
+if TYPE_CHECKING:
+    from .client import TuningClient
+
+
+def normalize_mcp_tools(payload: Any) -> list[dict[str, Any]]:
+    """Normalize common MCP tool-list response shapes.
+
+    The proxy may return `{"tools": [...]}` or group tools by server. This
+    function keeps the adapter tolerant while preserving server attribution.
+    """
+
+    if isinstance(payload, dict) and isinstance(payload.get("tools"), list):
+        return [dict(tool) for tool in payload["tools"]]
+    if isinstance(payload, list):
+        return [dict(tool) for tool in payload]
+
+    tools: list[dict[str, Any]] = []
+    if isinstance(payload, dict):
+        for server in payload.get("servers", []) or []:
+            server_name = server.get("name") or server.get("server_name")
+            for tool in server.get("tools", []) or []:
+                merged = dict(tool)
+                merged.setdefault("server_name", server_name)
+                tools.append(merged)
+    return tools
+
+
+def pydantic_model_from_json_schema(name: str, schema: Mapping[str, Any] | None) -> type[BaseModel]:
+    properties = dict((schema or {}).get("properties") or {})
+    required = set((schema or {}).get("required") or [])
+    fields: dict[str, tuple[Any, Any]] = {}
+
+    for field_name, spec in properties.items():
+        spec = spec or {}
+        annotation = _json_type_to_python(spec.get("type"))
+        default = ... if field_name in required else None
+        fields[field_name] = (
+            annotation,
+            Field(default, description=spec.get("description")),
+        )
+
+    if not fields:
+        fields["arguments"] = (
+            dict[str, Any],
+            Field(default_factory=dict, description="Tool arguments as a JSON object."),
+        )
+
+    return create_model(name, **fields)
+
+
+def make_langchain_tools(
+    client: TuningClient,
+    *,
+    server_names: set[str] | None = None,
+    tool_names: set[str] | None = None,
+) -> list[Any]:
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError("Install tuning-agents[langgraph] to build LangGraph tools") from exc
+
+    raw_tools = normalize_mcp_tools(client.list_mcp_tools())
+    tools: list[Any] = []
+    for raw in raw_tools:
+        server_name = raw.get("server_name") or raw.get("server") or raw.get("mcp_server")
+        tool_name = raw.get("name") or raw.get("tool_name")
+        if not server_name or not tool_name:
+            continue
+        if server_names and server_name not in server_names:
+            continue
+        if tool_names and tool_name not in tool_names:
+            continue
+
+        args_schema = pydantic_model_from_json_schema(
+            f"{_safe_identifier(server_name)}_{_safe_identifier(tool_name)}_Args",
+            raw.get("inputSchema") or raw.get("input_schema") or raw.get("schema"),
+        )
+
+        def _call(_server_name: str = server_name, _tool_name: str = tool_name, **kwargs: Any) -> Any:
+            if "arguments" in kwargs and len(kwargs) == 1 and isinstance(kwargs["arguments"], dict):
+                kwargs = kwargs["arguments"]
+            return client.call_mcp_tool(
+                server_name=_server_name,
+                tool_name=_tool_name,
+                arguments=kwargs,
+            )
+
+        tools.append(
+            StructuredTool.from_function(
+                func=_call,
+                name=f"{_safe_identifier(server_name)}__{_safe_identifier(tool_name)}",
+                description=raw.get("description") or f"Call {tool_name} on MCP server {server_name}.",
+                args_schema=args_schema,
+            )
+        )
+
+    return tools
+
+
+def make_agent_langchain_tools(
+    client: "TuningClient",
+    *,
+    agent_names: list[str] | set[str],
+    descriptions: Mapping[str, str] | None = None,
+) -> list[Any]:
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError("Install tuning-agents[langgraph] to build LangGraph tools") from exc
+
+    class AgentArgs(BaseModel):
+        message: str = Field(..., description="Task or message to send to the registered agent.")
+        context: dict[str, Any] = Field(default_factory=dict, description="Optional structured context.")
+
+    tools: list[Any] = []
+    for agent_name in agent_names:
+        safe_name = _safe_identifier(agent_name)
+
+        def _call(message: str, context: dict[str, Any] | None = None, _agent_name: str = agent_name) -> Any:
+            return client.call_agent(agent_name=_agent_name, message=message, context=context or {})
+
+        tools.append(
+            StructuredTool.from_function(
+                func=_call,
+                name=f"agent__{safe_name}",
+                description=(descriptions or {}).get(agent_name) or f"Delegate a full task to agent {agent_name}.",
+                args_schema=AgentArgs,
+            )
+        )
+    return tools
+
+
+def skill_tool_spec(
+    name: str,
+    *,
+    description: str | None = None,
+    parameters: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build an OpenAI tool spec for a registered skill.
+
+    Skills are enforced by the proxy orchestrator when their function name
+    matches the registered tenant/platform skill name. Unlike MCP and A2A
+    agents, this SDK does not invent a local execution endpoint for skills.
+    """
+
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description or f"Invoke the governed skill {name}.",
+            "parameters": parameters
+            or {
+                "type": "object",
+                "properties": {
+                    "input": {"type": "string", "description": "Input for the skill."},
+                    "context": {"type": "object", "description": "Optional structured context."},
+                },
+                "required": ["input"],
+            },
+        },
+    }
+
+
+def agent_tool_spec(
+    name: str,
+    *,
+    description: str | None = None,
+) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description or f"Delegate a full task to registered agent {name}.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "message": {"type": "string", "description": "Message or task for the agent."},
+                    "context": {"type": "object", "description": "Optional structured context."},
+                },
+                "required": ["message"],
+            },
+        },
+    }
+
+
+def _json_type_to_python(json_type: Any) -> Any:
+    if isinstance(json_type, list):
+        json_type = next((item for item in json_type if item != "null"), None)
+    return {
+        "string": str,
+        "integer": int,
+        "number": float,
+        "boolean": bool,
+        "array": list[Any],
+        "object": dict[str, Any],
+    }.get(json_type, Any)
+
+
+def _safe_identifier(value: str) -> str:
+    cleaned = "".join(ch if ch.isalnum() else "_" for ch in value)
+    return cleaned.strip("_") or "tool"

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

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .mcp import agent_tool_spec, skill_tool_spec
+
+
+@dataclass(slots=True)
+class ResourceManifest:
+    """Runtime-facing manifest for governed Tuning Engines resources.
+
+    Use this when the application knows which agents/skills should be exposed
+    to a run. The proxy still enforces RBAC/AGT using the tenant registry.
+    """
+
+    model: str = "auto"
+    agents: dict[str, str] = field(default_factory=dict)
+    skills: dict[str, str] = field(default_factory=dict)
+    extra_tools: list[dict[str, Any]] = field(default_factory=list)
+
+    def openai_tools(self) -> list[dict[str, Any]]:
+        tools = list(self.extra_tools)
+        tools.extend(agent_tool_spec(name, description=description) for name, description in self.agents.items())
+        tools.extend(skill_tool_spec(name, description=description) for name, description in self.skills.items())
+        return tools

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

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Any
+
+from .client import TuningClient
+
+
+@dataclass
+class AgentRunInput:
+    api_key: str
+    inference_url: str = "https://api.tuningengines.com/v1"
+    api_url: str = "https://app.tuningengines.com"
+    model: str = "auto"
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    tools: list[dict[str, Any]] | None = None
+    max_steps: int = 8
+
+
+@dataclass
+class AgentRunResult:
+    output: Any
+    trace: dict[str, Any]
+
+
+async def chat_completion_activity(payload: dict[str, Any]) -> dict[str, Any]:
+    client = _client_from_payload(payload)
+    response = client.chat(
+        model=payload["model"],
+        messages=payload["messages"],
+        tools=payload.get("tools"),
+        tool_choice=payload.get("tool_choice", "auto") if payload.get("tools") else None,
+    )
+    return response.model_dump(mode="json") if hasattr(response, "model_dump") else response
+
+
+async def mcp_tool_activity(payload: dict[str, Any]) -> dict[str, Any]:
+    client = _client_from_payload(payload)
+    result = await client.acall_mcp_tool(
+        server_name=payload["server_name"],
+        tool_name=payload["tool_name"],
+        arguments=payload.get("arguments") or {},
+    )
+    return {"result": result, "trace": client.trace.as_dict()}
+
+
+async def agent_message_activity(payload: dict[str, Any]) -> dict[str, Any]:
+    client = _client_from_payload(payload)
+    result = await client.acall_agent(
+        agent_name=payload["agent_name"],
+        message=payload["message"],
+        context=payload.get("context") or {},
+    )
+    return {"result": result, "trace": client.trace.as_dict()}
+
+
+def define_temporal_workflow() -> type[Any]:
+    """Return a Temporal workflow class without importing Temporal at module load.
+
+    Temporal workflow modules are replayed under deterministic constraints. This
+    factory keeps optional dependencies isolated for users who only need
+    LangGraph.
+    """
+
+    try:
+        from temporalio import workflow
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError("Install tuning-agents[temporal] to use the Temporal adapter") from exc
+
+    @workflow.defn
+    class TuningAgentWorkflow:
+        @workflow.run
+        async def run(self, request: AgentRunInput) -> AgentRunResult:
+            messages = list(request.messages)
+            trace_events: list[dict[str, Any]] = []
+
+            for step in range(request.max_steps):
+                llm = await workflow.execute_activity(
+                    chat_completion_activity,
+                    {
+                        "api_key": request.api_key,
+                        "api_url": request.api_url,
+                        "inference_url": request.inference_url,
+                        "model": request.model,
+                        "messages": messages,
+                        "tools": request.tools,
+                    },
+                    start_to_close_timeout=timedelta(minutes=5),
+                )
+                trace_events.extend(_events_from_activity(llm))
+                choice = (llm.get("choices") or [{}])[0]
+                message = choice.get("message") or {}
+                messages.append(message)
+
+                tool_calls = message.get("tool_calls") or []
+                if not tool_calls:
+                    return AgentRunResult(output=message, trace={"events": trace_events})
+
+                for tool_call in tool_calls:
+                    function = tool_call.get("function") or {}
+                    tool_call_name = function.get("name") or ""
+                    arguments = function.get("arguments") or {}
+                    if isinstance(arguments, str):
+                        arguments = json.loads(arguments or "{}")
+                    if tool_call_name.startswith("agent__"):
+                        agent_name = tool_call_name.removeprefix("agent__")
+                        tool_result = await workflow.execute_activity(
+                            agent_message_activity,
+                            {
+                                "api_key": request.api_key,
+                                "api_url": request.api_url,
+                                "inference_url": request.inference_url,
+                                "agent_name": agent_name,
+                                "message": arguments.get("message") or arguments.get("input") or "",
+                                "context": arguments.get("context") or {},
+                            },
+                            start_to_close_timeout=timedelta(minutes=2),
+                        )
+                    else:
+                        server_name, tool_name = _split_tool_name(tool_call_name)
+                        tool_result = await workflow.execute_activity(
+                            mcp_tool_activity,
+                            {
+                                "api_key": request.api_key,
+                                "api_url": request.api_url,
+                                "inference_url": request.inference_url,
+                                "server_name": server_name,
+                                "tool_name": tool_name,
+                                "arguments": arguments,
+                            },
+                            start_to_close_timeout=timedelta(minutes=5),
+                        )
+                    trace_events.extend(_events_from_activity(tool_result))
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call.get("id"),
+                            "content": str(tool_result.get("result")),
+                        }
+                    )
+
+            return AgentRunResult(
+                output={"role": "assistant", "content": "Max steps reached."},
+                trace={"events": trace_events},
+            )
+
+    return TuningAgentWorkflow
+
+
+def _client_from_payload(payload: dict[str, Any]) -> TuningClient:
+    return TuningClient(
+        api_key=payload["api_key"],
+        api_url=payload.get("api_url", "https://app.tuningengines.com"),
+        inference_url=payload.get("inference_url", "https://api.tuningengines.com/v1"),
+    )
+
+
+def _split_tool_name(name: str) -> tuple[str, str]:
+    if "__" in name:
+        return tuple(name.split("__", 1))  # type: ignore[return-value]
+    if "." in name:
+        return tuple(name.split(".", 1))  # type: ignore[return-value]
+    raise ValueError(f"Tool name must include server and tool, got {name!r}")
+
+
+def _events_from_activity(payload: Any) -> list[Any]:
+    if isinstance(payload, dict):
+        trace = payload.get("trace") or {}
+        return trace.get("events") or []
+    return []

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

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class TraceEvent:
+    id: str
+    type: str
+    status: str
+    at: float
+    parent_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class TraceRecorder:
+    """In-process trace collector for agent runs.
+
+    This captures the full SDK-side causal chain. Rails already records
+    gateway usage, request capture, audit, and token economics. Persist these
+    events in your app or forward them once a public trace-ingest endpoint is
+    added.
+    """
+
+    run_id: str = field(default_factory=lambda: f"run_{uuid.uuid4().hex}")
+    events: list[TraceEvent] = field(default_factory=list)
+
+    def start(self, event_type: str, metadata: dict[str, Any] | None = None, parent_id: str | None = None) -> str:
+        event_id = f"evt_{uuid.uuid4().hex}"
+        self.events.append(
+            TraceEvent(
+                id=event_id,
+                type=event_type,
+                status="started",
+                at=time.time(),
+                parent_id=parent_id,
+                metadata={"run_id": self.run_id, **(metadata or {})},
+            )
+        )
+        return event_id
+
+    def finish(self, event_id: str, metadata: dict[str, Any] | None = None) -> None:
+        self.events.append(
+            TraceEvent(
+                id=f"evt_{uuid.uuid4().hex}",
+                type="span.finish",
+                status="succeeded",
+                at=time.time(),
+                parent_id=event_id,
+                metadata={"run_id": self.run_id, **(metadata or {})},
+            )
+        )
+
+    def error(self, event_id: str, exc: BaseException) -> None:
+        self.events.append(
+            TraceEvent(
+                id=f"evt_{uuid.uuid4().hex}",
+                type="span.error",
+                status="failed",
+                at=time.time(),
+                parent_id=event_id,
+                metadata={
+                    "run_id": self.run_id,
+                    "error_type": exc.__class__.__name__,
+                    "error": str(exc),
+                },
+            )
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "events": [
+                {
+                    "id": event.id,
+                    "type": event.type,
+                    "status": event.status,
+                    "at": event.at,
+                    "parent_id": event.parent_id,
+                    "metadata": event.metadata,
+                }
+                for event in self.events
+            ],
+        }