dullfig/xml-pipeline
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add Librarian endpoints to agentserver API spec

Browse source 
Documents REST API for Premium Librarian codebase intelligence:

Data models:
- Library (ingested codebase metadata)
- Chunk (code fragment with location and type)

Endpoints:
- GET/POST /librarian/libraries - list/ingest libraries
- GET/DELETE /librarian/libraries/{id} - get/delete library
- POST /librarian/libraries/{id}/query - RAG query with sources
- GET /librarian/libraries/{id}/chunks/{chunk_id} - get code chunk

Includes full request/response examples for each endpoint.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
dullfig 2026-01-27 23:15:42 -08:00
parent d6a0efc064
commit 6023e92ab0
1 changed files with 188 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

188
docs/agentserver_api_spec.md
View file

@ -81,6 +81,43 @@ The agentserver is the backend for monitoring and controlling an xml-pipeline or
}
```
### Library (Codebase Intelligence)
```json
{
"library_id": "fastapi-abc12345",
"name": "fastapi",
"source_url": "https://github.com/tiangolo/fastapi.git",
"created_at": "2024-01-15T10:00:00Z",
"total_files": 142,
"total_chunks": 890,
"stats": {
"functions": 234,
"classes": 45,
"lang_python": 890
}
}
```
### Chunk (Code Fragment)
```json
{
"chunk_id": "fastapi/routing.py:APIRouter:a1b2c3d4",
"library_id": "fastapi-abc12345",
"file_path": "fastapi/routing.py",
"name": "APIRouter",
"chunk_type": "class",
"language": "python",
"start_line": 150,
"end_line": 320,
"signature": "class APIRouter(routing.Router)",
"docstring": "A router for grouping path operations."
}
```
**Chunk types:** `function`, `method`, `class`, `module`, `section`, `block`
**Languages:** `python`, `javascript`, `typescript`, `cpp`, `c`, `rust`, `go`, `java`, `markdown`, `unknown`
---
## REST API
@ -142,6 +179,157 @@ Response:
}
```
### Librarian (Codebase Intelligence)
RAG-powered codebase intelligence. Ingest git repositories, chunk code intelligently, and query with natural language.
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/librarian/libraries` | GET | List all ingested libraries |
| `/librarian/libraries` | POST | Ingest a new codebase |
| `/librarian/libraries/{id}` | GET | Get library details and index |
| `/librarian/libraries/{id}` | DELETE | Delete a library |
| `/librarian/libraries/{id}/query` | POST | Query library with natural language |
| `/librarian/libraries/{id}/chunks/{chunk_id}` | GET | Get specific code chunk |
#### GET /librarian/libraries
List all ingested libraries.
Response:
```json
{
"libraries": [
{
"library_id": "fastapi-abc12345",
"name": "fastapi",
"source_url": "https://github.com/tiangolo/fastapi.git",
"created_at": "2024-01-15T10:00:00Z",
"total_files": 142,
"total_chunks": 890
}
],
"count": 1
}
```
#### POST /librarian/libraries
Ingest a git repository.
Request:
```json
{
"git_url": "https://github.com/tiangolo/fastapi.git",
"branch": "main",
"library_name": "fastapi"
}
```
Response:
```json
{
"library_id": "fastapi-abc12345",
"library_name": "fastapi",
"files_processed": 142,
"chunks_created": 890,
"index_built": true,
"errors": []
}
```
#### GET /librarian/libraries/{id}
Get library index with structural information.
Response:
```json
{
"library_id": "fastapi-abc12345",
"name": "fastapi",
"source_url": "https://github.com/tiangolo/fastapi.git",
"created_at": "2024-01-15T10:00:00Z",
"files": ["fastapi/main.py", "fastapi/routing.py", ...],
"functions": {
"get_swagger_ui_html": "fastapi/openapi/docs.py",
"get_redoc_html": "fastapi/openapi/docs.py"
},
"classes": {
"FastAPI": "fastapi/applications.py",
"APIRouter": "fastapi/routing.py"
},
"stats": {
"chunks": 890,
"files": 142,
"functions": 234,
"classes": 45,
"lang_python": 890
}
}
```
#### POST /librarian/libraries/{id}/query
Query a library with natural language. Uses RAG to search relevant chunks and synthesize an answer.
Request:
```json
{
"question": "How does dependency injection work in FastAPI?",
"max_chunks": 20,
"model": "grok-4.1"
}
```
Response:
```json
{
"answer": "FastAPI implements dependency injection through the `Depends` function...",
"sources": [
{
"file_path": "fastapi/dependencies/utils.py",
"name": "solve_dependencies",
"chunk_type": "function",
"start_line": 45,
"end_line": 120,
"relevance_score": 0.95,
"snippet": "async def solve_dependencies(..."
},
{
"file_path": "fastapi/params.py",
"name": "Depends",
"chunk_type": "class",
"start_line": 10,
"end_line": 35,
"relevance_score": 0.88,
"snippet": "class Depends:..."
}
],
"tokens_used": 2450,
"chunks_examined": 15
}
```
#### GET /librarian/libraries/{id}/chunks/{chunk_id}
Retrieve a specific code chunk (for viewing full source).
Response:
```json
{
"chunk_id": "fastapi/routing.py:APIRouter:a1b2c3d4",
"file_path": "fastapi/routing.py",
"name": "APIRouter",
"chunk_type": "class",
"language": "python",
"start_line": 150,
"end_line": 320,
"content": "class APIRouter:\n \"\"\"...",
"docstring": "A router for grouping path operations.",
"signature": "class APIRouter(routing.Router)"
}
```
---
## WebSocket API