api-operator 0.9.0__py3-none-any.whl

api_operator/core/planner_openai.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from api_operator.core.config import Settings
+from api_operator.core.planner import MockPlanner, PlanStep, Planner
+from api_operator.tools.base import ToolRegistry
+
+
+class OpenAIPlanner:
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+
+    async def plan(
+        self,
+        message: str,
+        registry: ToolRegistry,
+        history: list[dict[str, str]],
+        system_prompt: str,
+    ) -> PlanStep:
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as exc:
+            raise RuntimeError(
+                "OpenAI planner requires optional dependency. Install with: pip install api-operator[llm]"
+            ) from exc
+
+        if not self.settings.openai_api_key:
+            raise RuntimeError("api_operator_OPENAI_API_KEY is not set.")
+
+        client = AsyncOpenAI(api_key=self.settings.openai_api_key)
+        tools = [_openai_tool_schema(tool.schema()) for tool in registry.list_tools()]
+        messages: list[dict[str, Any]] = [{"role": "system", "content": system_prompt}]
+        messages.extend(history[-12:])
+        messages.append({"role": "user", "content": message})
+
+        response = await client.chat.completions.create(
+            model=self.settings.openai_model,
+            messages=messages,
+            tools=tools or None,
+            tool_choice="auto" if tools else None,
+        )
+        choice = response.choices[0].message
+
+        if choice.tool_calls:
+            call = choice.tool_calls[0]
+            args = json.loads(call.function.arguments or "{}")
+            return PlanStep(type="tool", tool_name=call.function.name, tool_args=args)
+
+        return PlanStep(type="respond", content=choice.content or "")
+
+
+def _openai_tool_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": schema["name"],
+            "description": schema["description"],
+            "parameters": schema["parameters"],
+        },
+    }
+
+
+def build_planner(settings: Settings) -> Planner:
+    mode = settings.planner
+    if mode == "auto":
+        mode = "openai" if settings.openai_api_key else "mock"
+    if mode == "openai":
+        return OpenAIPlanner(settings)
+    return MockPlanner()

api_operator/factory.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from api_operator.core.agent import Agent
+from api_operator.core.config import Settings
+from api_operator.core.memory import SessionStore
+from api_operator.adapters.registry import load_adapter
+
+
+def build_agent(
+    adapter_name: str = "mock",
+    settings: Settings | None = None,
+    adapter_class: str | None = None,
+    config_path: str | None = None,
+    sessions: SessionStore | None = None,
+    **adapter_kwargs: Any,
+) -> Agent:
+    settings = settings or Settings()
+    adapter = load_adapter(
+        adapter_name,
+        adapter_class=adapter_class,
+        config_path=config_path,
+        **adapter_kwargs,
+    )
+    return Agent(adapter=adapter, settings=settings, sessions=sessions)

api_operator/rag/indexer.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+class DocsIndex:
+    """Lightweight keyword RAG over markdown/text docs (no embeddings required)."""
+
+    def __init__(self, paths: list[str | Path]) -> None:
+        self.chunks: list[tuple[str, str]] = []
+        for path in paths:
+            file_path = Path(path)
+            if not file_path.exists():
+                continue
+            text = file_path.read_text(encoding="utf-8", errors="ignore")
+            source = str(file_path)
+            for idx, paragraph in enumerate(text.split("\n\n")):
+                cleaned = paragraph.strip()
+                if len(cleaned) < 40:
+                    continue
+                self.chunks.append((source, cleaned))
+
+    def search(self, query: str, limit: int = 3) -> list[dict[str, Any]]:
+        terms = [t for t in query.lower().split() if len(t) > 2]
+        if not terms:
+            return []
+        scored: list[tuple[int, str, str]] = []
+        for source, chunk in self.chunks:
+            lower = chunk.lower()
+            score = sum(lower.count(term) for term in terms)
+            if score:
+                scored.append((score, source, chunk))
+        scored.sort(key=lambda item: item[0], reverse=True)
+        return [
+            {"source": source, "excerpt": chunk[:500]}
+            for _, source, chunk in scored[:limit]
+        ]

api_operator/server/app.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from api_operator.adapters.registry import available_adapters
+from api_operator.core.config import Settings
+from api_operator.core.memory import SessionStore
+from api_operator.factory import build_agent
+
+
+class ChatRequest(BaseModel):
+    message: str
+    session_id: str | None = None
+    adapter: str | None = None
+    adapter_class: str | None = None
+    config_path: str | None = None
+    abilities: list[str] | None = None
+    auto_confirm: bool = False
+    adapter_config: dict[str, Any] = Field(default_factory=dict)
+
+
+class ChatResponse(BaseModel):
+    session_id: str
+    message: str
+    status: str
+    tool: str | None = None
+    tool_result: dict[str, Any] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+def create_app(settings: Settings | None = None):
+    from fastapi import FastAPI, HTTPException
+
+    settings = settings or Settings()
+    session_store = SessionStore()
+    app = FastAPI(
+        title="API Operator",
+        version="0.1.0",
+        description="Standalone AI operator with pluggable adapters",
+    )
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        return {"status": "ok", "adapter_default": settings.default_adapter}
+
+    @app.get("/v1/adapters")
+    async def adapters() -> dict[str, Any]:
+        return {
+            "builtin": available_adapters(),
+            "yaml": "Use adapter=yaml with config_path in adapter_config",
+            "external": "Use adapter_class=module.path:ClassName (see examples/)",
+        }
+
+    @app.get("/v1/tools")
+    async def tools(
+        adapter: str | None = None,
+        adapter_class: str | None = None,
+        config_path: str | None = None,
+        base_url: str | None = None,
+        token: str | None = None,
+    ) -> dict[str, Any]:
+        name = adapter or settings.default_adapter
+        config: dict[str, Any] = {}
+        if config_path:
+            config["config_path"] = config_path
+        if base_url:
+            config["base_url"] = base_url
+        if token:
+            config["token"] = token
+        agent = build_agent(
+            name,
+            settings=settings,
+            adapter_class=adapter_class,
+            config_path=config_path,
+            base_url=base_url,
+            token=token,
+        )
+        return {"adapter": name, "adapter_class": adapter_class, "tools": agent.list_tools()}
+
+    @app.post("/v1/chat", response_model=ChatResponse)
+    async def chat(payload: ChatRequest) -> ChatResponse:
+        name = payload.adapter or settings.default_adapter
+        extra = dict(payload.adapter_config)
+        cfg = payload.config_path or extra.pop("config_path", None)
+        try:
+            agent = build_agent(
+                name,
+                settings=settings,
+                adapter_class=payload.adapter_class,
+                config_path=cfg,
+                sessions=session_store,
+                **extra,
+            )
+        except (ValueError, TypeError) as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+        response = await agent.chat(
+            message=payload.message,
+            session_id=payload.session_id,
+            abilities=payload.abilities,
+            auto_confirm=payload.auto_confirm,
+        )
+        return ChatResponse(
+            session_id=response.session_id,
+            message=response.message,
+            status=response.status,
+            tool=response.tool,
+            tool_result=response.tool_result,
+            metadata=response.metadata,
+        )
+
+    return app

api_operator/server/cli.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.table import Table
+
+from api_operator.adapters.mock import reset_mock_store
+from api_operator.adapters.openapi_generator import generate_adapter_from_openapi, scaffold_adapter
+from api_operator.adapters.yaml_spec import save_adapter_spec
+from api_operator.core.config import Settings
+from api_operator.factory import build_agent
+from api_operator.server.app import create_app
+
+app = typer.Typer(no_args_is_help=True, help="API Operator CLI")
+console = Console()
+
+
+def _build_agent_from_cli(
+    adapter: str,
+    adapter_class: str | None,
+    config: str | None,
+    planner: str,
+    base_url: str | None,
+    token: str | None,
+) -> Any:
+    settings = Settings(planner=planner, default_adapter=adapter)
+    kwargs: dict[str, Any] = {}
+    if base_url:
+        kwargs["base_url"] = base_url
+    if token:
+        kwargs["token"] = token
+    if adapter == "yaml" and not config:
+        console.print("[red]--adapter yaml requires --config path/to/adapter.yaml[/red]")
+        raise typer.Exit(code=1)
+    return build_agent(
+        adapter,
+        settings=settings,
+        adapter_class=adapter_class,
+        config_path=config,
+        **kwargs,
+    )
+
+
+@app.command("chat")
+def chat(
+    adapter: str = typer.Option("mock", help="Built-in adapter: mock | yaml"),
+    config: str | None = typer.Option(None, help="Path to adapter.yaml (required for yaml adapter)"),
+    adapter_class: str | None = typer.Option(None, help="External adapter class module:Class"),
+    session_id: str | None = typer.Option(None, help="Reuse session id"),
+    planner: str = typer.Option("mock", help="Planner: mock | openai | auto"),
+    base_url: str | None = typer.Option(None, help="Override API base URL from YAML"),
+    token: str | None = typer.Option(None, help="API bearer token"),
+    auto_confirm: bool = typer.Option(False, help="Skip dangerous confirmations"),
+) -> None:
+    """Interactive chat in the terminal."""
+    agent = _build_agent_from_cli(adapter, adapter_class, config, planner, base_url, token)
+    sid = session_id
+    label = config or adapter_class or adapter
+    console.print(f"[bold green]API Operator[/bold green] adapter={label} planner={planner}")
+    console.print("Type 'exit' to quit.\n")
+
+    while True:
+        try:
+            user_input = console.input("[bold cyan]you>[/bold cyan] ")
+        except (EOFError, KeyboardInterrupt):
+            console.print("\nBye.")
+            break
+        if user_input.strip().lower() in {"exit", "quit"}:
+            break
+        response = asyncio.run(
+            agent.chat(
+                message=user_input,
+                session_id=sid,
+                abilities=_default_abilities(adapter),
+                auto_confirm=auto_confirm,
+            )
+        )
+        sid = response.session_id
+        color = {"ok": "green", "confirm": "yellow", "error": "red"}.get(response.status, "white")
+        console.print(f"[bold {color}]agent>[/bold {color}] {response.message}")
+
+
+@app.command("serve")
+def serve(
+    host: str = typer.Option("127.0.0.1", help="Host"),
+    port: int = typer.Option(8100, help="Port"),
+    adapter: str = typer.Option("mock", help="Default adapter"),
+    planner: str = typer.Option("mock", help="Planner mode"),
+) -> None:
+    """Run HTTP API server."""
+    import uvicorn
+
+    settings = Settings(host=host, port=port, default_adapter=adapter, planner=planner)
+    uvicorn.run(create_app(settings), host=host, port=port)
+
+
+@app.command("tools")
+def tools(
+    adapter: str = typer.Option("mock", help="Adapter name"),
+    config: str | None = typer.Option(None, help="adapter.yaml path for yaml adapter"),
+    base_url: str | None = typer.Option(None, help="Override base URL"),
+    token: str | None = typer.Option(None, help="API token"),
+) -> None:
+    """List registered tools for an adapter."""
+    agent = _build_agent_from_cli(adapter, None, config, "mock", base_url, token)
+    table = Table(title=f"Tools ({config or adapter})")
+    table.add_column("Name")
+    table.add_column("Dangerous")
+    table.add_column("Ability")
+    table.add_column("Description")
+    for schema in agent.list_tools():
+        table.add_row(
+            schema["name"],
+            str(schema.get("dangerous", False)),
+            str(schema.get("requires_ability") or "-"),
+            schema["description"],
+        )
+    console.print(table)
+
+
+@app.command("scaffold-adapter")
+def scaffold_cmd(
+    name: str = typer.Argument(..., help="Adapter/project name"),
+    output: str = typer.Option("examples", help="Output directory"),
+    base_url: str = typer.Option("http://localhost:8000", help="Default API base URL"),
+) -> None:
+    """Create adapter.yaml + README template (no Python required)."""
+    out_dir = Path(output) / f"{name}-adapter"
+    path = scaffold_adapter(name, out_dir, base_url=base_url)
+    console.print(f"[green]Created[/green] {path}")
+    console.print(f"Edit the YAML, then run:\n  python -m api_operator.server.cli chat --adapter yaml --config {path}")
+
+
+@app.command("generate-from-openapi")
+def generate_openapi_cmd(
+    spec: str = typer.Argument(..., help="OpenAPI YAML/JSON file"),
+    output: str = typer.Option("adapter.yaml", help="Output adapter.yaml path"),
+    base_url: str = typer.Option(..., help="API base URL"),
+    path_prefix: str | None = typer.Option("/api", help="Only include paths starting with this prefix"),
+    methods: str = typer.Option("GET,POST", help="Comma-separated HTTP methods to include"),
+) -> None:
+    """Generate adapter.yaml from an OpenAPI spec."""
+    include = {m.strip().upper() for m in methods.split(",") if m.strip()}
+    adapter_spec = generate_adapter_from_openapi(
+        spec,
+        base_url=base_url,
+        path_prefix=path_prefix,
+        include_methods=include,
+    )
+    save_adapter_spec(adapter_spec, output)
+    console.print(f"[green]Generated[/green] {output} with {len(adapter_spec.tools)} tools")
+
+
+@app.command("demo")
+def demo() -> None:
+    """Run an automated mock demo conversation."""
+    reset_mock_store()
+    agent = build_agent("mock", settings=Settings(planner="mock"))
+
+    async def run() -> None:
+        steps = [
+            "list workspaces",
+            "create workspace Acme subdomain acme",
+            "yes",
+            "invite admin@acme.com to acme admin",
+            "yes",
+            "list workspaces",
+            "provision link Riyadh Jeddah 500",
+            "yes",
+            "list connections",
+        ]
+        sid = None
+        for step in steps:
+            console.print(f"[cyan]you>[/cyan] {step}")
+            response = await agent.chat(
+                message=step,
+                session_id=sid,
+                abilities=_default_abilities("mock"),
+            )
+            sid = response.session_id
+            console.print(f"[green]agent>[/green] {response.message}\n")
+
+    asyncio.run(run())
+    console.print(Markdown("Demo complete. Try YAML adapter with examples/tenant-kit-adapter/adapter.yaml"))
+
+
+def _default_abilities(adapter: str) -> list[str] | None:
+    if adapter == "mock":
+        return ["workspaces:read", "workspaces:write", "team:invite"]
+    if adapter == "yaml":
+        return ["workspaces:read", "workspaces:write", "team:invite"]
+    return None
+
+
+if __name__ == "__main__":
+    app()

api_operator/tools/base.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from api_operator.tools.schema import tool_parameters_schema
+
+
+@dataclass(slots=True)
+class ToolResult:
+    ok: bool
+    data: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"ok": self.ok, "data": self.data}
+        if self.error:
+            payload["error"] = self.error
+        return payload
+
+
+@dataclass(slots=True)
+class Tool:
+    name: str
+    description: str
+    handler: Callable[..., ToolResult | Awaitable[ToolResult]]
+    parameters: dict[str, type | str] = field(default_factory=dict)
+    required: list[str] = field(default_factory=list)
+    dangerous: bool = False
+    requires_ability: str | None = None
+
+    def schema(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": tool_parameters_schema(self.parameters, self.required),
+            "dangerous": self.dangerous,
+            "requires_ability": self.requires_ability,
+        }
+
+    async def run(self, **kwargs: Any) -> ToolResult:
+        result = self.handler(**kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        if tool.name in self._tools:
+            raise ValueError(f"Tool already registered: {tool.name}")
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def list_tools(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return [tool.schema() for tool in self.list_tools()]
+
+    def names(self) -> list[str]:
+        return list(self._tools.keys())

api_operator/tools/schema.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, get_args, get_origin
+
+
+_TYPE_MAP: dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+}
+
+
+def _json_type(python_type: type | str) -> str:
+    if isinstance(python_type, str):
+        return python_type
+    origin = get_origin(python_type)
+    if origin is list:
+        return "array"
+    return _TYPE_MAP.get(python_type, "string")
+
+
+def tool_parameters_schema(
+    parameters: dict[str, type | str],
+    required: list[str],
+) -> dict[str, Any]:
+    properties: dict[str, Any] = {}
+    for name, param_type in parameters.items():
+        properties[name] = {"type": _json_type(param_type)}
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+    }