Skip to main content

​
Search

Ground uses hybrid search combining vector similarity with full-text search for optimal retrieval.

​
How It Works

​
1. Query Embedding

Your search query is converted into a vector embedding using the same model used for indexing content. pgvector finds the most similar chunks using cosine similarity: 
SELECT * FROM chunks
ORDER BY embedding <=> query_embedding
LIMIT 50

​
3. Full-Text Search

PostgreSQL’s full-text search finds keyword matches: 
SELECT * FROM chunks
WHERE to_tsvector('english', content) @@ plainto_tsquery('english', query)

​
4. Score Fusion

Results are combined using weighted scores: 
combined_score = 0.7 × vector_score + 0.3 × text_score

​
5. Policy Application

The trust policy applies:
  • Source priority weights (boost OpenAPI results for API questions)
  • Staleness filtering (exclude or warn about stale results)
  • Refusal thresholds (refuse to answer with insufficient evidence)

​
Search Request

curl "https://api.trygroundai.com/search?query=how+to+authenticate&top_k=10&max_tokens=4000"
Parameters:
  • query: Search query (required)
  • source_ids: Filter to specific sources (optional)
  • top_k: Maximum results (default: 10, max: 50)
  • max_tokens: Token budget for results (default: 4000)
  • include_stale: Include stale results with warning (default: true)

​
Search Response

{
  "results": [
    {
      "content": "...",
      "score": 0.85,
      "token_count": 150,
      "citation": {
        "chunk_id": "...",
        "source_id": "...",
        "source_name": "My API",
        "path": "/api/auth/login",
        "symbol": "POST",
        "version_ref": "v2.3.0",
        "language": "openapi",
        "chunk_type": "openapi"
      },
      "freshness_days": 5.2,
      "is_stale": false
    }
  ],
  "total_results": 10,
  "total_tokens": 1500,
  "sources_searched": 3,
  "sources_with_results": 2,
  "evidence_quality": {
    "score": 0.72,
    "evidence_count": 10,
    "avg_freshness_days": 8.5,
    "has_conflicts": false,
    "confidence": "high"
  },
  "staleness_summary": {
    "total_sources": 3,
    "fresh_sources": 2,
    "stale_sources": 1,
    "staleness_budget_days": 30,
    "stale_source_names": ["Old Docs"]
  },
  "conflicts": [],
  "warnings": [],
  "query": "how to authenticate",
  "search_time_ms": 45
}

​
Evidence Quality

Ground computes an evidence quality score based on:
  • Score distribution: Higher average scores = better quality
  • Evidence count: More results = more confidence (up to a point)
  • Freshness: Fresher sources = higher quality
  • Conflicts: Conflicts reduce quality score
  • Source type: OpenAPI chunks get a small boost for API questions
Confidence levels:
  • high: score ≥ 0.7
  • medium: score ≥ 0.5
  • low: score ≥ 0.3
  • insufficient: score < 0.3

​
No Evidence Response

When no relevant content is found: 
{
  "message": "No relevant evidence found",
  "query": "something obscure",
  "sources_searched": 5,
  "suggestions": [
    "Try a broader or different query",
    "Check if relevant sources are synced"
  ]
}