Get Started
DocsTrack 5architecture
/llms.txt
Under the Hood5 min readbrevio-core v0.11.1

PageRank Repository Map, What Runs Where & Known Limits

Plain-English Summary (For Anyone)

How brevio-core is built, what runs where, and where it stops

brevio-core is a standard-library Python package. The rules read text with fixed line patterns, the repository map ranks files with Personalized PageRank, and none of it calls a model. This page says what each part does and what it does not do.

Why this matters:
You can audit it: there is no dependency tree, no build step and no native code.
The limits are written down: line patterns are not AST or dataflow analysis, and precision is measured on TypeScript and JavaScript only.
The Brevio Harness is a separate product with its own architecture, described in its documentation; the research notes on this site are one project's measurements.
When to use:A reference for engineers and architects evaluating brevio-core's technical foundations.
Technical Contract (For Engineers)
Line-level rules
CLI Invocation Signature:
brevio-core map [--files F] [--budget 4000] [--json] | brevio-core rules --scanned
Latency / Execution
Not measured for 0.11.1
Token Cost
No model call. The map takes a token budget (default 4000).
Exit Codes
0 = success; 1 = findings (scan); 2 = usage error
Artifacts & Files Generated:
brevio-core.toml.brevio/guards.json
Visual Execution Pipeline
5-Stage Progressive Flow
01Local
Read
Read the added lines (scan --diff) or whole files, one file at a time
02No model call
Match
Apply the fixed line patterns of the rules
03PageRank
Rank
map: rank files by how they depend on each other, alpha 0.85
045 formats
Report
Text, Markdown, JSON, SARIF or one short line per finding for an agent

The Repository Dependency Graph

In Plain English:Code is a web of files that import each other. `brevio-core map` draws that web before it ranks anything.
`brevio-core map` reads `.py`, `.ts`, `.tsx`, `.js`, `.jsx`, `.go` and `.rs` files and skips folders such as node_modules, dist, build, .next and virtual environments. For Python it reads symbols with the standard-library ast module; for the other languages it uses regular expressions on import statements and declarations. Edges connect a file to the files it imports.

Personalized PageRank in the Map

In Plain English:The files you name are the starting point, and the map lists the files that matter most to them.
The ranking is Personalized PageRank over the file graph with damping alpha = 0.85 and at most 30 iterations. The seed files you pass with `--files` (or as positional arguments) shape the teleport vector, so files linked to your seeds rank higher. The output is the ranked files with their symbols, cut to `--budget` tokens.

What Runs Where, and What Sends Nothing

In Plain English:Most of brevio-core uses no network at all. The one exception is a model you connect yourself.
`scan`, the agent hook and the MCP server use no network and send nothing. The rules make no model call and need no API key. `brevio-core ai` is optional, off until you connect a model or a program, and sends a request only after you read it and answer yes. A program you connect may send the request elsewhere, which brevio-core does not see. Nothing goes to Brevio. The Brevio Harness is a separate product and runs on your own server with your own model keys.

Known Limits

In Plain English:Where brevio-core stops, so you know what else to keep in your pipeline.
The rules are line-level pattern checks and are TypeScript and React first. A mistake that needs the whole file, the types or the call graph is a job for your linter, type checker or code scanner. Precision is published for TypeScript and JavaScript only (human-written code; Python is not measured), and the R6.3 rule was below 70% in the sample. A scan of a whole folder reads old lines too; `scan --diff` reads only what a change adds. brevio-core is in Development Status 3 (Alpha) on PyPI.

Interactive Rule Explorer

Explore the brevio-core rules and load their examples into the panel on the right.

129 / 129 rules