Skip to content

API.md

Latest commit

 

History

History
55 lines (42 loc) · 2.4 KB

API.md

File metadata and controls

55 lines (42 loc) · 2.4 KB
Raw

API Service

The api/ directory contains a FastAPI-based HTTP service that wraps all arag-cli commands as REST APIs via async subprocess calls.

Architecture

api/
├── app/
│   ├── main.py           # FastAPI entry: middleware, route registration, /health, global exception handling
│   ├── api/v1/arag.py    # REST endpoint definitions (/arag/*)
│   ├── tools/arag_cli.py # Async subprocess wrapper: invokes arag-cli binary via asyncio
│   ├── schemas/arag.py   # Pydantic request/response models
│   └── core/             # Configuration and logging
├── Dockerfile            # Multi-stage build: compile Rust binary first, then install Python dependencies
├── start.sh              # uvicorn startup script
├── requirements.txt      # Python dependencies
└── tests/                # API tests

How It Works

app/tools/arag_cli.py invokes arag-cli --format json <subcommand> via asyncio.create_subprocess_exec, parses stdout JSON, and returns the result. The API layer handles:

  • Request validation (Pydantic models)
  • Unified response format (AragResponse: code / data / text / message / request_id)
  • Latency logging (JSONL format) and exception-to-HTTP error code mapping (408 timeout / 503 runtime error)

All endpoints support the ?format=text parameter to convert results into LLM-readable text format.

Endpoint Mapping

Category HTTP Endpoint CLI Command
Retrieval POST /arag/keyword-search, POST /arag/semantic-search, POST /arag/search keyword-search, semantic-search, search
Read POST /arag/read-chunk read-chunk
Notes POST /arag/note (action: add/show/list/remove/export) note subcommands
KB Operations POST /arag/pin, GET /arag/pin-candidates, POST /arag/lint, POST /arag/cache pin, pin-candidates, lint, cache
Diagnostics GET /arag/history, GET /arag/profile, GET /arag/health history, profile, health
Service GET /health Aggregated service status + CLI health check

Startup

cd api && pip install -r requirements.txt
# Ensure arag-cli is in PATH and set ARAG_EMBEDDING_* environment variables
./start.sh   # Default listens on 0.0.0.0:8080

Docker

docker build -f api/Dockerfile .
docker run -p 8080:8080 <image>