Results and AST Models

Unless a module path is shown, the types on this page can be imported directly from contextcraft.

Compilation results

class contextcraft.CompilationResult(root_path: 'str', output_format: 'OutputFormat', content: 'str', stats: 'CompilationStats', files: 'list[FileAnalysis]')

property markdown: str

property text_content: str

Field	Meaning
root_path	Resolved repository root as a string
output_format	Selected OutputFormat
content	Complete formatted artifact
stats	CompilationStats for this compilation
files	Analyzed files, including files selected at TREE fidelity

markdown and text_content are aliases for content, not format converters.

class contextcraft.OutputFormat(*values)

JSON = 'json'

MARKDOWN = 'markdown'

XML = 'xml'

Statistics

CompilationStats is a Pydantic model with the following fields. Use result.stats.model_dump() for a dictionary or model_dump_json() for JSON.

Field	Meaning
total_files_discovered	Files discovered during scanning
binary_files_skipped	Files skipped as binary
ignored_files_skipped	Files skipped by filtering or scan constraints
files_compiled	Number of analyzed files, including TREE selections
raw_tokens	Sum of the analyzed files’ FULL tier token counts
compressed_tokens	Token count of the complete formatted artifact
tree_overhead_tokens	Token count of the directory tree
budget_tokens	Requested token budget
budget_utilization_pct	Artifact tokens divided by budget, times 100
compression_ratio	Raw tokens divided by artifact tokens (1.0 if no raw tokens)
token_savings_pct	Percentage reduction from raw tokens to artifact tokens
fidelity_counts	File counts by fidelity badge (TREE, SIGS, SKEL, FULL)
total_symbols_extracted	Number of extracted symbols
total_public_signatures	Number of public symbols
preserved_public_signatures	Public symbols in files selected at SIGS or higher
preserved_signatures_pct	Fidelity-based public-symbol retention estimate, times 100
secrets_redacted	Number of detected secrets redacted
execution_time_ms	Compilation duration in milliseconds

Raw tokens are counted after redaction. Artifact counts include formatting overhead, so token savings can be negative for small inputs.

File analysis

class contextcraft.FileAnalysis(rel_path: 'str', abs_path: 'str', language: 'str', size_bytes: 'int', parsed: 'ParsedAst', tiers: 'dict[FidelityLevel, RenderedTier]'=<factory>, pagerank_score: 'float' = 0.0, relevance_boost: 'float' = 1.0, selected_fidelity: 'FidelityLevel' = <FidelityLevel.TREE: 0>, redacted_secrets: 'list[SecretMatch]' = <factory>)

property defined_identifiers: list[str]

property imports: list[str]

property raw_tokens: int

property redacted_secrets_count: int

property referenced_identifiers: list[str]

property selected_content: str

property selected_tokens: int

property symbols: list[Symbol]

property tier_tokens: dict[FidelityLevel, int]

parsed holds the byte-backed AST. tiers maps FidelityLevel to RenderedTier. pagerank_score and relevance_boost describe ranking; selected_fidelity identifies the tier chosen for output. imports returns import declaration text, while parsed.imports contains structured Import objects. redacted_secrets contains SecretMatch records.

Fidelity and token counting

class contextcraft.FidelityLevel(*values)

FULL = 3

SIGNATURES = 1

SKELETON = 2

TREE = 0

property badge: str

property semantic_utility: float

Level	Value	Content
TREE	0	Empty file content; path remains in the directory tree
SIGNATURES	1	Language-specific signatures or compact summary
SKELETON	2	Structural representation with implementation elided
FULL	3	Full source after optional redaction

class contextcraft.RenderedTier(content: 'str', tokens: 'int')

content is the rendered text and tokens is its token count.

class contextcraft.TokenCounter(encoding_name: str = 'cl100k_base')

Count with tiktoken, using deterministic estimates if loading or encoding fails.

Unknown encoding names raise ValueError rather than silently falling back. Offline estimates are not guaranteed to match the requested tokenizer.

count(text: str) → int

Uses the requested tiktoken encoding. An unknown encoding raises ValueError. If tokenization is unavailable or fails, counting falls back to a lexical/byte estimate.

class contextcraft.Elider(token_counter: TokenCounterProtocol | None = None)

render(parsed: ParsedAst, language: type[Language]) → dict[FidelityLevel, RenderedTier]

Build tiers with nondecreasing token costs from TREE through FULL.

Empty or more expensive summaries reuse the next higher tier. FULL is the exact parsed source, which the caller should sanitize before parsing.

render() produces all four tiers. Empty compressed output or a compressed tier larger than the next richer tier falls back to that richer tier. A custom counter only needs a count(text: str) -> int method, as specified by contextcraft.elider.TokenCounterProtocol.

AST data

All ranges are half-open UTF-8 byte offsets, not character indexes. Use ParsedAst.text() rather than slicing a decoded Python string with them. When redaction is enabled, ranges refer to the sanitized source.

class contextcraft.ByteRange(start_byte: int, end_byte: int)

Half-open byte offsets into ParsedAst.source, not character indices.

class contextcraft.Symbol(name: 'str | None', kind: 'str', declaration_range: 'ByteRange', signature_range: 'ByteRange', body_range: 'ByteRange | None' = None, docstring_range: 'ByteRange | None' = None, parent: 'Symbol | None' = None, is_public: 'bool' = True)

property qualified_name: str | None

A symbol describes its declaration, signature, optional body and docstring, parent, and public visibility. qualified_name joins named parents with dots; it is None for unnamed symbols.

class contextcraft.Import(module: 'str', declaration_range: 'ByteRange')

class contextcraft.ParsedAst(source: bytes, symbols: list[Symbol] = <factory>, imports: list[Import] = <factory>, scope_graph: ScopeGraph = <factory>, has_errors: bool = False, embedded_regions: list[EmbeddedRegion] = <factory>)

Source-backed declarations and scopes extracted from one UTF-8 document.

All ranges refer to these source bytes, after any secret sanitization. Embedded regions have their own ParsedAst with region-relative offsets.

property defined_identifiers: list[str]

property referenced_identifiers: list[str]

text(span: ByteRange) → str

source is UTF-8 bytes. symbols, imports, and scope_graph contain extracted structure. has_errors records parsing problems. embedded_regions contains contextcraft.ast.EmbeddedRegion values with a source range, language class, and a separately parsed AST; ranges inside that AST are local to its source.

Secret metadata

SecretMatch is a frozen Pydantic model. It records kind (SecretKind), a one-based line_number, redacted_placeholder, and masked_preview rather than the original secret value.

class contextcraft.SecretKind(*values)

ANTHROPIC_API_KEY = 'ANTHROPIC_API_KEY'

AWS_ACCESS_KEY = 'AWS_ACCESS_KEY'

ENV_SECRET_ASSIGNMENT = 'ENV_SECRET'

GENERIC_HIGH_ENTROPY = 'GENERIC_SECRET'

GITHUB_TOKEN = 'GITHUB_TOKEN'

GOOGLE_API_KEY = 'GOOGLE_API_KEY'

OPENAI_API_KEY = 'OPENAI_API_KEY'

PRIVATE_KEY_BLOCK = 'PRIVATE_KEY_BLOCK'

SLACK_TOKEN = 'SLACK_TOKEN'

STRIPE_KEY = 'STRIPE_KEY'