FastContext Agent — exploration repo

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

Un sous-agent d'exploration déterministe qui sépare la collecte de contexte du raisonnement. Les recherches locales peuvent réduire le contexte à fournir, mais leurs coûts et leur latence doivent être mesurés avec le runtime installé.

L'approche upstream est inspirée par Microsoft FastContext et utilise des recherches locales. Ce catalogue ne fournit ni son modèle ni son runtime.

Usage

# Explorer un dossier
python -m skills.fast_context.cli explore /path/to/project "find DB connection patterns"

# Types de requête supportés
python -m skills.fast_context.cli explore . "find all imports in main.py"
python -m skills.fast_context.cli explore . "understand function: calibrate()"
python -m skills.fast_context.cli explore . "where are the tests?"
python -m skills.fast_context.cli explore . "queue usage patterns"
python -m skills.fast_context.cli explore . "audit security: eval, exec, shell"

# Mode verbeux
python -m skills.fast_context.cli explore . "find async patterns" --verbose

# Limiter les résultats
python -m skills.fast_context.cli explore . "import pathlib" --max-results 10

# Utiliser le cache
python -m skills.fast_context.cli explore . "class FastContext" --cache

API Python

from skills.fast_context import explore, cached_explore
from skills.fast_context import discover_query_type, QueryType

# Exploration simple
results = explore(".", "find DB connection patterns")
# → [{"file": "src/db.py:15", "snippet": "...", "score": 0.92, "type": "import"}, ...]

# Avec cache
results = cached_explore(".", "find async patterns", ttl=60)

# Découverte du type de requête
qt = discover_query_type("find all imports")
# → QueryType.IMPORTS

Types de requête

Architecture

FastContext Agent
  ┌─────────────────────────────────┐
  │  agent.py                       │
  │  - discover_query_type(query)   │
  │  - explore(query, path) → list  │
  ├─────────────────────────────────┤
  │  readers.py                     │
  │  - fast_read(file, lines)       │
  │  - fast_glob(pattern, root)     │
  │  - fast_grep(pattern, root)     │
  ├─────────────────────────────────┤
  │  ranker.py                      │
  │  - score(file, match, query)    │
  │  - rank_results(results)        │
  ├─────────────────────────────────┤
  │  compiler.py                    │
  │  - compile_report(results)      │
  │  - format_compact(results)      │
  ├─────────────────────────────────┤
  │  store.py                       │
  │  - LRUCache(ttl=30)             │
  └─────────────────────────────────┘

Mesures

Comparer le contexte retourné, la qualité de recherche, la latence et la consommation réelle de l'agent. Aucun benchmark de gains n'est fourni dans ce catalogue.

Pitfalls

1. Ne remplace pas LLM pour compréhension complexe — FastContext livre du contexte brut (fichier:ligne:snippet). Le LLM principal doit encore raisonner dessus. C'est le but : le LLM ne fait QUE raisonner.
2. Cache TTL — Le cache LRU évite de rescanner 30 fois le même fichier dans la même session. TTL par défaut: 30s. Passer --no-cache pour forcer.
3. Gros repos — Pour les repos >1000 fichiers, fast_grep utilise subprocess.run("grep -rl ...") plutôt qu'un glob Python (mesurer les performances sur le dépôt concerné).
4. Binaire/symlinks — Skip automatiquement les fichiers binaires, .git/, node_modules/, pycache/, .venv/.