Skip to main content
The Athena SDK includes a suite of command-line tools for search orchestration, automatic indexing, and system monitoring.

​
Available Tools

​
Search Tools

​
System Tools

  • Heartbeat - Auto-indexing file watcher daemon

​
Core Features

​
Parallel Execution

All tools use ThreadPoolExecutor for concurrent operations: 
from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor(max_workers=8) as executor:
    futures = [executor.submit(task) for task in tasks]
    results = [f.result() for f in futures]

​
Caching

Search results are cached both exactly (by query string) and semantically (by embedding similarity): 
from athena.core.cache import get_search_cache

cache = get_search_cache()
cache.set(query, results, embedding=query_embedding)

​
Debouncing

File system events are debounced to prevent redundant syncs during rapid edits (5-second window).

​
Architecture

​
Search Pipeline

  1. Collection - Gather candidates from multiple sources in parallel
  2. Fusion - Weighted Reciprocal Rank Fusion (RRF) to combine rankings
  3. Reranking (optional) - Semantic reranking with cross-encoder models
  4. Validation - Filter by confidence thresholds

​
Data Sources

The tools integrate with:
  • Supabase - Vector embeddings and structured data
  • SQLite - Local file index and tags
  • GraphRAG - Knowledge graph entities and communities
  • File System - Direct file content search

​
Configuration

All tools read from athena.core.config: 
from athena.core.config import (
    PROJECT_ROOT,
    TAG_INDEX_PATH,
    CANONICAL_PATH,
    CORE_DIRS,
)

​
CLI Usage

All tools can be invoked via the athena command: 
# Hybrid search
python -m athena.tools.search "trading psychology"

# Agentic search
python -m athena.tools.agentic_search "risk management and position sizing"

# Start heartbeat daemon
python -m athena.tools.heartbeat

​
Next Steps

Hybrid Search

Multi-source search with RRF fusion

Agentic Search

Query decomposition and validation

Heartbeat

Auto-indexing file watcher

Build docs developers (and LLMs) love

Get started for freeTalk to us