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.
query_code(pattern, *, inside=None, not_inside=None, where=None, languages=None, steps=None, limit=None, result_detail=None, schema_version=None) Query normalized code structure and apply typed declaration, hierarchy, ownership, and import steps.
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_definitions_by_location([{"path": ..., "line": ..., "column": ...}]) Resolve references at known file locations.
get_definitions_by_reference([{"symbol": ..., "context": ..., "target": ...}]) Resolve copied references inside symbol source blocks.
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_by_reference(symbols, *, include_tests=False, paths=None) Find references to known symbols.
scan_usages_by_location(targets, *, include_tests=False, paths=None) Find references from declaration line/column targets.
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).

query_code detail and ranges

query_code is the version-2 typed query surface. Omit schema_version for v2 or pass schema_version=2 explicitly. The structural pattern can be followed by ordered steps using enclosing_decl, file_of, imports_of, importers_of, supertypes, subtypes, members, and owner. Import operations traverse one direct project-local edge per step. Hierarchy operations are direct by default and accept a positive depth or transitive: true. Declaration results are limited to declarations indexed by the workspace analyzer, so references into an unindexed library do not manufacture library declarations. Results are tagged as structural matches, declarations, or files. Compact output retains minimal pipeline provenance. Pass result_detail="full" when follow-up tooling needs deterministic IDs and precise ranges.

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

query_code normalizes common syntax across Python, Java, JavaScript, TypeScript, Go, C/C++, Rust, PHP, Scala, C#, and Ruby, but it is still a syntactic structural query tool. Use these caveats when writing reusable rules or prompts; the public Code Querying guide is the canonical reference:

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, PHP, Scala, C#, and Ruby support normalized kwargs; other adapters report unsupported-role diagnostics.
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; v2 does not require exact positions or arity.
Typed pipelines Declaration, hierarchy, and ownership steps preserve exact indexed identities; import steps follow direct workspace file edges and may be repeated.
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 semantic search docs list 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.8.2.tar.gz (3.6 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.8.2-cp312-abi3-win_amd64.whl (14.4 MB view details)

Uploaded CPython 3.12+Windows x86-64

brokk_bifrost_searchtools-0.8.2-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.1 MB view details)

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

brokk_bifrost_searchtools-0.8.2-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (14.9 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ ARM64

brokk_bifrost_searchtools-0.8.2-cp312-abi3-macosx_11_0_arm64.whl (14.1 MB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

brokk_bifrost_searchtools-0.8.2-cp312-abi3-macosx_10_12_x86_64.whl (14.6 MB view details)

Uploaded CPython 3.12+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.8.2.tar.gz
Algorithm Hash digest
SHA256 9579139eecefc445b4dd49c5a27f3a93f6a9a58505fd23466fe8519e20599807
MD5 a82636e0f5f21089c3f35e1d6e787762
BLAKE2b-256 d52283fe9d2004b8ff1147e6c8fc04829c242d14d4d5d754e51b059ae293262d

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.8.2.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.8.2-cp312-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.8.2-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 1705a6a6d972fdcbcb1cc9a4bbf6772d81b5b56e4d5839ef9231cda8c6b48a51
MD5 c61d6beaa687b114757240f712be2d8c
BLAKE2b-256 3067603b5ee0ad963bd786bd58ec5d51f9ddda5779033ac3ea8d651b30e986a4

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.8.2-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.8.2-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.8.2-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 810aa7fe93e2d7d8f6193bb11b6de53c149f1eae3fd7b7954fa01486673fc5d6
MD5 3ca1f607d97e443befaeb9f3d5fadfd6
BLAKE2b-256 1a834a4170a030dce4f3d60388c72ccaf6291aff65b1b81bf3259ffe01d907e5

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.8.2-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.8.2-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.8.2-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 6f8d2cd8c1a78c3cdd75c84b122458d2f97c5ad5340a607c4b94a9184ec4ada2
MD5 985eb21578834ead99b2f06fada0a00d
BLAKE2b-256 5d07b9b8327f4395d4a4b69a630c9ad2902f88ed8ab1f704dcd90bce44c9a424

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.8.2-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.8.2-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.8.2-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 843ecc0ec445c260a4b9dba1ed70b8eb0d1c64114ee769feabbe82f58446932b
MD5 0d9f1d7daa26646e9b5aa166239e8a7d
BLAKE2b-256 2a4d4b4124e0410cc26ce90133f07eb7a3d5e5cae04616086bf92011a0864935

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.8.2-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.8.2-cp312-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for brokk_bifrost_searchtools-0.8.2-cp312-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 77d03f41f9d023d96cd73db6793a8de7e829b917b2672dea852160cf1901e54c
MD5 470737263d00301ab9aa1dfcb34a51b5
BLAKE2b-256 654abbeb79ca40bdf86128643e5285b3dd2edd11ce55f284877669187b799214

See more details on using hashes here.

Provenance

The following attestation bundles were made for brokk_bifrost_searchtools-0.8.2-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