**Context Compiler: Shrinking Python Prompts by 70% with a Three‑Pass Build**
In modern AI-assisted coding, context windows feel both infinite and fragile. Vendors quietly change the limits, and even when they grow, each extra token spent on irrelevant code competes with the signal the model actually needs. One way to regain control is to treat prompt construction like a compiler: instead of retrieving a broad set of files and hoping the model can “find” the right thing, you resolve what actually matters, strip it down to interfaces, and exclude everything else. That is the premise behind the Context Compiler—a three-pass pipeline written in pure Python using only the standard library.
The pipeline has three stages. First, Pass 1 performs symbol resolution by tracing imports from the target file and expanding outward via a repo‑wide symbol table up to a configurable hop limit. This phase catches dynamic dispatch where static analysis fails and explicitly reports gaps rather than guessing. Second, Pass 2 skeletonizes reachable but non‑target files, keeping function signatures and docstrings while replacing every body with a placeholder. This preserves what an agent needs to know—types, defaults, and semantics—without burning context on internals. Third, Pass assembles a three‑tier context: full source for the file being edited, skeletonized interfaces for dependencies, and an explicit exclude list for everything else, along with token counts and warnings for unresolved patterns.
In practice, the approach is materially different from a flat repo dump or a simple file list. Because unreachable files are never included—even as skeletons—the prompt can be dramatically smaller without losing correctness. Across two real Python repositories, the compiler reduced prompt sizes by 69–74% and built the trimmed context in under 75 ms. These numbers come from captured terminal runs, and where certainty is missing the tool reports an unknown instead of guessing.
The design embraces explicit trade‑offs. With max_hops=2 as a balanced default, the pipeline flags dynamic dispatch, event‑style registration, and name collisions so the agent knows exactly where static analysis ends. Name collisions, for example, cause both conflicting implementations to be included rather than silently dropping one—an intentional safe failure mode. The implementation intentionally avoids a full type‑checker to remain dependency‑free and fast, accepting some false positives in favor of determinism and simplicity.
The result is a lean, explainable context set that stays within tight limits while still conveying the correct API surface. If your agent recently failed because it was overwhelmed by unrelated code, this approach directly addresses that problem. If it failed due to vague instructions, the issue lies elsewhere. Context compilation will not fix every prompt engineering challenge, but it reliably removes a major and common one: irrelevant context competing for attention.
