Metadata-Version: 2.4
Name: wacp
Version: 2.0.0
Summary: WACP — turn any backend into an AI-agent-friendly system via /ai/* endpoints.
License: MIT
Project-URL: Changelog, https://github.com/your-org/ai-web/blob/main/sdk/CHANGELOG.md
Keywords: ai,sdk,wacp,fastapi,agent,api,llm
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Framework :: FastAPI
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: uvicorn[standard]>=0.22.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"

# WACP Python SDK (`wacp`)

**Version: 2.0.0**

```bash
pip install wacp
```

One package for Python. Framework adapters live in submodules:

```python
from wacp.fastapi import wacp_router
# later: from wacp.flask import ...
# later: from wacp.django import ...
```

Full changelog: [../CHANGELOG.md](../CHANGELOG.md)

---

## Quick start (FastAPI)

```python
from fastapi import FastAPI
from wacp.fastapi import wacp_router

app = FastAPI()

# ... your normal routes ...

app.include_router(
    wacp_router(
        app,
        base_dir="ai",       # folder with config/ + docs/
        discover=True,       # optional: write config/_discovered.json
    )
)
```

If `ai/config/` does not exist, the SDK **auto-scaffolds** starter JSON files on first boot.

---

## Package layout

```text
wacp/
  core/          # config, scaffold, search, types (shared)
  fastapi/       # FastAPI adapter (wacp_router, discovery)
  # flask/       # planned
  # django/      # planned
```

---

## `base_dir` layout

```text
ai/
  config/
    main.json
    categories.json
    endpoints.json
    docs.json
    custom-map.json
    _discovered.json        # only when discover=True (never served / never merged)
  docs/
    overview.md
```

Optional: set `files.search_vocabulary` in `main.json` to a JSON file under `config/` for org-specific synonym overrides.

---

## Routes

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/ai` | Entry: app info, navigation, quick access |
| GET | `/ai/all` | Flat list of endpoints (`?page=&limit=` optional) |
| GET | `/ai/category` | Category index |
| GET | `/ai/category/{id}` | Endpoints in a category |
| GET | `/ai/endpoint/{id}` | Full endpoint detail |
| GET | `/ai/docs` | Docs index |
| GET | `/ai/docs/{filename}` | Raw doc content |
| GET | `/ai/search?q=` | Lexical search |

---

## Discovery (`discover=True`)

```python
from wacp.fastapi import wacp_router, FastAPIDiscovery
```

- Writes `base_dir/config/_discovered.json`
- Never served by `/ai`, never merged into `endpoints.json`
- Scaffold runs before discovery on a fresh `base_dir`

---

## Search & pagination

Lightweight lexical search via `GET /ai/search?q=...`.  
List routes accept optional `?page=&limit=`.

---

## Versioning

**2.0.0** — see [CHANGELOG](../CHANGELOG.md) and `wacp.__version__`.

---

## License

MIT
