# 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
