brokk-bifrost-searchtools

Fast, structured code search and analysis for Python, backed by a native Rust extension. This is the Python distribution of bifrost, the Tree-sitter-backed analyzer suite that powers Brokk.

It gives you one in-process client that talks straight to the Rust analyzer (no subprocess, no MCP server) and returns typed results plus ready-to-render text. It understands Java, JavaScript, TypeScript, Rust, Go, Python, C++, C#, PHP, and Scala.

  • Install: pip install brokk-bifrost-searchtools
  • Import as: bifrost_searchtools

What it does

Index a project once, then ask fast structural questions:

  • Symbol search: find classes, functions, and fields by name pattern.
  • Locations and sources: jump to a symbol's definition or pull its source.
  • Summaries: get a signature-level outline of a file or directory.
  • Usages and call graph: scan references to a symbol, or build the whole-workspace caller/callee graph (feed it to PageRank for a code map).
  • Most-relevant files: rank the files most related to one or more seed files.
  • Semantic search: find code by meaning, using ONNX embeddings and a cross-encoder reranker (opt-in).

Quick start

from bifrost_searchtools import SearchToolsClient

with SearchToolsClient("/path/to/project") as client:
    # Signature-level outline of a file
    print(client.get_summaries(["src/main.py"]).render_text())

    # Find symbols by name pattern
    for file in client.search_symbols(["parse_*"], limit=10).files:
        print(file.path)

    # Rank the files most related to a seed file
    print(client.most_relevant_files(["src/main.py"]).render_text())

The client indexes on first use, keeps the index warm for the session, and watches the filesystem so later queries see your edits. Every result has typed fields plus a render_text() helper.

For a runnable end-to-end demo, examples/searchtools_demo.py declares its dependency inline (PEP 723), so uv fetches the package and runs it with no manual install:

uv run examples/searchtools_demo.py --root /path/to/repo Calculator compute

API overview

SearchToolsClient(root, library_path=None, render_line_numbers=True, manual=False) exposes:

Method Purpose
search_symbols(patterns, *, include_tests=False, limit=20) Find symbols by name pattern.
search_ast(pattern, *, inside=None, not_inside=None, where=None, languages=None, limit=None, result_detail=None, schema_version=None) Search normalized AST structure across supported languages.
get_symbol_locations(symbols, *, kind_filter=...) Resolve symbols to definition sites.
get_symbol_ancestors(symbols, *, kind_filter=...) Walk the enclosing type/scope chain.
get_symbol_sources(symbols, *, kind_filter=...) Pull full source for symbols.
get_definition_by_location(path, *, line=..., column=...) Resolve a reference at a known file location.
get_definition_by_reference(symbol, *, context=..., target=...) Resolve a copied reference inside a symbol source block.
get_type_by_location(path, *, line=..., column=...) Resolve the type of an expression or identifier at a known file location.
get_summaries(targets) Signature-level outline of files / classes / directories.
list_symbols(file_patterns) Skim the symbols declared in matching files.
scan_usages(symbols, *, include_tests=False, paths=None) Find references to a symbol.
rename_symbol(path, *, line=..., column=..., new_name=...) Return a non-mutating edit plan for a symbol rename.
usage_graph(*, include_tests=False, paths=None) Whole-workspace caller/callee graph; each edge carries its {path, line} call sites.
most_relevant_files(seed_files, *, limit=20, ...) Rank files related to seed files.
semantic_search(query, *, k=10) Meaning-based code search (opt-in).
semantic_search_status() Report whether the semantic index is ready.
refresh() Force a full re-index (recovery escape hatch).
update_paths(paths) Incrementally re-analyze specific paths (with manual=True).
activate_workspace(path) / get_active_workspace() Switch / read the active workspace root.
get_file_contents(file_paths) Read whole files by path.
find_filenames(patterns, *, limit=None) Find files by path glob.
search_file_contents(patterns, *, file_path=None, context_lines=None, case_insensitive=False) Grep contents with context.
find_files_containing(patterns, *, limit=None, case_insensitive=False) Find files whose contents match.
list_files(directory_path="", *, max_entries=None) List files under a directory.
get_git_log(*, file_path=None, limit=None) Recent commits (optionally for one path).
get_commit_diff(revision, *, max_files=None, lines_per_file=None) Unified diff for a commit.
search_git_commit_messages(pattern, *, limit=None) Regex search over commit messages.
jq(file_path, filter_expr, *, max_files=None, matches_per_file=None) Run a jq filter over JSON files.
xml_skim(file_path, *, max_files=None) Summarize XML element structure.
xml_select(file_path, xpath, *, output=XmlSelectOutput.TEXT, attr_name=None, max_files=None) Evaluate an XPath over XML files.
compute_cyclomatic_complexity(file_paths, *, threshold=None) Per-function cyclomatic complexity.
compute_cognitive_complexity(file_paths, *, threshold=None) Per-function cognitive complexity.
report_comment_density_for_code_unit(fq_name, *, max_lines=None) Comment density for one symbol.
report_comment_density_for_files(file_paths, *, max_top_level_rows=None, max_files=None) Comment density per file.
report_exception_handling_smells(file_paths, *, min_score=None, max_findings=None, options=None) Suspicious exception handlers.
report_test_assertion_smells(file_paths, *, min_score=None, max_findings=None, options=None) Low-value test assertions.
report_structural_clone_smells(file_paths, *, min_score=None, max_findings=None, options=None) Structural code clones.
report_long_method_and_god_object_smells(file_paths, *, max_findings=None, max_files=None, options=None) Oversized functions / god objects.
report_dead_code_and_unused_abstraction_smells(*, file_paths=None, fq_names=None, min_score=None, max_findings=None, options=None) Likely dead code (Rust).
report_secret_like_code(*, max_findings=None, max_commits=None, include_history_only=False, include_low_confidence=False) Secret-looking strings in files / history.
analyze_git_hotspots(*, since_days=None, since_iso=None, until_iso=None, max_commits=None, max_files=None) Churn × complexity hotspots.

Pass render_line_numbers=False to drop line numbers from rendered text while keeping the structured line metadata on the result objects.

The git tools return a GitTextResult (.text), the slopcop tools return a CodeQualityReport (.report), and the rest return structured dataclasses from bifrost_searchtools.models. The per-rule tuning knobs on the smell reports are passed through options (keys map 1:1 to the Rust tool arguments).

search_ast detail and ranges

search_ast is an experimental v1 query surface. Omit schema_version for v1 or pass schema_version=1 explicitly when callers want to pin the shape. Compact output is the default: matches include project-relative path, language, normalized kind, line range, a short snippet, captures, and an enclosing symbol when available. Pass result_detail="full" when a rule, refactoring step, or follow-up tool call needs precise locations. Full detail adds deterministic match ids plus byte offsets and 1-based character columns for matches and captures.

For decorated or annotated declarations, node_range is the matched normalized node's parser-backed range. decorator_ranges are the decorator or annotation role spans extracted by the language adapter. decorated_range is the union of node_range and those decorator ranges. Matching semantics are unchanged by requesting full detail; these fields only make the span policy explicit.

Current structural precision

search_ast normalizes common syntax across Python, Java, JavaScript, and TypeScript, but it is still a syntactic structural search tool. Use these caveats when writing reusable rules or prompts:

Area Current behavior
Constructor calls Java object creation and JS/TS new expressions are normalized as call; constructors are also refined as constructor declarations where the adapter can identify them.
Keyword arguments Python supports kwargs; Java, JavaScript, and TypeScript currently report unsupported-role diagnostics for kwargs.
Imports and aliases Import matching is based on syntactic module/import spans. It does not resolve aliases or follow re-exports.
Receiver and callee callee.name and receiver.name are derived from AST fields and terminal names, not type resolution. Chained calls stay syntactic.
Decorators and annotations Decorators/annotations are exposed through the decorators role. Full detail reports node_range, decorator_ranges, and decorated_range.
Positional arguments args patterns match positional arguments in order as a subsequence; v1 does not require exact positions or arity.
Unsupported capabilities Queries against unsupported normalized kinds or roles return diagnostics instead of silently pretending the language can answer them.

Semantic search

semantic_search(...) searches code by meaning rather than name and returns the three retrieval legs directly: function-oriented vector and BM25 rankings over function-level chunks, plus a file-oriented co-edit ranking. It searches code, not prose.

It is opt-in. Set BIFROST_SEMANTIC_INDEX=auto to enable background indexing; the models load via ONNX and download from the HuggingFace hub on first use. The main bifrost README lists every environment override.

License

LGPL-3.0-or-later. See LICENSE.md.

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.8.24)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for brokkai from gravatar.com brokkai Avatar for DavidBakerEffendi_Brokk from gravatar.com DavidBakerEffendi_Brokk

Credits

Author: Brokk

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

LGPL-3.0-or-later
View SPDX License List

Requires

Python >=3.12

Tags

code-analysis tree-sitter code-search semantic-search static-analysis symbols

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

brokk_bifrost_searchtools-0.7.3.tar.gz (2.2 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

brokk_bifrost_searchtools-0.7.3-cp312-abi3-win_amd64.whl (12.4 MB view details)

Uploaded CPython 3.12+Windows x86-64

brokk_bifrost_searchtools-0.7.3-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (13.2 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ x86-64

brokk_bifrost_searchtools-0.7.3-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (13.0 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ ARM64

brokk_bifrost_searchtools-0.7.3-cp312-abi3-macosx_11_0_arm64.whl (12.4 MB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

brokk_bifrost_searchtools-0.7.3-cp312-abi3-macosx_10_12_x86_64.whl (12.7 MB view details)

Uploaded CPython 3.12+macOS 10.12+ x86-64

File details

Details for the file brokk_bifrost_searchtools-0.7.3.tar.gz.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.7.3.tar.gz
Algorithm Hash digest
SHA256 2b4f74e13f114644e41d4fa21fbf035c0ee17d4af6d7430cd9221f1d74bf5e4f
MD5 d1713ba18fd9fa65b06cc5877efdeca2
BLAKE2b-256 7a5f3aa217fb8d8bdd1da8f8fa6dd7ba0e994c5b39242e97dd93481e76e287f9

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.7.3.tar.gz:

Publisher: publish-wheels.yml on BrokkAi/bifrost

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file brokk_bifrost_searchtools-0.7.3-cp312-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.7.3-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 c713e7cc2efaf4ab1826d19ab1dac921848dc487d9aa7a39f1f81e05e63d0fbd
MD5 5b15cf43c5e74ad09f9aba1523576b20
BLAKE2b-256 26bf2208b4afc1e13eabd41b703e506eb5de1497141d8873e456fe6daa920982

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.7.3-cp312-abi3-win_amd64.whl:

Publisher: publish-wheels.yml on BrokkAi/bifrost

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file brokk_bifrost_searchtools-0.7.3-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.7.3-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 53b0487c3bf26ab4c69919f2d7f182ccc35bf4674262c89c3eebf42dad8bfcd5
MD5 a131029e643f1280ab934005ac88eb97
BLAKE2b-256 b190277d16b4592fc7a58447cbe8798640b0ad153ace4a5e6a9540fedca9ddf0

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.7.3-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-wheels.yml on BrokkAi/bifrost

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file brokk_bifrost_searchtools-0.7.3-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.7.3-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 9ed2346fc18d4cb66c95a1d1ebb9b9bcf4d66d6e4257c76f97c9286985a95f67
MD5 6e4aee9b010bd4c4b72cde3e22d98789
BLAKE2b-256 c7aa9c83f12474833a79b3eb7f3db6fdab3eedfcab65817f0c577fc9f60e6a2b

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.7.3-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-wheels.yml on BrokkAi/bifrost

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file brokk_bifrost_searchtools-0.7.3-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.7.3-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7b4b69bee747dd3f5080b164175888cf9656dcb8727e334902f42efb38770634
MD5 2c0819e1fd8a0225c642e9bd5660b502
BLAKE2b-256 a277e5f7ef9845f413fbd45191603369563c8451bff86cdfce8cbac553ffecc2

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.7.3-cp312-abi3-macosx_11_0_arm64.whl:

Publisher: publish-wheels.yml on BrokkAi/bifrost

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file brokk_bifrost_searchtools-0.7.3-cp312-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.7.3-cp312-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 7847db1edbeb7284c95200918463ed4f333421b5d0bef75332b9d9c5b0cc525e
MD5 a5fb1216e37c6ecb3e4cc84e9794c335
BLAKE2b-256 6f9d1a6333cd887acaf010e7da752d7c41034a1ff64adbb192f26ccedd4399cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.7.3-cp312-abi3-macosx_10_12_x86_64.whl:

Publisher: publish-wheels.yml on BrokkAi/bifrost

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page