Skip to content

API.md

Latest commit

 

History

History
197 lines (149 loc) · 4.01 KB

API.md

File metadata and controls

197 lines (149 loc) · 4.01 KB
Raw

Grimoire Retriever API Documentation

This document provides comprehensive documentation for the Grimoire Retriever REST API.

Base URL

By default, the API runs at http://localhost:8000.

Authentication

Currently, the API does not require authentication. For production deployments, consider adding API key authentication.

Endpoints

Health Check

GET /health

Returns the health status of the API.

Response:

{
    "status": "healthy",
    "version": "0.1.0"
}

Query Lore

POST /query

Query the lore database with a natural language question.

Request Body:

{
    "question": "Who is the Dragon Queen?",
    "top_k": 5,
    "include_sources": true
}
Field Type Required Default Description
question string Yes - Natural language question about your lore
top_k integer No 5 Number of source chunks to retrieve
include_sources boolean No true Whether to include source snippets in response

Response:

{
    "answer": "The Dragon Queen is Empress Valdris, ruler of the Eastern Realms...",
    "sources": [
        {
            "content": "Empress Valdris, known as the Dragon Queen, ascended to power...",
            "metadata": {
                "source": "lore/characters/valdris.md",
                "chunk_index": 0
            },
            "relevance_score": 0.92
        }
    ],
    "query_time_ms": 145
}

Error Responses:

  • 400 Bad Request: Invalid query parameters
  • 500 Internal Server Error: Processing error

Ingest Documents

POST /ingest

Ingest markdown documents into the vector database.

Request Body:

{
    "path": "./lore",
    "recursive": true,
    "chunk_size": 512,
    "chunk_overlap": 50
}
Field Type Required Default Description
path string Yes - Path to markdown file or directory
recursive boolean No true Recursively process subdirectories
chunk_size integer No 512 Maximum tokens per chunk
chunk_overlap integer No 50 Overlap tokens between chunks

Response:

{
    "status": "success",
    "documents_processed": 15,
    "chunks_created": 87,
    "processing_time_ms": 2340
}

Get Collection Stats

GET /stats

Get statistics about the current document collection.

Response:

{
    "total_documents": 15,
    "total_chunks": 87,
    "embedding_model": "sentence-transformers/all-MiniLM-L6-v2",
    "collection_name": "grimoire_lore"
}

Error Handling

All error responses follow this format:

{
    "detail": "Error description",
    "error_code": "ERROR_CODE",
    "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

Code Description
INVALID_QUERY The query was empty or malformed
COLLECTION_NOT_FOUND No documents have been ingested yet
EMBEDDING_ERROR Failed to generate embeddings
SYNTHESIS_ERROR Failed to synthesize answer

Rate Limiting

No rate limiting is enforced by default. For production, consider using a reverse proxy with rate limiting.

Examples

Python (requests)

import requests

# Query lore
response = requests.post(
    "http://localhost:8000/query",
    json={
        "question": "What are the magical properties of moonstone?",
        "top_k": 3
    }
)
result = response.json()
print(result["answer"])

cURL

curl -X POST http://localhost:8000/query \
    -H "Content-Type: application/json" \
    -d '{"question": "Tell me about the Forgotten War"}'

JavaScript (fetch)

const response = await fetch('http://localhost:8000/query', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        question: 'Who founded the Mage Academy?',
        top_k: 5
    })
});
const data = await response.json();
console.log(data.answer);