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).
