api-operator 0.9.0__py3-none-any.whl

api_operator/__init__.py

@@ -0,0 +1,8 @@
+"""API Operator — standalone AI operator with pluggable adapters."""
+
+from api_operator.core.agent import Agent, AgentResponse
+from api_operator.core.config import Settings
+from api_operator.tools.base import Tool, ToolRegistry
+
+__all__ = ["Agent", "AgentResponse", "Settings", "Tool", "ToolRegistry"]
+__version__ = "0.9.0"

api_operator/adapters/__init__.py

@@ -0,0 +1 @@
+

api_operator/adapters/base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from api_operator.tools.base import ToolRegistry
+
+
+class Adapter(ABC):
+    name: str
+    description: str
+
+    @abstractmethod
+    def build_registry(self) -> ToolRegistry:
+        raise NotImplementedError
+
+    @abstractmethod
+    def system_prompt(self) -> str:
+        raise NotImplementedError
+
+    def auth_context(self) -> dict[str, Any]:
+        return {}
+
+    def docs_paths(self) -> list[str]:
+        return []

api_operator/adapters/mock.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import Any
+
+from api_operator.adapters.base import Adapter
+from api_operator.tools.base import Tool, ToolRegistry, ToolResult
+
+
+class _MockStore:
+    workspaces: dict[str, dict[str, Any]] = {}
+    invitations: list[dict[str, Any]] = []
+    connections: dict[str, dict[str, Any]] = {}
+
+
+def reset_mock_store() -> None:
+    _MockStore.workspaces.clear()
+    _MockStore.invitations.clear()
+    _MockStore.connections.clear()
+
+
+class MockAdapter(Adapter):
+    name = "mock"
+    description = "In-memory demo adapter for SaaS + connectivity scenarios"
+
+    def build_registry(self) -> ToolRegistry:
+        registry = ToolRegistry()
+        registry.register(
+            Tool(
+                name="list_workspaces",
+                description="List all mock workspaces",
+                handler=self._list_workspaces,
+                parameters={},
+            )
+        )
+        registry.register(
+            Tool(
+                name="create_workspace",
+                description="Create a mock workspace with name and subdomain",
+                handler=self._create_workspace,
+                parameters={"name": str, "subdomain": str},
+                required=["name", "subdomain"],
+                dangerous=True,
+                requires_ability="workspaces:write",
+            )
+        )
+        registry.register(
+            Tool(
+                name="invite_member",
+                description="Invite a team member to a workspace by subdomain",
+                handler=self._invite_member,
+                parameters={"subdomain": str, "email": str, "role": str},
+                required=["subdomain", "email"],
+                dangerous=True,
+                requires_ability="team:invite",
+            )
+        )
+        registry.register(
+            Tool(
+                name="list_connections",
+                description="List network connections (connectivity demo)",
+                handler=self._list_connections,
+                parameters={},
+            )
+        )
+        registry.register(
+            Tool(
+                name="provision_link",
+                description="Provision a network link between two sites",
+                handler=self._provision_link,
+                parameters={"site_a": str, "site_b": str, "bandwidth_mbps": int},
+                required=["site_a", "site_b"],
+                dangerous=True,
+            )
+        )
+        return registry
+
+    def system_prompt(self) -> str:
+        return (
+            "You are API Operator (mock mode). You help operators manage "
+            "workspaces and network links using registered tools only. "
+            "Reply in the user's language (Arabic or English). "
+            "Never claim an action succeeded unless a tool returned ok=true."
+        )
+
+    async def _list_workspaces(self) -> ToolResult:
+        items = list(_MockStore.workspaces.values())
+        return ToolResult(ok=True, data={"workspaces": items, "count": len(items)})
+
+    async def _create_workspace(self, name: str, subdomain: str) -> ToolResult:
+        key = subdomain.strip().lower()
+        if key in _MockStore.workspaces:
+            return ToolResult(ok=False, error=f"Workspace '{key}' already exists.")
+        workspace = {
+            "id": key,
+            "name": name.strip(),
+            "subdomain": key,
+            "url": f"https://{key}.example.test",
+        }
+        _MockStore.workspaces[key] = workspace
+        return ToolResult(ok=True, data=workspace)
+
+    async def _invite_member(
+        self,
+        subdomain: str,
+        email: str,
+        role: str = "member",
+    ) -> ToolResult:
+        key = subdomain.strip().lower()
+        if key not in _MockStore.workspaces:
+            return ToolResult(ok=False, error=f"Workspace '{key}' not found.")
+        invitation = {
+            "workspace": key,
+            "email": email.strip().lower(),
+            "role": role.strip().lower() or "member",
+            "status": "sent",
+        }
+        _MockStore.invitations.append(invitation)
+        return ToolResult(ok=True, data=invitation)
+
+    async def _list_connections(self) -> ToolResult:
+        items = list(_MockStore.connections.values())
+        return ToolResult(ok=True, data={"connections": items, "count": len(items)})
+
+    async def _provision_link(
+        self,
+        site_a: str,
+        site_b: str,
+        bandwidth_mbps: int = 100,
+    ) -> ToolResult:
+        link_id = f"{site_a.strip().lower()}-{site_b.strip().lower()}"
+        if link_id in _MockStore.connections:
+            return ToolResult(ok=False, error=f"Link '{link_id}' already exists.")
+        link = {
+            "id": link_id,
+            "site_a": site_a.strip(),
+            "site_b": site_b.strip(),
+            "bandwidth_mbps": bandwidth_mbps,
+            "status": "active",
+        }
+        _MockStore.connections[link_id] = link
+        return ToolResult(ok=True, data=link)
+
+
+def get_mock_store() -> _MockStore:
+    return _MockStore

api_operator/adapters/openapi_generator.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import re
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from api_operator.adapters.yaml_spec import AdapterSpec, ParameterSpec, ToolSpec, save_adapter_spec
+
+_METHODS = {"get", "post", "put", "patch", "delete"}
+
+
+def generate_adapter_from_openapi(
+    spec_path: str | Path,
+    *,
+    base_url: str,
+    name: str | None = None,
+    description: str | None = None,
+    path_prefix: str | None = None,
+    include_methods: set[str] | None = None,
+    tag_filter: set[str] | None = None,
+    dangerous_paths: set[str] | None = None,
+) -> AdapterSpec:
+    path = Path(spec_path)
+    text = path.read_text(encoding="utf-8")
+    if path.suffix.lower() == ".json":
+        raw = json.loads(text)
+    else:
+        raw = yaml.safe_load(text)
+    if not isinstance(raw, dict):
+        raise ValueError("OpenAPI spec must be a YAML/JSON object")
+
+    info = raw.get("info") or {}
+    adapter_name = name or str(info.get("title", path.stem)).lower().replace(" ", "_")
+    adapter_description = description or str(info.get("description", f"{adapter_name} API adapter"))
+    methods = {m.upper() for m in (include_methods or {"GET", "POST"})}
+    dangerous_paths = dangerous_paths or set()
+
+    tools: list[ToolSpec] = []
+    paths = raw.get("paths") or {}
+    for route, path_item in paths.items():
+        if not isinstance(path_item, dict):
+            continue
+        if path_prefix and not route.startswith(path_prefix):
+            continue
+
+        for method, operation in path_item.items():
+            if method.lower() not in _METHODS or not isinstance(operation, dict):
+                continue
+            if method.upper() not in methods:
+                continue
+
+            tags = operation.get("tags") or []
+            if tag_filter and not (set(tags) & tag_filter):
+                continue
+
+            tool = _operation_to_tool(route, method.upper(), operation, dangerous_paths)
+            if tool:
+                tools.append(tool)
+
+    if not tools:
+        raise ValueError("No tools generated — check path_prefix, methods, or tag_filter.")
+
+    return AdapterSpec(
+        name=adapter_name,
+        description=adapter_description,
+        base_url=base_url.rstrip("/"),
+        system_prompt=(
+            f"You are API Operator for {adapter_name}. "
+            "Use tools to call the project API. Confirm dangerous actions. "
+            "Reply in the user's language."
+        ),
+        tools=tools,
+        token_env=f"{adapter_name.upper()}_API_TOKEN",
+    )
+
+
+def _operation_to_tool(
+    route: str,
+    method: str,
+    operation: dict[str, Any],
+    dangerous_paths: set[str],
+) -> ToolSpec | None:
+    operation_id = operation.get("operationId")
+    summary = operation.get("summary") or operation.get("description") or f"{method} {route}"
+    name = _tool_name(operation_id, method, route)
+    parameters: dict[str, ParameterSpec] = {}
+    path = route
+
+    for param in operation.get("parameters") or []:
+        if not isinstance(param, dict):
+            continue
+        pname = param.get("name")
+        if not pname:
+            continue
+        location = param.get("in")
+        required = bool(param.get("required", False))
+        schema = param.get("schema") or {}
+        ptype = str(schema.get("type", "string"))
+        parameters[str(pname)] = ParameterSpec(type=ptype, required=required)
+        if location == "path":
+            path = path.replace(f"{{{pname}}}", f"{{{pname}}}")
+
+    body_template: dict[str, Any] | None = None
+    request_body = operation.get("requestBody") or {}
+    content = request_body.get("content") or {}
+    json_content = content.get("application/json") or {}
+    schema = json_content.get("schema") or {}
+    props = schema.get("properties") or {}
+    required_fields = set(schema.get("required") or [])
+    if props:
+        body_template = {}
+        for pname, pschema in props.items():
+            if not isinstance(pschema, dict):
+                continue
+            parameters.setdefault(
+                str(pname),
+                ParameterSpec(
+                    type=str(pschema.get("type", "string")),
+                    required=str(pname) in required_fields,
+                ),
+            )
+            body_template[str(pname)] = f"{{{pname}}}"
+
+    dangerous = method in {"POST", "PUT", "PATCH", "DELETE"} or route in dangerous_paths
+
+    return ToolSpec(
+        name=name,
+        description=str(summary).strip(),
+        method=method,
+        path=path,
+        parameters=parameters,
+        body=body_template,
+        dangerous=dangerous,
+    )
+
+
+def _tool_name(operation_id: str | None, method: str, route: str) -> str:
+    if operation_id:
+        return _slugify(operation_id)
+    slug = _slugify(route.replace("{", "").replace("}", "").replace("/", "_"))
+    return _slugify(f"{method.lower()}_{slug}")
+
+
+def _slugify(value: str) -> str:
+    value = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", value)
+    value = value.strip().lower()
+    value = re.sub(r"[^a-z0-9_]+", "_", value)
+    value = re.sub(r"_+", "_", value).strip("_")
+    return value[:64] or "tool"
+
+
+SCAFFOLD_TEMPLATE = """name: {name}
+description: {description}
+base_url: {base_url}
+
+auth:
+  type: bearer
+  header: Authorization
+  env_token: {token_env}
+
+system_prompt: |
+  You are API Operator for {name}.
+  Use registered tools only. Confirm dangerous actions.
+  Reply in the user's language (Arabic or English).
+
+tools:
+  - name: list_items
+    description: List items from the project API
+    method: GET
+    path: /api/items
+    requires_ability: items:read
+
+  - name: create_item
+    description: Create a new item
+    method: POST
+    path: /api/items
+    dangerous: true
+    requires_ability: items:write
+    parameters:
+      title:
+        type: string
+        required: true
+    body:
+      title: "{{title}}"
+"""
+
+
+def scaffold_adapter(
+    name: str,
+    output_dir: str | Path,
+    *,
+    base_url: str = "http://localhost:8000",
+    description: str | None = None,
+) -> Path:
+    directory = Path(output_dir)
+    directory.mkdir(parents=True, exist_ok=True)
+    config_path = directory / "adapter.yaml"
+    token_env = f"{name.upper()}_API_TOKEN"
+    config_path.write_text(
+        SCAFFOLD_TEMPLATE.format(
+            name=name,
+            description=description or f"{name} API adapter",
+            base_url=base_url.rstrip("/"),
+            token_env=token_env,
+        ),
+        encoding="utf-8",
+    )
+
+    readme = directory / "README.md"
+    readme.write_text(
+        f"""# {name} adapter (YAML)
+
+No Python required — edit `adapter.yaml` and run:
+
+```powershell
+python -m api_operator.server.cli chat --adapter yaml --config adapter.yaml
+```
+
+Set token:
+
+```powershell
+$env:{token_env} = "your-api-token"
+```
+
+Or pass `--token` on the CLI.
+
+Generate from OpenAPI:
+
+```powershell
+python -m api_operator.server.cli generate-from-openapi openapi.yaml --output adapter.yaml --base-url {base_url}
+```
+""",
+        encoding="utf-8",
+    )
+    return config_path

api_operator/adapters/registry.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from api_operator.adapters.base import Adapter
+from api_operator.adapters.mock import MockAdapter
+from api_operator.adapters.yaml_adapter import YamlAdapter
+
+_BUILTIN: dict[str, type[Adapter]] = {
+    "mock": MockAdapter,
+    "yaml": YamlAdapter,
+}
+
+_REGISTERED: dict[str, type[Adapter]] = {}
+
+
+def register_adapter(name: str, adapter_cls: type[Adapter]) -> None:
+    """Register a custom adapter at runtime (e.g. from your project bootstrap)."""
+    _REGISTERED[name] = adapter_cls
+
+
+def import_adapter_class(reference: str) -> type[Adapter]:
+    """
+    Import adapter class from 'module.path:ClassName'.
+    Used for adapters that live outside the core package.
+    """
+    if ":" not in reference:
+        raise ValueError("adapter_class must be 'module.path:ClassName'")
+    module_path, class_name = reference.split(":", 1)
+    module = importlib.import_module(module_path)
+    cls = getattr(module, class_name)
+    if not isinstance(cls, type) or not issubclass(cls, Adapter):
+        raise TypeError(f"{reference} is not an Adapter subclass")
+    return cls
+
+
+def available_adapters() -> list[str]:
+    return sorted({*_BUILTIN.keys(), *_REGISTERED.keys()})
+
+
+def load_adapter(
+    name: str | None = None,
+    *,
+    adapter_class: str | None = None,
+    config_path: str | None = None,
+    **kwargs: Any,
+) -> Adapter:
+    if adapter_class:
+        cls = import_adapter_class(adapter_class)
+        return cls(**kwargs)
+
+    if name is None:
+        name = "mock"
+
+    if name == "mock":
+        return MockAdapter()
+
+    if name == "yaml":
+        if not config_path:
+            raise ValueError("yaml adapter requires config_path (adapter.yaml).")
+        return YamlAdapter(config_path=config_path, **kwargs)
+
+    cls = _REGISTERED.get(name) or _BUILTIN.get(name)
+    if cls is None:
+        available = ", ".join(available_adapters())
+        raise ValueError(
+            f"Unknown adapter '{name}'. Built-in: {available}. "
+            "Use --adapter yaml --config adapter.yaml or adapter_class='module:Class'."
+        )
+    return cls(**kwargs)  # type: ignore[call-arg]

api_operator/adapters/yaml_adapter.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+import httpx
+
+from api_operator.adapters.base import Adapter
+from api_operator.adapters.yaml_spec import AdapterSpec, ToolSpec, load_adapter_spec
+from api_operator.tools.base import Tool, ToolRegistry, ToolResult
+
+_PLACEHOLDER = re.compile(r"\{(\w+)\}")
+
+
+class YamlAdapter(Adapter):
+    """
+    HTTP adapter driven by a YAML config file — no Python required per project.
+
+    See examples/tenant-kit-adapter/adapter.yaml and `scaffold-adapter` CLI.
+    """
+
+    name = "yaml"
+    description = "YAML-configured HTTP adapter"
+
+    def __init__(
+        self,
+        config_path: str,
+        token: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        self.spec = load_adapter_spec(config_path)
+        self.name = self.spec.name
+        self.description = self.spec.description
+        self.token = token or _token_from_env(self.spec.token_env)
+        if base_url:
+            self.spec.base_url = base_url.rstrip("/")
+
+    def auth_context(self) -> dict[str, Any]:
+        return {"token": "***" if self.token else None, "base_url": self.spec.base_url}
+
+    def build_registry(self) -> ToolRegistry:
+        registry = ToolRegistry()
+        for tool_spec in self.spec.tools:
+            registry.register(self._build_tool(tool_spec))
+        return registry
+
+    def system_prompt(self) -> str:
+        return self.spec.system_prompt
+
+    def _build_tool(self, spec: ToolSpec) -> Tool:
+        param_types: dict[str, type | str] = {}
+        required: list[str] = []
+        for name, param in spec.parameters.items():
+            param_types[name] = param.type
+            if param.required:
+                required.append(name)
+
+        async def handler(**kwargs: Any) -> ToolResult:
+            return await self._execute(spec, kwargs)
+
+        return Tool(
+            name=spec.name,
+            description=spec.description,
+            handler=handler,
+            parameters=param_types,
+            required=required,
+            dangerous=spec.dangerous,
+            requires_ability=spec.requires_ability,
+        )
+
+    async def _execute(self, spec: ToolSpec, args: dict[str, Any]) -> ToolResult:
+        if self.spec.auth_type == "bearer" and not self.token:
+            return ToolResult(ok=False, error="Missing API token for YAML adapter.")
+
+        for name, param in spec.parameters.items():
+            if args.get(name) is None and param.default is not None:
+                args[name] = param.default
+
+        url = self._build_url(spec, args)
+        json_body = self._build_body(spec.body, args) if spec.body else None
+        params = self._build_query(spec.query, args) if spec.query else None
+
+        headers = {"Accept": "application/json"}
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+        if self.token and self.spec.auth_type == "bearer":
+            headers[self.spec.auth_header] = f"Bearer {self.token}"
+
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.request(
+                    spec.method,
+                    url,
+                    headers=headers,
+                    json=json_body,
+                    params=params,
+                )
+        except httpx.HTTPError as exc:
+            return ToolResult(ok=False, error=f"HTTP error: {exc}")
+
+        try:
+            body = response.json()
+        except ValueError:
+            body = {"raw": response.text}
+
+        if response.is_success:
+            return ToolResult(ok=True, data=body if isinstance(body, dict) else {"data": body})
+
+        error = body.get("message") if isinstance(body, dict) else response.text
+        return ToolResult(
+            ok=False,
+            error=f"API {response.status_code}: {error}",
+            data=body if isinstance(body, dict) else {},
+        )
+
+    def _build_url(self, spec: ToolSpec, args: dict[str, Any]) -> str:
+        path = spec.path
+        for match in _PLACEHOLDER.finditer(path):
+            key = match.group(1)
+            if key not in args:
+                raise ValueError(f"Missing path parameter: {key}")
+            path = path.replace(f"{{{key}}}", str(args[key]))
+
+        base = self._resolve_base(spec, args)
+        return f"{base}{path}"
+
+    def _resolve_base(self, spec: ToolSpec, args: dict[str, Any]) -> str:
+        if spec.host != "tenant":
+            return self.spec.base_url
+
+        subdomain_key = spec.tenant_param
+        subdomain = args.get(subdomain_key)
+        if not subdomain:
+            raise ValueError(f"Missing tenant parameter: {subdomain_key}")
+
+        return _tenant_base_url(self.spec.base_url, str(subdomain))
+
+    def _build_body(self, template: dict[str, Any], args: dict[str, Any]) -> dict[str, Any]:
+        return _render_mapping(template, args)
+
+    def _build_query(self, template: dict[str, str], args: dict[str, Any]) -> dict[str, str]:
+        return {key: str(_render_value(value, args)) for key, value in template.items()}
+
+
+def _tenant_base_url(base_url: str, subdomain: str) -> str:
+    if "://" not in base_url:
+        raise ValueError("base_url must include scheme")
+    scheme, rest = base_url.split("://", 1)
+    host = rest.split("/", 1)[0]
+    return f"{scheme}://{subdomain}.{host}"
+
+
+def _render_mapping(template: dict[str, Any], args: dict[str, Any]) -> dict[str, Any]:
+    return {key: _render_value(value, args) for key, value in template.items()}
+
+
+def _render_value(value: Any, args: dict[str, Any]) -> Any:
+    if isinstance(value, str):
+        rendered = value
+        for match in _PLACEHOLDER.finditer(value):
+            key = match.group(1)
+            if key not in args:
+                raise ValueError(f"Missing body parameter: {key}")
+            rendered = rendered.replace(f"{{{key}}}", str(args[key]))
+        return rendered
+    if isinstance(value, dict):
+        return _render_mapping(value, args)
+    return value
+
+
+def _token_from_env(env_name: str | None) -> str | None:
+    if not env_name:
+        return None
+    return os.environ.get(env_name)