api-operator 0.9.0__py3-none-any.whl

api_operator/adapters/yaml_spec.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class ParameterSpec:
+    type: str = "string"
+    required: bool = False
+    default: Any = None
+
+
+@dataclass
+class ToolSpec:
+    name: str
+    description: str
+    method: str
+    path: str
+    parameters: dict[str, ParameterSpec] = field(default_factory=dict)
+    body: dict[str, Any] | None = None
+    query: dict[str, str] | None = None
+    dangerous: bool = False
+    requires_ability: str | None = None
+    host: str = "central"  # central | tenant
+    tenant_param: str = "subdomain"
+
+
+@dataclass
+class AdapterSpec:
+    name: str
+    description: str
+    base_url: str
+    system_prompt: str
+    tools: list[ToolSpec]
+    auth_type: str = "bearer"
+    auth_header: str = "Authorization"
+    token_env: str | None = None
+
+
+def load_adapter_spec(path: str | Path) -> AdapterSpec:
+    file_path = Path(path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"Adapter config not found: {file_path}")
+
+    raw = yaml.safe_load(file_path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError("Adapter YAML must be a mapping")
+
+    auth = raw.get("auth") or {}
+    tools: list[ToolSpec] = []
+    for item in raw.get("tools") or []:
+        if not isinstance(item, dict):
+            continue
+        params: dict[str, ParameterSpec] = {}
+        raw_params = item.get("parameters") or {}
+        if isinstance(raw_params, dict):
+            for pname, pspec in raw_params.items():
+                if isinstance(pspec, dict):
+                    params[pname] = ParameterSpec(
+                        type=str(pspec.get("type", "string")),
+                        required=bool(pspec.get("required", False)),
+                        default=pspec.get("default"),
+                    )
+                else:
+                    params[pname] = ParameterSpec(required=bool(pspec))
+
+        tools.append(
+            ToolSpec(
+                name=str(item["name"]),
+                description=str(item.get("description", item["name"])),
+                method=str(item.get("method", "GET")).upper(),
+                path=str(item["path"]),
+                parameters=params,
+                body=item.get("body"),
+                query=item.get("query"),
+                dangerous=bool(item.get("dangerous", False)),
+                requires_ability=item.get("requires_ability"),
+                host=str(item.get("host", "central")),
+                tenant_param=str(item.get("tenant_param", "subdomain")),
+            )
+        )
+
+    return AdapterSpec(
+        name=str(raw.get("name", file_path.stem)),
+        description=str(raw.get("description", "")),
+        base_url=str(raw.get("base_url", "")).rstrip("/"),
+        system_prompt=str(raw.get("system_prompt") or _default_prompt(raw)),
+        tools=tools,
+        auth_type=str(auth.get("type", "bearer")),
+        auth_header=str(auth.get("header", "Authorization")),
+        token_env=auth.get("env_token"),
+    )
+
+
+def save_adapter_spec(spec: AdapterSpec, path: str | Path) -> None:
+    file_path = Path(path)
+    payload: dict[str, Any] = {
+        "name": spec.name,
+        "description": spec.description,
+        "base_url": spec.base_url,
+        "auth": {"type": spec.auth_type, "header": spec.auth_header},
+        "system_prompt": spec.system_prompt,
+        "tools": [],
+    }
+    if spec.token_env:
+        payload["auth"]["env_token"] = spec.token_env
+
+    for tool in spec.tools:
+        entry: dict[str, Any] = {
+            "name": tool.name,
+            "description": tool.description,
+            "method": tool.method,
+            "path": tool.path,
+        }
+        if tool.host != "central":
+            entry["host"] = tool.host
+            entry["tenant_param"] = tool.tenant_param
+        if tool.dangerous:
+            entry["dangerous"] = True
+        if tool.requires_ability:
+            entry["requires_ability"] = tool.requires_ability
+        if tool.parameters:
+            entry["parameters"] = {
+                name: {
+                    "type": param.type,
+                    "required": param.required,
+                    **({"default": param.default} if param.default is not None else {}),
+                }
+                for name, param in tool.parameters.items()
+            }
+        if tool.body:
+            entry["body"] = tool.body
+        if tool.query:
+            entry["query"] = tool.query
+        payload["tools"].append(entry)
+
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_text(
+        yaml.safe_dump(payload, sort_keys=False, allow_unicode=True),
+        encoding="utf-8",
+    )
+
+
+def _default_prompt(raw: dict[str, Any]) -> str:
+    name = raw.get("name", "project")
+    return (
+        f"You are API Operator for {name}. "
+        "Use registered tools only. Confirm dangerous actions. "
+        "Reply in the user's language."
+    )

api_operator/core/agent.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from api_operator.adapters.base import Adapter
+from api_operator.core.config import Settings
+from api_operator.core.executor import ToolExecutor
+from api_operator.core.guardrails import Guardrails
+from api_operator.core.memory import Session, SessionStore
+from api_operator.core.planner import Planner
+from api_operator.core.planner_openai import build_planner
+from api_operator.tools.base import ToolRegistry
+
+
+@dataclass
+class AgentResponse:
+    session_id: str
+    message: str
+    status: str = "ok"  # ok | confirm | error
+    tool: str | None = None
+    tool_result: dict[str, Any] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Agent:
+    def __init__(
+        self,
+        adapter: Adapter,
+        settings: Settings | None = None,
+        planner: Planner | None = None,
+        sessions: SessionStore | None = None,
+    ) -> None:
+        self.settings = settings or Settings()
+        self.adapter = adapter
+        self.registry: ToolRegistry = adapter.build_registry()
+        self.guardrails = Guardrails(
+            require_confirm_dangerous=self.settings.require_confirm_dangerous
+        )
+        self.executor = ToolExecutor(self.guardrails)
+        self.planner = planner or build_planner(self.settings)
+        self.sessions = sessions or SessionStore()
+
+    async def chat(
+        self,
+        message: str,
+        session_id: str | None = None,
+        abilities: list[str] | None = None,
+        auto_confirm: bool = False,
+    ) -> AgentResponse:
+        session = self.sessions.get_or_create(session_id, self.adapter.name)
+        session.add("user", message)
+
+        if session.pending_confirmation and not auto_confirm:
+            if self.guardrails.is_confirmation(message):
+                pending = session.pending_confirmation
+                session.pending_confirmation = None
+                result, error = await self.executor.execute(
+                    self.registry,
+                    pending["tool_name"],
+                    pending["tool_args"],
+                    abilities=abilities,
+                )
+                return self._finalize_tool(session, pending["tool_name"], result, error)
+
+            if self.guardrails.is_cancellation(message):
+                session.pending_confirmation = None
+                reply = "Cancelled. No changes were made."
+                session.add("assistant", reply, status="ok")
+                return AgentResponse(session_id=session.id, message=reply, status="ok")
+
+        plan = await self.planner.plan(
+            message=message,
+            registry=self.registry,
+            history=session.history(),
+            system_prompt=self.adapter.system_prompt(),
+        )
+
+        if plan.type == "respond":
+            session.add("assistant", plan.content, status="ok")
+            return AgentResponse(session_id=session.id, message=plan.content, status="ok")
+
+        if plan.type == "clarify":
+            session.add("assistant", plan.content, status="ok")
+            return AgentResponse(session_id=session.id, message=plan.content, status="ok")
+
+        if plan.type != "tool" or not plan.tool_name:
+            reply = "Could not determine an action."
+            session.add("assistant", reply, status="error")
+            return AgentResponse(session_id=session.id, message=reply, status="error")
+
+        tool = self.registry.get(plan.tool_name)
+        if tool is None:
+            reply = f"Tool not found: {plan.tool_name}"
+            session.add("assistant", reply, status="error")
+            return AgentResponse(session_id=session.id, message=reply, status="error")
+
+        if self.guardrails.needs_confirmation(tool) and not auto_confirm:
+            session.pending_confirmation = {
+                "tool_name": plan.tool_name,
+                "tool_args": plan.tool_args or {},
+            }
+            confirm_msg = self.executor.confirmation_message(tool, plan.tool_args or {})
+            session.add("assistant", confirm_msg, status="confirm")
+            return AgentResponse(
+                session_id=session.id,
+                message=confirm_msg,
+                status="confirm",
+                tool=plan.tool_name,
+                metadata={"arguments": plan.tool_args or {}},
+            )
+
+        result, error = await self.executor.execute(
+            self.registry,
+            plan.tool_name,
+            plan.tool_args,
+            abilities=abilities,
+        )
+        return self._finalize_tool(session, plan.tool_name, result, error)
+
+    def _finalize_tool(
+        self,
+        session: Session,
+        tool_name: str,
+        result: Any,
+        error: str | None,
+    ) -> AgentResponse:
+        if error:
+            session.add("assistant", error, status="error", tool=tool_name)
+            return AgentResponse(
+                session_id=session.id,
+                message=error,
+                status="error",
+                tool=tool_name,
+            )
+
+        payload = result.to_dict() if result else {"ok": False}
+        if payload.get("ok"):
+            reply = f"{tool_name} succeeded: {payload.get('data')}"
+            session.add("assistant", reply, status="ok", tool=tool_name)
+            return AgentResponse(
+                session_id=session.id,
+                message=reply,
+                status="ok",
+                tool=tool_name,
+                tool_result=payload,
+            )
+
+        err = payload.get("error", "Tool failed.")
+        session.add("assistant", err, status="error", tool=tool_name)
+        return AgentResponse(
+            session_id=session.id,
+            message=str(err),
+            status="error",
+            tool=tool_name,
+            tool_result=payload,
+        )
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        return self.registry.schemas()

api_operator/core/config.py

@@ -0,0 +1,18 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="api_operator_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    host: str = "127.0.0.1"
+    port: int = 8100
+    default_adapter: str = "mock"
+    planner: str = "auto"  # auto | mock | openai
+    openai_api_key: str | None = None
+    openai_model: str = "gpt-4o-mini"
+    require_confirm_dangerous: bool = True
+    log_tool_calls: bool = True

api_operator/core/executor.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+from api_operator.core.guardrails import Guardrails
+from api_operator.tools.base import Tool, ToolRegistry, ToolResult
+
+
+class ToolExecutor:
+    def __init__(self, guardrails: Guardrails | None = None) -> None:
+        self.guardrails = guardrails or Guardrails()
+
+    async def execute(
+        self,
+        registry: ToolRegistry,
+        tool_name: str,
+        arguments: dict[str, Any] | None,
+        abilities: list[str] | None = None,
+    ) -> tuple[ToolResult | None, str | None]:
+        tool = registry.get(tool_name)
+        if tool is None:
+            return None, f"Unknown tool: {tool_name}"
+
+        permission_error = self.guardrails.check_ability(tool, abilities)
+        if permission_error:
+            return None, permission_error
+
+        args = arguments or {}
+        missing = self.guardrails.missing_parameters(tool, args)
+        if missing:
+            return None, f"Missing required parameters: {', '.join(missing)}"
+
+        result = await tool.run(**args)
+        return result, None
+
+    def confirmation_message(self, tool: Tool, arguments: dict[str, Any]) -> str:
+        rendered = ", ".join(f"{k}={v!r}" for k, v in arguments.items())
+        return f"Confirm {tool.name}({rendered})? Reply yes to proceed or no to cancel."

api_operator/core/guardrails.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from api_operator.tools.base import Tool
+
+
+class Guardrails:
+    def __init__(self, require_confirm_dangerous: bool = True) -> None:
+        self.require_confirm_dangerous = require_confirm_dangerous
+
+    def check_ability(self, tool: Tool, abilities: list[str] | None) -> str | None:
+        if tool.requires_ability is None:
+            return None
+        if abilities is None:
+            return None
+        if tool.requires_ability not in abilities:
+            return (
+                f"Permission denied: tool '{tool.name}' requires "
+                f"ability '{tool.requires_ability}'."
+            )
+        return None
+
+    def missing_parameters(self, tool: Tool, arguments: dict[str, Any]) -> list[str]:
+        missing: list[str] = []
+        for name in tool.required:
+            value = arguments.get(name)
+            if value is None or (isinstance(value, str) and not value.strip()):
+                missing.append(name)
+        return missing
+
+    def needs_confirmation(self, tool: Tool) -> bool:
+        return self.require_confirm_dangerous and tool.dangerous
+
+    @staticmethod
+    def is_confirmation(message: str) -> bool:
+        normalized = message.strip().lower()
+        return normalized in {
+            "yes",
+            "y",
+            "confirm",
+            "ok",
+            "okay",
+            "نعم",
+            "أكد",
+            "اكد",
+            "موافق",
+        }
+
+    @staticmethod
+    def is_cancellation(message: str) -> bool:
+        normalized = message.strip().lower()
+        return normalized in {"no", "n", "cancel", "stop", "لا", "الغ", "إلغاء", "الغاء"}

api_operator/core/memory.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class Message:
+    role: str
+    content: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Session:
+    id: str
+    adapter: str
+    messages: list[Message] = field(default_factory=list)
+    context: dict[str, Any] = field(default_factory=dict)
+    pending_confirmation: dict[str, Any] | None = None
+
+    def add(self, role: str, content: str, **metadata: Any) -> None:
+        self.messages.append(Message(role=role, content=content, metadata=metadata))
+
+    def history(self, limit: int = 20) -> list[dict[str, str]]:
+        return [{"role": m.role, "content": m.content} for m in self.messages[-limit:]]
+
+
+class SessionStore:
+    def __init__(self) -> None:
+        self._sessions: dict[str, Session] = {}
+
+    def create(self, adapter: str, session_id: str | None = None) -> Session:
+        sid = session_id or str(uuid4())
+        session = Session(id=sid, adapter=adapter)
+        self._sessions[sid] = session
+        return session
+
+    def get(self, session_id: str) -> Session | None:
+        return self._sessions.get(session_id)
+
+    def get_or_create(self, session_id: str | None, adapter: str) -> Session:
+        if session_id and session_id in self._sessions:
+            return self._sessions[session_id]
+        return self.create(adapter=adapter, session_id=session_id)

api_operator/core/planner.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from api_operator.tools.base import ToolRegistry
+
+
+@dataclass
+class PlanStep:
+    type: str  # respond | tool | clarify
+    content: str = ""
+    tool_name: str | None = None
+    tool_args: dict[str, Any] | None = None
+
+
+class Planner(Protocol):
+    async def plan(
+        self,
+        message: str,
+        registry: ToolRegistry,
+        history: list[dict[str, str]],
+        system_prompt: str,
+    ) -> PlanStep: ...
+
+
+class MockPlanner:
+    """Rule-based planner for offline demos and tests (no LLM required)."""
+
+    async def plan(
+        self,
+        message: str,
+        registry: ToolRegistry,
+        history: list[dict[str, str]],
+        system_prompt: str,
+    ) -> PlanStep:
+        text = message.strip()
+        lower = text.lower()
+
+        if "help" in lower or "مساعدة" in text or lower.strip() == "tools":
+            names = ", ".join(registry.names())
+            return PlanStep(
+                type="respond",
+                content=(
+                    "I can run these tools: "
+                    f"{names}. Try: 'list workspaces', 'create workspace Acme subdomain acme', "
+                    "'invite admin@acme.com to acme', 'provision link Riyadh Jeddah 500'."
+                ),
+            )
+
+        if _wants_create_workspace(lower):
+            args = _extract_workspace_args(text)
+            if args.get("name") and args.get("subdomain") and registry.get("create_workspace"):
+                return PlanStep(
+                    type="tool",
+                    tool_name="create_workspace",
+                    tool_args=args,
+                )
+            return PlanStep(
+                type="clarify",
+                content="Please provide workspace name and subdomain (e.g. name Acme, subdomain acme).",
+            )
+
+        if _wants_invite(lower, text):
+            tool_name = "invite_member" if registry.get("invite_member") else "invite_team_member"
+            if registry.get(tool_name):
+                args = _extract_invite_args(text)
+                if args.get("email"):
+                    subdomain = args.get("subdomain") or "acme"
+                    return PlanStep(
+                        type="tool",
+                        tool_name=tool_name,
+                        tool_args={
+                            "subdomain": subdomain,
+                            "email": args["email"],
+                            "role": args.get("role", "member"),
+                        },
+                    )
+                return PlanStep(type="clarify", content="Which email should I invite?")
+
+        if _wants_provision_link(lower):
+            args = _extract_link_args(text)
+            if args.get("site_a") and args.get("site_b") and registry.get("provision_link"):
+                return PlanStep(type="tool", tool_name="provision_link", tool_args=args)
+
+        if _wants_list_connections(lower, text) and registry.get("list_connections"):
+            return PlanStep(type="tool", tool_name="list_connections", tool_args={})
+
+        if _wants_list_workspaces(lower, text) and registry.get("list_workspaces"):
+            return PlanStep(type="tool", tool_name="list_workspaces", tool_args={})
+
+        return PlanStep(
+            type="respond",
+            content=(
+                "I did not map that request to a tool. Say 'help' to see examples, or be explicit "
+                "(e.g. 'list workspaces', 'create workspace Acme subdomain acme')."
+            ),
+        )
+
+
+def _wants_create_workspace(lower: str) -> bool:
+    return (
+        "create workspace" in lower
+        or "new workspace" in lower
+        or "أنشئ workspace" in lower
+        or "انشئ workspace" in lower
+    )
+
+
+def _wants_invite(lower: str, text: str) -> bool:
+    return "invite" in lower or "ادع" in lower or "دعوة" in text
+
+
+def _wants_provision_link(lower: str) -> bool:
+    return "provision link" in lower or ("provision" in lower and "link" in lower)
+
+
+def _wants_list_connections(lower: str, text: str) -> bool:
+    if not ("connection" in lower or "link" in lower or "اتصال" in text or "رابط" in text):
+        return False
+    return any(word in lower for word in ("list", "show", "display")) or "اعرض" in text
+
+
+def _wants_list_workspaces(lower: str, text: str) -> bool:
+    if "workspace" not in lower and "workspace" not in text:
+        return False
+    if _wants_create_workspace(lower):
+        return False
+    return (
+        "list workspace" in lower
+        or "list workspaces" in lower
+        or "show workspace" in lower
+        or "show workspaces" in lower
+        or lower.strip() == "workspaces"
+        or "ورّيني" in text
+        or "اعرض" in text
+    )
+
+
+def _extract_workspace_args(text: str) -> dict[str, Any]:
+    args: dict[str, Any] = {}
+    lower = text.lower()
+    if "subdomain" in lower:
+        parts = lower.split("subdomain", 1)[1].strip().split()
+        if parts:
+            args["subdomain"] = parts[0].strip(",.")
+    if "name" in lower:
+        segment = text.split("name", 1)[1]
+        if "subdomain" in segment.lower():
+            segment = segment.split("subdomain", 1)[0]
+        args["name"] = segment.strip().strip(",.")
+    tokens = text.replace(",", " ").split()
+    for idx, token in enumerate(tokens):
+        if token.lower() == "workspace" and idx + 1 < len(tokens):
+            maybe_name = tokens[idx + 1]
+            if maybe_name.lower() not in {"subdomain", "named", "on"}:
+                args.setdefault("name", maybe_name)
+        if token.lower() == "subdomain" and idx + 1 < len(tokens):
+            args["subdomain"] = tokens[idx + 1].strip(".,")
+    return args
+
+
+def _extract_invite_args(text: str) -> dict[str, Any]:
+    args: dict[str, Any] = {}
+    for token in text.replace(",", " ").split():
+        if "@" in token:
+            args["email"] = token.strip(".,")
+    lower = text.lower()
+    if " to " in lower:
+        subdomain = lower.split(" to ", 1)[1].strip().split()[0]
+        args["subdomain"] = subdomain.strip(".,")
+    for token in text.split():
+        if token.lower() in {"admin", "member"}:
+            args["role"] = token.lower()
+    return args
+
+
+def _extract_link_args(text: str) -> dict[str, Any]:
+    args: dict[str, Any] = {}
+    lower = text.lower()
+    if "provision" in lower and "link" in lower:
+        tail = text.lower().split("link", 1)[1].strip()
+        parts = tail.split()
+        if len(parts) >= 2:
+            args["site_a"] = parts[0].capitalize()
+            args["site_b"] = parts[1].capitalize()
+        if len(parts) >= 3 and parts[2].isdigit():
+            args["bandwidth_mbps"] = int(parts[2])
+    return args