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.
`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.
`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).

Semantic search

semantic_search(...) finds files by meaning rather than name: function-level chunks are embedded, fused with BM25 and git co-edit signals, then reranked by a cross-encoder. 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.

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.6.7.tar.gz (1.5 MB view details)

Uploaded Jun 26, 2026 Source

Built Distributions

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

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

brokk_bifrost_searchtools-0.6.7-cp312-abi3-win_amd64.whl (11.6 MB view details)

Uploaded Jun 26, 2026 CPython 3.12+Windows x86-64

brokk_bifrost_searchtools-0.6.7-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.2 MB view details)

Uploaded Jun 26, 2026 CPython 3.12+manylinux: glibc 2.17+ x86-64

brokk_bifrost_searchtools-0.6.7-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (12.2 MB view details)

Uploaded Jun 26, 2026 CPython 3.12+manylinux: glibc 2.17+ ARM64

brokk_bifrost_searchtools-0.6.7-cp312-abi3-macosx_11_0_arm64.whl (11.6 MB view details)

Uploaded Jun 26, 2026 CPython 3.12+macOS 11.0+ ARM64

brokk_bifrost_searchtools-0.6.7-cp312-abi3-macosx_10_12_x86_64.whl (11.9 MB view details)

Uploaded Jun 26, 2026 CPython 3.12+macOS 10.12+ x86-64

File details

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

File metadata

Download URL: brokk_bifrost_searchtools-0.6.7.tar.gz
Upload date: Jun 26, 2026
Size: 1.5 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for brokk_bifrost_searchtools-0.6.7.tar.gz
Algorithm	Hash digest
SHA256	`2776378caeabb8dbb5f2da735d5a24d3b257bce506e2a53009fa988936828fd8`
MD5	`639c2a9f00f9516d80665e518911323d`
BLAKE2b-256	`5c3cb1e78b0b5fa47e8f570d2dff67b78688bb39e45ad1750516d38ae8dc34e9`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: brokk_bifrost_searchtools-0.6.7.tar.gz
- Subject digest: 2776378caeabb8dbb5f2da735d5a24d3b257bce506e2a53009fa988936828fd8
- Sigstore transparency entry: 1967113272
- Sigstore integration time: Jun 26, 2026
Source repository:
- Permalink: BrokkAi/bifrost@78d05cd120ff836d8c7df4fb60a511da1339abea
- Branch / Tag: refs/tags/v0.6.7
- Owner: https://github.com/BrokkAi
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-wheels.yml@78d05cd120ff836d8c7df4fb60a511da1339abea
- Trigger Event: push

File details

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

File metadata

Download URL: brokk_bifrost_searchtools-0.6.7-cp312-abi3-win_amd64.whl
Upload date: Jun 26, 2026
Size: 11.6 MB
Tags: CPython 3.12+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for brokk_bifrost_searchtools-0.6.7-cp312-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`34813be9db027abf6237e8038f55fb2cf886c6ff695327680eb4c7dc034b13a1`
MD5	`d580bbfd9da8a88e86dde17f5c7ccf80`
BLAKE2b-256	`41a978342c2e958006e68db8da26709cd87e8e92df9afb535513fdfbc41e9dc4`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: brokk_bifrost_searchtools-0.6.7-cp312-abi3-win_amd64.whl
- Subject digest: 34813be9db027abf6237e8038f55fb2cf886c6ff695327680eb4c7dc034b13a1
- Sigstore transparency entry: 1967114034
- Sigstore integration time: Jun 26, 2026
Source repository:
- Permalink: BrokkAi/bifrost@78d05cd120ff836d8c7df4fb60a511da1339abea
- Branch / Tag: refs/tags/v0.6.7
- Owner: https://github.com/BrokkAi
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-wheels.yml@78d05cd120ff836d8c7df4fb60a511da1339abea
- Trigger Event: push

File details

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

File metadata

Download URL: brokk_bifrost_searchtools-0.6.7-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jun 26, 2026
Size: 12.2 MB
Tags: CPython 3.12+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for brokk_bifrost_searchtools-0.6.7-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`194a6bb18894c9c271d27abd162f15bc3208d445b6dae65e0634e088a1bd7b8c`
MD5	`693dc97a33d9f436f2dd11abdcd776f2`
BLAKE2b-256	`6440a67b328112ca89d338349fcfd0c5d25b231496713d9ca59531b5c4fa63a0`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: brokk_bifrost_searchtools-0.6.7-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 194a6bb18894c9c271d27abd162f15bc3208d445b6dae65e0634e088a1bd7b8c
- Sigstore transparency entry: 1967113446
- Sigstore integration time: Jun 26, 2026
Source repository:
- Permalink: BrokkAi/bifrost@78d05cd120ff836d8c7df4fb60a511da1339abea
- Branch / Tag: refs/tags/v0.6.7
- Owner: https://github.com/BrokkAi
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-wheels.yml@78d05cd120ff836d8c7df4fb60a511da1339abea
- Trigger Event: push

File details

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

File metadata

Download URL: brokk_bifrost_searchtools-0.6.7-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Jun 26, 2026
Size: 12.2 MB
Tags: CPython 3.12+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for brokk_bifrost_searchtools-0.6.7-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`a699f742970824f64a9b330bb3acf6081e2f756bb27644eb6795830754d97c5d`
MD5	`fdc5117cb784c471e8f61b9481d63f5b`
BLAKE2b-256	`f7fe7a46062b31cf978dfb75a2c852ae5891984974ae7bd4856149519cc8025f`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: brokk_bifrost_searchtools-0.6.7-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: a699f742970824f64a9b330bb3acf6081e2f756bb27644eb6795830754d97c5d
- Sigstore transparency entry: 1967114209
- Sigstore integration time: Jun 26, 2026
Source repository:
- Permalink: BrokkAi/bifrost@78d05cd120ff836d8c7df4fb60a511da1339abea
- Branch / Tag: refs/tags/v0.6.7
- Owner: https://github.com/BrokkAi
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-wheels.yml@78d05cd120ff836d8c7df4fb60a511da1339abea
- Trigger Event: push

File details

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

File metadata

Download URL: brokk_bifrost_searchtools-0.6.7-cp312-abi3-macosx_11_0_arm64.whl
Upload date: Jun 26, 2026
Size: 11.6 MB
Tags: CPython 3.12+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for brokk_bifrost_searchtools-0.6.7-cp312-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`0ea020b0c29f6056dd37967c96a69d8ee72f68ef1e263dc8f9d8dcd0c74a7430`
MD5	`285013611e5fdeb1cebf22a611545b3f`
BLAKE2b-256	`a1445dbf3f0ec0bb895cd2d4742b707442624832be4ee46d7c86e40b2e5b86c3`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: brokk_bifrost_searchtools-0.6.7-cp312-abi3-macosx_11_0_arm64.whl
- Subject digest: 0ea020b0c29f6056dd37967c96a69d8ee72f68ef1e263dc8f9d8dcd0c74a7430
- Sigstore transparency entry: 1967113632
- Sigstore integration time: Jun 26, 2026
Source repository:
- Permalink: BrokkAi/bifrost@78d05cd120ff836d8c7df4fb60a511da1339abea
- Branch / Tag: refs/tags/v0.6.7
- Owner: https://github.com/BrokkAi
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-wheels.yml@78d05cd120ff836d8c7df4fb60a511da1339abea
- Trigger Event: push

File details

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

File metadata

Download URL: brokk_bifrost_searchtools-0.6.7-cp312-abi3-macosx_10_12_x86_64.whl
Upload date: Jun 26, 2026
Size: 11.9 MB
Tags: CPython 3.12+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for brokk_bifrost_searchtools-0.6.7-cp312-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`1817140d22711cf87d2900b61352068c547c944602c23721ea794bbacd5650e1`
MD5	`d9859bb60e5efe9d38a30c766b470366`
BLAKE2b-256	`32e999f525f2e1d64085a62d7c1da977cbc9da31c580fa853d0d21d45250be06`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: brokk_bifrost_searchtools-0.6.7-cp312-abi3-macosx_10_12_x86_64.whl
- Subject digest: 1817140d22711cf87d2900b61352068c547c944602c23721ea794bbacd5650e1
- Sigstore transparency entry: 1967113870
- Sigstore integration time: Jun 26, 2026
Source repository:
- Permalink: BrokkAi/bifrost@78d05cd120ff836d8c7df4fb60a511da1339abea
- Branch / Tag: refs/tags/v0.6.7
- Owner: https://github.com/BrokkAi
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-wheels.yml@78d05cd120ff836d8c7df4fb60a511da1339abea
- Trigger Event: push

Release history Release notifications | RSS feed

0.8.24

Aug 7, 2026

0.8.23

Aug 7, 2026

0.8.22

Aug 5, 2026

0.8.21

Aug 4, 2026

0.8.20

Aug 4, 2026

0.8.19

Aug 2, 2026

0.8.18

Aug 1, 2026

0.8.17

Jul 30, 2026

0.8.16

Jul 30, 2026

0.8.15

Jul 30, 2026

0.8.12

Jul 28, 2026

0.8.11

Jul 27, 2026

0.8.10

Jul 24, 2026

0.8.9

Jul 23, 2026

0.8.8

Jul 22, 2026

0.8.6

Jul 20, 2026

0.8.5

Jul 20, 2026

0.8.4

Jul 16, 2026

0.8.3

Jul 15, 2026

0.8.2

Jul 15, 2026

0.8.1

Jul 13, 2026

0.8.0

Jul 13, 2026

0.7.6

Jul 12, 2026

0.7.5

Jul 10, 2026

0.7.4

Jul 7, 2026

0.7.3

Jul 6, 2026

0.7.2

Jul 1, 2026

0.7.1

Jun 30, 2026

0.7.0

Jun 29, 2026

0.6.8

Jun 28, 2026

This release

0.6.7

Jun 26, 2026

0.6.6

Jun 23, 2026

0.6.5

Jun 18, 2026

0.6.4

Jun 17, 2026

0.2.1

Jun 17, 2026

brokk-bifrost-searchtools 0.6.7

brokk-bifrost-searchtools

What it does

Quick start

API overview

Semantic search

License

Project links

Key dates

2 maintainers

Credits

GitHub Statistics

License expression

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed