api-operator 0.9.0__tar.gz

api_operator-0.9.0/.env.example

@@ -0,0 +1,6 @@
+api_operator_HOST=127.0.0.1
+api_operator_PORT=8100
+api_operator_DEFAULT_ADAPTER=mock
+api_operator_PLANNER=mock
+# api_operator_OPENAI_API_KEY=
+# api_operator_OPENAI_MODEL=gpt-4o-mini

api_operator-0.9.0/.github/workflows/tests.yml

@@ -0,0 +1,28 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q

api_operator-0.9.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Tools
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environment & secrets
+.env
+.env.local
+*.pem
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db

api_operator-0.9.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.9.0] - 2026-06-14
+
+Renamed to **`api-operator`** (GitHub + PyPI). PyPI blocks names starting with `operator` (stdlib conflict).
+
+### Added
+
+- Core agent runtime: planning, guardrails, tool execution, session memory
+- `mock` adapter for offline demos and tests
+- `yaml` adapter — configure HTTP tools without Python
+- OpenAPI scaffold CLI (`generate-from-openapi`, `scaffold-adapter`)
+- CLI: `chat`, `demo`, `tools`, `serve`
+- FastAPI server: `/health`, `/v1/adapters`, `/v1/tools`, `/v1/chat`
+- Example adapter for [Laravel Tenant Kit](https://github.com/mohammedelkarsh/laravel-tenant-kit)
+- Live integration script: `scripts/integration_tenant_kit.py`
+- 69 unit tests; optional pytest integration marker
+
+### Notes
+
+- Default planner is rule-based (`mock`); OpenAI planner is optional (`pip install api-operator[llm]`)
+- Tenant team invites require a tenant-scoped Sanctum token (see example adapter README)

api_operator-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Elkarsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

api_operator-0.9.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: api-operator
+Version: 0.9.0
+Summary: Standalone AI API Operator with pluggable adapters for multi-project APIs
+Project-URL: Homepage, https://github.com/mohammedelkarsh/api-operator
+Project-URL: Repository, https://github.com/mohammedelkarsh/api-operator
+Project-URL: Issues, https://github.com/mohammedelkarsh/api-operator/issues
+Project-URL: Changelog, https://github.com/mohammedelkarsh/api-operator/blob/main/CHANGELOG.md
+Author: Mohammed Elkarsh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,llm,multi-tenant,openapi,saas,tools,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.3.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: openai>=1.35.0; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# API Operator
+
+[![Tests](https://github.com/mohammedelkarsh/api-operator/actions/workflows/tests.yml/badge.svg)](https://github.com/mohammedelkarsh/api-operator/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+
+Standalone **AI operator runtime** with pluggable adapters. Talk to your HTTP APIs instead of clicking through admin panels.
+
+Works with Laravel, Go, connectivity platforms, or any backend with a REST API.
+
+## Install
+
+```bash
+git clone https://github.com/mohammedelkarsh/api-operator.git
+cd api-operator
+pip install -e ".[dev]"
+```
+
+Optional OpenAI planner:
+
+```bash
+pip install -e ".[dev,llm]"
+```
+
+## Quick start
+
+```bash
+api-operator demo
+api-operator tools --adapter mock
+```
+
+## What ships in the core package
+
+| In core | In your projects |
+|---------|------------------|
+| Agent runtime (plan, guard, execute) | `adapter.yaml` per API |
+| `mock` adapter (demo + tests) | OpenAPI specs |
+| `yaml` adapter | API tokens in `.env` |
+| CLI + HTTP server | Optional custom adapters |
+
+## Build an adapter without Python
+
+### Scaffold template
+
+```bash
+api-operator scaffold-adapter my-api --output examples
+```
+
+### Generate from OpenAPI
+
+```bash
+api-operator generate-from-openapi openapi.yaml \
+  --output adapter.yaml \
+  --base-url http://api.example.test \
+  --path-prefix /api
+```
+
+### Laravel Tenant Kit example
+
+See [`examples/tenant-kit-adapter/`](examples/tenant-kit-adapter/) — pairs with [laravel-tenant-kit](https://github.com/mohammedelkarsh/laravel-tenant-kit).
+
+```bash
+export TENANT_KIT_API_TOKEN="your-sanctum-token"
+api-operator chat \
+  --adapter yaml \
+  --config examples/tenant-kit-adapter/adapter.yaml \
+  --base-url http://laravel-tenant-kit.test
+```
+
+## adapter.yaml (minimal)
+
+```yaml
+name: my_project
+description: My API adapter
+base_url: http://api.example.test
+
+auth:
+  type: bearer
+  env_token: MY_PROJECT_API_TOKEN
+
+tools:
+  - name: list_items
+    description: List items
+    method: GET
+    path: /api/items
+
+  - name: create_item
+    description: Create item
+    method: POST
+    path: /api/items
+    dangerous: true
+    parameters:
+      title:
+        type: string
+        required: true
+    body:
+      title: "{title}"
+```
+
+Tenant subdomain APIs:
+
+```yaml
+  - name: invite_member
+    method: POST
+    path: /api/team/invitations
+    host: tenant
+    tenant_param: subdomain
+    parameters:
+      subdomain: { type: string, required: true }
+      email: { type: string, required: true }
+```
+
+## HTTP server
+
+```bash
+api-operator serve --port 8100
+```
+
+```json
+POST /v1/chat
+{
+  "adapter": "yaml",
+  "config_path": "examples/tenant-kit-adapter/adapter.yaml",
+  "adapter_config": { "token": "YOUR_TOKEN" },
+  "message": "list workspaces",
+  "abilities": ["workspaces:read"]
+}
+```
+
+## Integration test (Tenant Kit)
+
+With [Tenant Kit](https://github.com/mohammedelkarsh/laravel-tenant-kit) running:
+
+```bash
+python scripts/integration_tenant_kit.py
+# Docker on port 8080:
+python scripts/integration_tenant_kit.py --base-url http://laravel-tenant-kit.test:8080
+```
+
+Optional pytest marker (requires env vars):
+
+```bash
+export TENANT_KIT_BASE_URL=http://laravel-tenant-kit.test
+export TENANT_KIT_API_TOKEN=your-token
+pytest -m integration -q
+```
+
+## Tests
+
+```bash
+pytest -q
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` for local defaults (`api_operator_PLANNER`, port, etc.).
+
+## Architecture
+
+```
+api-operator (core)          your projects
+├── agent runtime               ├── adapter.yaml
+├── mock + yaml adapters        ├── openapi.yaml
+└── scaffold / generate CLI     └── HTTP APIs (Laravel, Go, …)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

api_operator-0.9.0/README.md

@@ -0,0 +1,169 @@
+# API Operator
+
+[![Tests](https://github.com/mohammedelkarsh/api-operator/actions/workflows/tests.yml/badge.svg)](https://github.com/mohammedelkarsh/api-operator/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+
+Standalone **AI operator runtime** with pluggable adapters. Talk to your HTTP APIs instead of clicking through admin panels.
+
+Works with Laravel, Go, connectivity platforms, or any backend with a REST API.
+
+## Install
+
+```bash
+git clone https://github.com/mohammedelkarsh/api-operator.git
+cd api-operator
+pip install -e ".[dev]"
+```
+
+Optional OpenAI planner:
+
+```bash
+pip install -e ".[dev,llm]"
+```
+
+## Quick start
+
+```bash
+api-operator demo
+api-operator tools --adapter mock
+```
+
+## What ships in the core package
+
+| In core | In your projects |
+|---------|------------------|
+| Agent runtime (plan, guard, execute) | `adapter.yaml` per API |
+| `mock` adapter (demo + tests) | OpenAPI specs |
+| `yaml` adapter | API tokens in `.env` |
+| CLI + HTTP server | Optional custom adapters |
+
+## Build an adapter without Python
+
+### Scaffold template
+
+```bash
+api-operator scaffold-adapter my-api --output examples
+```
+
+### Generate from OpenAPI
+
+```bash
+api-operator generate-from-openapi openapi.yaml \
+  --output adapter.yaml \
+  --base-url http://api.example.test \
+  --path-prefix /api
+```
+
+### Laravel Tenant Kit example
+
+See [`examples/tenant-kit-adapter/`](examples/tenant-kit-adapter/) — pairs with [laravel-tenant-kit](https://github.com/mohammedelkarsh/laravel-tenant-kit).
+
+```bash
+export TENANT_KIT_API_TOKEN="your-sanctum-token"
+api-operator chat \
+  --adapter yaml \
+  --config examples/tenant-kit-adapter/adapter.yaml \
+  --base-url http://laravel-tenant-kit.test
+```
+
+## adapter.yaml (minimal)
+
+```yaml
+name: my_project
+description: My API adapter
+base_url: http://api.example.test
+
+auth:
+  type: bearer
+  env_token: MY_PROJECT_API_TOKEN
+
+tools:
+  - name: list_items
+    description: List items
+    method: GET
+    path: /api/items
+
+  - name: create_item
+    description: Create item
+    method: POST
+    path: /api/items
+    dangerous: true
+    parameters:
+      title:
+        type: string
+        required: true
+    body:
+      title: "{title}"
+```
+
+Tenant subdomain APIs:
+
+```yaml
+  - name: invite_member
+    method: POST
+    path: /api/team/invitations
+    host: tenant
+    tenant_param: subdomain
+    parameters:
+      subdomain: { type: string, required: true }
+      email: { type: string, required: true }
+```
+
+## HTTP server
+
+```bash
+api-operator serve --port 8100
+```
+
+```json
+POST /v1/chat
+{
+  "adapter": "yaml",
+  "config_path": "examples/tenant-kit-adapter/adapter.yaml",
+  "adapter_config": { "token": "YOUR_TOKEN" },
+  "message": "list workspaces",
+  "abilities": ["workspaces:read"]
+}
+```
+
+## Integration test (Tenant Kit)
+
+With [Tenant Kit](https://github.com/mohammedelkarsh/laravel-tenant-kit) running:
+
+```bash
+python scripts/integration_tenant_kit.py
+# Docker on port 8080:
+python scripts/integration_tenant_kit.py --base-url http://laravel-tenant-kit.test:8080
+```
+
+Optional pytest marker (requires env vars):
+
+```bash
+export TENANT_KIT_BASE_URL=http://laravel-tenant-kit.test
+export TENANT_KIT_API_TOKEN=your-token
+pytest -m integration -q
+```
+
+## Tests
+
+```bash
+pytest -q
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` for local defaults (`api_operator_PLANNER`, port, etc.).
+
+## Architecture
+
+```
+api-operator (core)          your projects
+├── agent runtime               ├── adapter.yaml
+├── mock + yaml adapters        ├── openapi.yaml
+└── scaffold / generate CLI     └── HTTP APIs (Laravel, Go, …)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

api_operator-0.9.0/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-0.9.0/api_operator/adapters/__init__.py

@@ -0,0 +1 @@
+

api_operator-0.9.0/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-0.9.0/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