FastContext Agent — exploration repo
Un sous-agent d'exploration déterministe qui sépare la collecte de contexte
du raisonnement. Au lieu de laisser l'agent principal dépenser 56% de ses
tokens en READ/GLOB/GREP, FastContext gère ça en ~5ms, 0 token.
Inspiré par Microsoft FastContext-1.0-4B-SFT mais 100% déterministe
(stdlib Python, pas de LLM, pas de GPU).
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
| Type |
Mots-clés |
Action |
IMPORTS |
import, dependency, require |
grep imports + suggest files |
FUNCTION |
function, method, def, understand |
grep def → contexte fichier |
TESTS |
test, spec, unittest |
glob test_* + grep |
PATTERN |
pattern, usage, find, where |
grep générique |
SECURITY |
security, audit, eval, malicious |
grep dangereux |
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) │
└─────────────────────────────────┘
Économie tokens estimée
| Type requête |
Avant (LLM) |
Après (FastContext) |
Économie |
| Imports |
~800 tokens |
0 token |
-100% |
| Comprendre fonction |
~1200 tokens |
0 token |
-100% |
| Trouver tests |
~400 tokens |
0 token |
-100% |
| Pattern search |
~600 tokens |
0 token |
-100% |
| Audit sécurité |
~2000 tokens |
0 token |
-100% |
~5000 tokens/session économisés (estimé sur 5 explorations par session).
Pitfalls
- 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.
- 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.
- Gros repos — Pour les repos >1000 fichiers,
fast_grep utilise
subprocess.run("grep -rl ...") plutôt qu'un glob Python (10x plus rapide).
- Binaire/symlinks — Skip automatiquement les fichiers binaires, .git/,
node_modules/, pycache/, .venv/.
1---2name: fast-context3description: FastContext Agent — exploration repo déterministe. Parse une requête d'exploration → READ/GLOB/GREP ciblés → rapport compact (fichier:ligne:score). Remplace 56% des appels LLM de type "read/search" par des opérations stdio à ~5ms, 0 token. Use when the agent needs to understand a codebase, find patterns, locate imports, or gather context without an LLM call.4---56# FastContext Agent — exploration repo78Un sous-agent d'exploration déterministe qui sépare la **collecte de contexte**9du **raisonnement**. Au lieu de laisser l'agent principal dépenser 56% de ses10tokens en READ/GLOB/GREP, FastContext gère ça en **~5ms, 0 token**.1112Inspiré par **Microsoft FastContext-1.0-4B-SFT** mais 100% déterministe13(stdlib Python, pas de LLM, pas de GPU).1415## Usage1617```bash18# Explorer un dossier19python -m skills.fast_context.cli explore /path/to/project "find DB connection patterns"2021# Types de requête supportés22python -m skills.fast_context.cli explore . "find all imports in main.py"23python -m skills.fast_context.cli explore . "understand function: calibrate()"24python -m skills.fast_context.cli explore . "where are the tests?"25python -m skills.fast_context.cli explore . "queue usage patterns"26python -m skills.fast_context.cli explore . "audit security: eval, exec, shell"2728# Mode verbeux29python -m skills.fast_context.cli explore . "find async patterns" --verbose3031# Limiter les résultats32python -m skills.fast_context.cli explore . "import pathlib" --max-results 103334# Utiliser le cache35python -m skills.fast_context.cli explore . "class FastContext" --cache36```3738## API Python3940```python41from skills.fast_context import explore, cached_explore42from skills.fast_context import discover_query_type, QueryType4344# Exploration simple45results = explore(".", "find DB connection patterns")46# → [{"file": "src/db.py:15", "snippet": "...", "score": 0.92, "type": "import"}, ...]4748# Avec cache49results = cached_explore(".", "find async patterns", ttl=60)5051# Découverte du type de requête52qt = discover_query_type("find all imports")53# → QueryType.IMPORTS54```5556## Types de requête5758| Type | Mots-clés | Action |59|------|-----------|--------|60| `IMPORTS` | import, dependency, require | grep imports + suggest files |61| `FUNCTION` | function, method, def, understand | grep def → contexte fichier |62| `TESTS` | test, spec, unittest | glob test_* + grep |63| `PATTERN` | pattern, usage, find, where | grep générique |64| `SECURITY` | security, audit, eval, malicious | grep dangereux |6566## Architecture6768```69FastContext Agent70 ┌─────────────────────────────────┐71 │ agent.py │72 │ - discover_query_type(query) │73 │ - explore(query, path) → list │74 ├─────────────────────────────────┤75 │ readers.py │76 │ - fast_read(file, lines) │77 │ - fast_glob(pattern, root) │78 │ - fast_grep(pattern, root) │79 ├─────────────────────────────────┤80 │ ranker.py │81 │ - score(file, match, query) │82 │ - rank_results(results) │83 ├─────────────────────────────────┤84 │ compiler.py │85 │ - compile_report(results) │86 │ - format_compact(results) │87 ├─────────────────────────────────┤88 │ store.py │89 │ - LRUCache(ttl=30) │90 └─────────────────────────────────┘91```9293## Économie tokens estimée9495| Type requête | Avant (LLM) | Après (FastContext) | Économie |96|-------------|-------------|-------------------|----------|97| Imports | ~800 tokens | 0 token | -100% |98| Comprendre fonction | ~1200 tokens | 0 token | -100% |99| Trouver tests | ~400 tokens | 0 token | -100% |100| Pattern search | ~600 tokens | 0 token | -100% |101| Audit sécurité | ~2000 tokens | 0 token | -100% |102103**~5000 tokens/session** économisés (estimé sur 5 explorations par session).104105## Pitfalls1061071. **Ne remplace pas LLM pour compréhension complexe** — FastContext livre du108 contexte brut (fichier:ligne:snippet). Le LLM principal doit encore raisonner109 dessus. C'est le but : le LLM ne fait QUE raisonner.1102. **Cache TTL** — Le cache LRU évite de rescanner 30 fois le même fichier dans111 la même session. TTL par défaut: 30s. Passer `--no-cache` pour forcer.1123. **Gros repos** — Pour les repos >1000 fichiers, `fast_grep` utilise113 `subprocess.run("grep -rl ...")` plutôt qu'un glob Python (10x plus rapide).1144. **Binaire/symlinks** — Skip automatiquement les fichiers binaires, .git/,115 node_modules/, __pycache__/, .venv/.
zedarvates