316 lines
10 KiB
Markdown
316 lines
10 KiB
Markdown
# Build Spec Phase 4 — Support Bot Foundation
|
|
|
|
**Date:** 2026-06-22
|
|
**Design:** Pi
|
|
**Build:** Claude Code
|
|
**Est:** 1 session
|
|
**Depends on:** Phase 3 (startup ritual) complete — shared-context pointers wired
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Phase 4 builds the foundation for a support bot by generating a machine-readable API reference from the backend source and cross-referencing it with the existing support manual. This enables automated troubleshooting support and sets up the data layer the bot will query.
|
|
|
|
Two substeps:
|
|
|
|
- **4.1** — Write `gen-api-ref.py` script to parse FastAPI routes from `main.py`
|
|
- **4.2** — Cross-reference `support-manual.md` with generated ref, fix gaps
|
|
|
|
---
|
|
|
|
## 4.1 Generate support-api-ref.json
|
|
|
|
### File to create
|
|
|
|
`signal/scripts/gen-api-ref.py`
|
|
|
|
### What to build
|
|
|
|
A Python script that:
|
|
|
|
1. Reads `python-backend/api/main.py`
|
|
2. Parses the AST for FastAPI route decorators (`@app.get`, `@app.post`, `@app.put`, `@app.delete`, `@app.patch`, `@router.*`)
|
|
3. Extracts for each route:
|
|
- Path (e.g., `/api/upload-csv`)
|
|
- HTTP method (GET, POST, etc.)
|
|
- Summary (first line of function docstring)
|
|
- Parameters (from function signature — path params, query params, body params)
|
|
- Response codes and descriptions (from `raise HTTPException(...)` calls in function body, plus the implicit 200)
|
|
4. Writes `signal/docs/support-api-ref.json`
|
|
|
|
### AST parsing approach
|
|
|
|
Use Python's `ast` module (stdlib — no external dependencies). Parse for:
|
|
|
|
- `@app.<method>` decorators and `@router.<method>` decorators
|
|
- Extract the route string from the decorator argument
|
|
- Get the function name from the decorated `FunctionDef`
|
|
- Extract docstring first line for summary
|
|
- Scan `raise` statements inside the function body for `HTTPException(status_code=...)`
|
|
- Detect `Request` and `UploadFile` params for the parameters list
|
|
|
|
### Expected output
|
|
|
|
```json
|
|
{
|
|
"generated": "2026-06-22",
|
|
"source": "python-backend/api/main.py",
|
|
"endpoints": [
|
|
{
|
|
"path": "/api/health",
|
|
"method": "GET",
|
|
"summary": "Health check endpoint",
|
|
"parameters": [],
|
|
"responses": [
|
|
{"code": 200, "description": "Service healthy"}
|
|
]
|
|
},
|
|
{
|
|
"path": "/api/upload-csv",
|
|
"method": "POST",
|
|
"summary": "Upload and process a CSV file",
|
|
"parameters": [
|
|
{"name": "file", "in": "formData", "type": "file", "required": true}
|
|
],
|
|
"responses": [
|
|
{"code": 200, "description": "CSV processed successfully"},
|
|
{"code": 400, "description": "Invalid CSV format or missing columns"},
|
|
{"code": 401, "description": "Invalid or missing API key"},
|
|
{"code": 500, "description": "Server error processing CSV"}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Script structure
|
|
|
|
```python
|
|
#!/usr/bin/env python3
|
|
"""Generate support-api-ref.json from FastAPI backend source."""
|
|
import ast
|
|
import json
|
|
from pathlib import Path
|
|
|
|
BACKEND_DIR = Path(__file__).parent.parent / "python-backend"
|
|
OUTPUT = Path(__file__).parent.parent / "docs" / "support-api-ref.json"
|
|
MAIN_FILE = BACKEND_DIR / "api" / "main.py"
|
|
|
|
# Route decorator prefixes to match
|
|
HTTP_METHODS = {"get", "post", "put", "delete", "patch", "options", "head"}
|
|
|
|
# Known module names that may contain route definitions
|
|
SHARED_ROUTER_MODULES = [
|
|
"api.routes",
|
|
]
|
|
|
|
|
|
def extract_route(node):
|
|
"""Given a decorator Call node, return (method, path) or None."""
|
|
# Handle @app.get, @router.post, etc.
|
|
if (isinstance(node.func, ast.Attribute)
|
|
and isinstance(node.func.value, ast.Name)
|
|
and node.func.attr in HTTP_METHODS):
|
|
path = node.args[0].value if node.args else ""
|
|
return node.func.attr.upper(), path
|
|
return None
|
|
|
|
|
|
def extract_summary(docstring):
|
|
"""Get the first line of a docstring."""
|
|
if not docstring:
|
|
return ""
|
|
lines = docstring.strip().split("\n")
|
|
return lines[0].strip()
|
|
|
|
|
|
def extract_error_codes(body):
|
|
"""Scan a function body for HTTPException raises and extract status codes."""
|
|
codes = [{"code": 200, "description": "Success"}]
|
|
for node in ast.walk(body):
|
|
if (isinstance(node, ast.Raise)
|
|
and isinstance(node.exc, ast.Call)
|
|
and isinstance(node.exc.func, ast.Name)
|
|
and node.exc.func.id == "HTTPException"):
|
|
for kw in node.exc.keywords:
|
|
if kw.arg == "status_code" and isinstance(kw.value, ast.Constant):
|
|
detail = ""
|
|
for kw2 in node.exc.keywords:
|
|
if kw2.arg == "detail" and isinstance(kw2.value, ast.Constant):
|
|
detail = kw2.value.value
|
|
break
|
|
codes.append({
|
|
"code": kw.value.value,
|
|
"description": detail or f"HTTP {kw.value.value}"
|
|
})
|
|
return codes
|
|
|
|
|
|
def extract_function_parameters(func_def):
|
|
"""Extract parameter info from a function definition."""
|
|
params = []
|
|
for arg in func_def.args.args:
|
|
arg_name = arg.arg
|
|
if arg_name == "request":
|
|
params.append({"name": arg_name, "in": "path", "type": "Request", "required": True})
|
|
elif arg_name in ("file", "csv_file"):
|
|
params.append({"name": arg_name, "in": "formData", "type": "file", "required": True})
|
|
else:
|
|
params.append({"name": arg_name, "in": "query", "type": "string", "required": False})
|
|
return params
|
|
|
|
|
|
def parse_file(filepath):
|
|
"""
|
|
Parse a single Python file for FastAPI route decorators.
|
|
Returns list of endpoint dicts.
|
|
"""
|
|
endpoints = []
|
|
tree = ast.parse(filepath.read_text())
|
|
|
|
for node in ast.walk(tree):
|
|
if not isinstance(node, ast.FunctionDef):
|
|
continue
|
|
|
|
func_def = node
|
|
for decorator in func_def.decorator_list:
|
|
route = extract_route(decorator)
|
|
if route:
|
|
method, path = route
|
|
endpoints.append({
|
|
"path": path,
|
|
"method": method,
|
|
"summary": extract_summary(ast.get_docstring(func_def)),
|
|
"parameters": extract_function_parameters(func_def),
|
|
"responses": extract_error_codes(func_def),
|
|
})
|
|
|
|
return endpoints
|
|
|
|
|
|
def main():
|
|
endpoints = parse_file(MAIN_FILE)
|
|
|
|
# Optional: scan shared router modules
|
|
# for module_name in SHARED_ROUTER_MODULES:
|
|
# module_path = BACKEND_DIR / module_name.replace(".", "/") + ".py"
|
|
# if module_path.exists():
|
|
# endpoints.extend(parse_file(module_path))
|
|
|
|
output = {
|
|
"generated": "2026-06-22",
|
|
"source": str(MAIN_FILE.relative_to(BACKEND_DIR.parent)),
|
|
"endpoints": endpoints,
|
|
}
|
|
|
|
OUTPUT.parent.mkdir(parents=True, exist_ok=True)
|
|
OUTPUT.write_text(json.dumps(output, indent=2) + "\n")
|
|
print(f"Generated {len(endpoints)} endpoints → {OUTPUT}")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|
|
```
|
|
|
|
### Verification
|
|
|
|
```bash
|
|
python3 signal/scripts/gen-api-ref.py
|
|
cat signal/docs/support-api-ref.json | python3 -c "
|
|
import json,sys; d=json.load(sys.stdin)
|
|
print(f'{len(d[\"endpoints\"])} endpoints extracted from {d[\"source\"]}')
|
|
for ep in d['endpoints']:
|
|
codes = [str(r['code']) for r in ep['responses']]
|
|
print(f' {ep[\"method\"]:6} {ep[\"path\"]:30} → {ep[\"summary\"][:40]} [{','.join(codes)}]')
|
|
"
|
|
```
|
|
|
|
### Acceptance
|
|
|
|
- [ ] Script runs without external dependencies (stdlib only)
|
|
- [ ] Output file written to `signal/docs/support-api-ref.json`
|
|
- [ ] All real API endpoints extracted (health, upload, export, etc.)
|
|
- [ ] Error codes from `raise HTTPException(...)` captured
|
|
- [ ] Parameter lists populated
|
|
|
|
---
|
|
|
|
## 4.2 Cross-reference support-manual.md with API ref
|
|
|
|
### What to do
|
|
|
|
1. Read both `signal/docs/support-manual.md` and the generated `support-api-ref.json`
|
|
2. For each endpoint in the API ref, check the support manual for:
|
|
- Does the manual mention this endpoint? If not, add a section or a link
|
|
- Do the error messages in the manual's tables match the actual HTTPException codes from the API ref?
|
|
- Do the parameter descriptions match what the backend actually accepts?
|
|
3. Add a note at the top of `support-manual.md` noting the generation timestamp:
|
|
|
|
```markdown
|
|
*Auto-generated API reference: signal/docs/support-api-ref.json (generated YYYY-MM-DD)*
|
|
```
|
|
|
|
1. Add any missing endpoints to the manual as a section:
|
|
|
|
```markdown
|
|
---
|
|
## [METHOD] /api/endpoint-name
|
|
|
|
**Summary:** description
|
|
|
|
**Error codes:**
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 200 | Success |
|
|
| 4xx | Error type |
|
|
```
|
|
|
|
### Verification
|
|
|
|
```bash
|
|
# Count endpoints in API ref
|
|
ENDPOINTS=$(python3 -c "import json; d=json.load(open('signal/docs/support-api-ref.json')); print(len(d['endpoints']))")
|
|
# Count sections in support manual that mention endpoints
|
|
MANUAL_COVERAGE=$(grep -c '/api/' signal/docs/support-manual.md)
|
|
echo "API ref: $ENDPOINTS endpoints, Manual covers: $MANUAL_COVERAGE /api/ references"
|
|
```
|
|
|
|
If `MANUAL_COVERAGE` is significantly less than `ENDPOINTS`, more manual sections are needed.
|
|
|
|
### Acceptance
|
|
|
|
- [ ] support-manual.md has a generation timestamp note at the top
|
|
- [ ] All API ref endpoints have a corresponding section in the manual
|
|
- [ ] Error code tables in the manual match the actual codes from the API ref
|
|
- [ ] No stale/incorrect error descriptions in the manual
|
|
|
|
---
|
|
|
|
## Implementation Order
|
|
|
|
1. Write `signal/scripts/gen-api-ref.py`
|
|
2. Run it to generate `signal/docs/support-api-ref.json`
|
|
3. Read the generated ref alongside the manual
|
|
4. Update `signal/docs/support-manual.md`:
|
|
- Add generation timestamp note
|
|
- Add missing endpoint sections
|
|
- Fix any error code mismatches
|
|
5. Commit both files
|
|
|
|
## Completion Report Template
|
|
|
|
```markdown
|
|
### Phase 4 (Support Bot Foundation)
|
|
|
|
#### 4.1 API ref generation
|
|
- [ ] gen-api-ref.py written to signal/scripts/
|
|
- [ ] Runs with stdlib only (no pip install)
|
|
- [ ] support-api-ref.json generated with all N endpoints
|
|
|
|
#### 4.2 Manual cross-reference
|
|
- [ ] Generation timestamp added to support-manual.md
|
|
- [ ] All endpoints cross-referenced
|
|
- [ ] Error codes match between manual and API ref
|
|
```
|