docs

src/file_cache.py

@@ -1,10 +1,39 @@
-# file_cache.py
-"""
-Stub — the Anthropic Files API path has been removed.
-All context is now sent as inline chunked text via _send_anthropic_chunked.
-This file is kept so that any stale imports do not break.
 """
+File Cache - ASTParser (tree-sitter) for Python source code analysis.
 
+This module provides AST-based code analysis using the tree-sitter library.
+ It is used to generate compressed "views" of Python code that preserve
+ structure while reducing token consumption.
+
+Key Components:
+ - ASTParser: Main parser class using tree-sitter
+ - get_skeleton(): Compress function bodies to `...`
+ - get_curated_view(): Preserve `@core_logic` and `[HOT]` functions
+ - get_targeted_view(): Extract only specified symbols + dependencies
+
+Caching:
+ - Module-level `_ast_cache` stores parsed trees with mtime invalidation
+ - Cache limit: 10 entries (simple LRU eviction)
+ - Cache key: file path + mtime
+
+Thread Safety:
+ - Not thread-safe. Use separate ASTParser instances per thread.
+ - Cache is module-level shared across instances.
+
+Views:
+ 1. Skeleton: Signatures + docstrings only, bodies replaced with `...`
+ 2. Curated: Skeleton + bodies marked with `@core_logic` or `[HOT]`
+ 3. Targeted: Only specified symbols + their dependencies (depth 2)
+
+Integration:
+ - Used by mcp_client.py for py_get_skeleton, py_get_curated_view
+ - Used by multi_agent_conductor.py for worker context injection
+ - Used by aggregate.py for summary generation
+
+See Also:
+ - docs/guide_tools.md for AST tool documentation
+ - src/summarize.py for heuristic summaries
+"""
 from pathlib import Path
 from typing import Optional, Any, List, Tuple, Dict
 import tree_sitter