Skip to content

AI-Box Endpoints

The AI-Box service provides a comprehensive FastAPI interface for hybrid search, evidence retrieval, and AI model inference. This page documents all available endpoints with examples.

Service Details

  • Service Name: AI-Box Service (v0.1)
  • Framework: Python 3.11 / FastAPI
  • Description: Small, typed FastAPI service that powers evidence retrieval for the platform. Implements hybrid BM25 + kNN → RRF with optional reranker toggle.
  • Base URL: http://localhost:8001 (development)
  • Languages: Arabic/English ready

Core Endpoints

GET /health

Returns service information and health status.

Response: 

{"status":"ok","service":"ai-box","version":"0.1.0"}

Example: 

curl -s localhost:8001/health

GET /metrics

Prometheus exposition format with per-route counters, latency histograms, and retrieval timers.

Key Metrics: - aibox_requests_total{route,method,code} - Request counters - aibox_request_duration_seconds{route} - Latency histograms - aibox_retrieval_rrf_ms - RRF fusion timing

Grafana Queries: 

# Request rate
rate(aibox_requests_total{route="/retrieve"}[5m])

# P95 latency
histogram_quantile(0.95, rate(aibox_request_duration_seconds_bucket{route="/retrieve"}[5m]))

Normalized search results matching the platform API schema. Supports filters on category, domain, source_tier, and returns meta.taxonomy_version when available.

Retrieval Endpoints

POST /retrieve

Hybrid retrieval with RRF fusion and optional rerank. Combines BM25 (keyword-based) and k-NN (semantic) search.

Request Body: 

{
  "query": "انتخابات سوريا 2025",
  "lang": "ar",
  "k_bm25": 20,           // 0 to skip BM25
  "k_knn": 20,            // 0 to skip kNN
  "k_rrf": 60,
  "rerank": false,
  "fields": null,
  "filters": {
    "search_fields": ["title^2","body"],   // default if omitted
    "index": "news_docs",                  // auto-set from env if omitted
    "vector_field": "embedding",           // auto-set from env if omitted
    "term": { "term": { "lang": "en" } }   // optional BM25 filter
  }
}

Response: 

{
  "query": "انتخابات سوريا 2025",
  "params": {"k_bm25":20,"k_knn":20,"k_rrf":60,"rerank":false},
  "results": [
    {
      "doc_id": "3",
      "title": "Exploring Neural Search",
      "passage": "Neural search combines vector search...",
      "url": "https://…",
      "published_at": "2025-01-01T00:00:00Z",
      "source": "Example",
      "bm25_rank": null,
      "knn_rank": 1,
      "rrf_score": 0.0161,
      "final_rank": 1,
      "highlights": {"body": ["<em>neural</em> search combines ..."] }
    }
  ],
  "diagnostics": {"bm25_ms": 5.0, "knn_ms": 4.8, "rrf_ms": 0.01, "rerank_ms": 0.0}
}

AI Model Endpoints

POST /s1/check-worthiness

Sentence-level check-worthiness analysis using XLM-RoBERTa. Also available as /s1/score alias.

Request Body (Option 1 - Single Text): 

{"text": "وزارة الصحة أعلنت ارتفاع عدد الإصابات إلى 25."}

Request Body (Option 2 - Multiple Sentences): 

{"sentences":["وزارة الصحة أعلنت ارتفاع عدد الإصابات إلى 25.","المباراة كانت ممتعة."]}

Response: 

{
  "results": [
    {
      "sentence": "وزارة الصحة أعلنت ارتفاع عدد الإصابات إلى 25.",
      "score": 0.87,
      "is_checkworthy": true
    },
    {
      "sentence": "المباراة كانت ممتعة.",
      "score": 0.23,
      "is_checkworthy": false
    }
  ],
  "model_id": "/models/xlm-roberta-large-xnli",
  "threshold_used": 0.55
}

Performance: On CPU, p95 latency for eight sentences is ~0.1s.

Usage Examples

BM25 Only Search (English)

curl -s localhost:8001/retrieve -H 'content-type: application/json' \
  -d '{"query":"neural search","lang":"en","k_bm25":20,"k_knn":0,"k_rrf":60,"rerank":false}'

Hybrid Search (Arabic Query)

curl -s localhost:8001/retrieve -H 'content-type: application/json' \
  -d '{"query":"انتخابات سوريا 2025","lang":"ar","k_bm25":20,"k_knn":20,"k_rrf":60,"rerank":false}'

Language Filter (Restrict to English Documents)

curl -s localhost:8001/retrieve -H 'content-type: application/json' \
  -d '{"query":"neural","lang":"en","k_bm25":20,"k_knn":20,"k_rrf":60,"filters":{"term":{"term":{"lang":"en"}}}}'

Check-Worthiness Analysis

curl -s -X POST localhost:8001/s1/check-worthiness \
  -H 'content-type: application/json' \
  -d '{"sentences":["وزارة الصحة أعلنت ارتفاع عدد الإصابات إلى 25.","المباراة كانت ممتعة."]}'

Interactive API Console