Python API

Everything RCE Code does is reached through one class: CodeEngine, the public facade over an index. It owns the SQLite database, the embedder, and the lexical, semantic, symbol, hybrid, and grep searchers, and exposes them as plain methods. This page documents every public method — exact signature, return type, and behavior — followed by the dataclasses those methods return.

Import the facade and the data types from the package root:

from rce.code import (
    CodeEngine, CodeConfig,
    SearchResult, Chunk, Symbol, Reference, GrepHit, IndexStats,
    ChunkKind, SymbolKind, SearchSource, Freshness,
)

Lifecycle

open_or_create is the sole constructor. It builds a CodeConfig if you do not pass one, opens the SQLite database, and runs migrations before returning a ready instance.

Indexing

index() builds (and incrementally updates) the index; refresh() is an alias of it; embed() fills in vector embeddings for chunks that lack a current one. See the Indexing Pipeline for what each stage does.

Search

Four query paths over the indexed corpus. The three search_* methods return SearchResult lists ranked by score; grep runs live ripgrep over the working tree and returns GrepHit lists. See Search & Retrieval for when to reach for each.

Structural

Symbol- and reference-level queries over the resolved call graph. Methods that take a symbol_id expect the id of a Symbol you already have (typically from find_symbol or get_definitions). See Symbols & References.

Discovery

File-level helpers for listing and reading source. find_files and read_file work against the working tree on disk; list_files reads the set of files already in the index.

Repo map

A single method produces an Aider-style, relevance-ranked map of the codebase, fit to a token budget. See Repo Map.

Health

Return types

All return types are frozen dataclasses (and string enums) from rce.code.types. The tables below cover the fields you will use most; every dataclass is immutable.

SearchResult

Returned by search_lexical, search_semantic, and search_hybrid.

Chunk

A stored chunk — the unit of retrieval. Reached via SearchResult.chunk.

Symbol

A stored symbol definition. Returned by find_symbol, get_definitions, get_definition_at, get_symbols_in_chunk, get_callers, and get_callees.

Reference

A stored reference (call or import). Returned by find_references, get_references_from, and get_references.

GrepHit

Returned by grep — one per matching line.

IndexStats

Returned by stats().

IndexSummary

Returned by index() and refresh() — the result of one indexing run.

Freshness

Carried on every SearchResult as result.freshness.

End-to-end examples

Open or create an index, build it, embed pending chunks, and run each modality:

from rce.code import CodeEngine

engine = CodeEngine.open_or_create("/path/to/repo")

# Build (or incrementally update) the index, then embed pending chunks.
summary = engine.index()
print(f"indexed {summary.files_indexed}, deleted {summary.files_deleted}")
engine.embed()

# Lexical, semantic, and hybrid search all return list[SearchResult].
for hit in engine.search_hybrid("authentication middleware", top_k=5):
    c = hit.chunk
    print(round(hit.score, 3), hit.source, f"{c.file_path}:{c.start_line}", c.name)

# Live grep over the working tree (keyword-only options).
for h in engine.grep("TODO", glob="*.py", max_count=10):
    print(f"{h.file_path}:{h.line}:{h.column}  {h.line_text}")

# Repo map fit to a token budget.
print(engine.build_repo_map(focused_files=["src/auth.py"], token_budget=1024))

engine.close()

Walk the call graph from a named definition — resolve the symbol, then ask for its callers and callees:

from rce.code import CodeEngine, SymbolKind

engine = CodeEngine.open_or_create("/path/to/repo")
engine.index()

for sym in engine.find_symbol("login", kind=SymbolKind.FUNCTION):
    print("definition:", sym.qualified_name, f"{sym.file_path}:{sym.start_line}")

    for caller in engine.get_callers(sym.id):
        print("  called by:", caller.qualified_name)
    for callee in engine.get_callees(sym.id):
        print("  calls:", callee.qualified_name)

    # Incoming resolved references vs. outgoing references from the body.
    print("  incoming refs:", len(engine.get_references(sym.id)))
    print("  outgoing refs:", len(engine.get_references_from(sym.id)))

engine.close()