Tools Module¶

Bond includes bundled toolsets for common agent use cases.

Memory Toolset¶

The memory toolset provides semantic memory storage with vector search.

Protocol¶

Bases: Protocol

Protocol for memory storage backends.

All operations require tenant_id for multi-tenant isolation. This ensures memories are always scoped correctly and enables efficient indexing on tenant boundaries.

Implementations

PgVectorMemoryStore: PostgreSQL + pgvector (default)
QdrantMemoryStore: Qdrant vector database

Methods:

delete –

Delete a memory by ID.
get –

Retrieve a specific memory by ID.
search –

Search memories by semantic similarity.
store –

Store a memory and return the created Memory object.

`delete(memory_id, *, tenant_id)` `async` ¶

Delete a memory by ID.

Parameters:

memory_id (UUID) –

The UUID of the memory to delete.
tenant_id (UUID) –

Tenant UUID for multi-tenant isolation (required).

Returns:

bool | Error –

True if deleted, False if not found, or Error on failure.

Source code in src/bond/tools/memory/_protocols.py

async def delete(self, memory_id: UUID, *, tenant_id: UUID) -> bool | Error:
    """Delete a memory by ID.

    Args:
        memory_id: The UUID of the memory to delete.
        tenant_id: Tenant UUID for multi-tenant isolation (required).

    Returns:
        True if deleted, False if not found, or Error on failure.
    """
    ...

`get(memory_id, *, tenant_id)` `async` ¶

Retrieve a specific memory by ID.

Parameters:

memory_id (UUID) –

The UUID of the memory to retrieve.
tenant_id (UUID) –

Tenant UUID for multi-tenant isolation (required).

Returns:

Memory | None | Error –

The Memory if found, None if not found, or Error on failure.

Source code in src/bond/tools/memory/_protocols.py

async def get(self, memory_id: UUID, *, tenant_id: UUID) -> Memory | None | Error:
    """Retrieve a specific memory by ID.

    Args:
        memory_id: The UUID of the memory to retrieve.
        tenant_id: Tenant UUID for multi-tenant isolation (required).

    Returns:
        The Memory if found, None if not found, or Error on failure.
    """
    ...

`search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None)` `async` ¶

Search memories by semantic similarity.

Parameters:

query (str) –

Search query text.
tenant_id (UUID) –

Tenant UUID for multi-tenant isolation (required).
top_k (int, default: 10 ) –

Maximum number of results.
score_threshold (float | None, default: None ) –

Minimum similarity score to include.
tags (list[str] | None, default: None ) –

Filter by memories with these tags.
agent_id (str | None, default: None ) –

Filter by creating agent.
embedding_model (str | None, default: None ) –

Override default embedding model.

Returns:

list[SearchResult] | Error –

List of SearchResult ordered by similarity, or Error on failure.

Source code in src/bond/tools/memory/_protocols.py

async def search(
    self,
    query: str,
    *,
    tenant_id: UUID,
    top_k: int = 10,
    score_threshold: float | None = None,
    tags: list[str] | None = None,
    agent_id: str | None = None,
    embedding_model: str | None = None,
) -> list[SearchResult] | Error:
    """Search memories by semantic similarity.

    Args:
        query: Search query text.
        tenant_id: Tenant UUID for multi-tenant isolation (required).
        top_k: Maximum number of results.
        score_threshold: Minimum similarity score to include.
        tags: Filter by memories with these tags.
        agent_id: Filter by creating agent.
        embedding_model: Override default embedding model.

    Returns:
        List of SearchResult ordered by similarity, or Error on failure.
    """
    ...

`store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None)` `async` ¶

Store a memory and return the created Memory object.

Parameters:

content (str) –

The text content to store.
agent_id (str) –

ID of the agent creating this memory.
tenant_id (UUID) –

Tenant UUID for multi-tenant isolation (required).
conversation_id (str | None, default: None ) –

Optional conversation context.
tags (list[str] | None, default: None ) –

Optional tags for filtering.
embedding (list[float] | None, default: None ) –

Pre-computed embedding (backend generates if None).
embedding_model (str | None, default: None ) –

Override default embedding model.

Returns:

Memory | Error –

The created Memory on success, or Error on failure.

Source code in src/bond/tools/memory/_protocols.py

async def store(
    self,
    content: str,
    agent_id: str,
    *,
    tenant_id: UUID,
    conversation_id: str | None = None,
    tags: list[str] | None = None,
    embedding: list[float] | None = None,
    embedding_model: str | None = None,
) -> Memory | Error:
    """Store a memory and return the created Memory object.

    Args:
        content: The text content to store.
        agent_id: ID of the agent creating this memory.
        tenant_id: Tenant UUID for multi-tenant isolation (required).
        conversation_id: Optional conversation context.
        tags: Optional tags for filtering.
        embedding: Pre-computed embedding (backend generates if None).
        embedding_model: Override default embedding model.

    Returns:
        The created Memory on success, or Error on failure.
    """
    ...

Models¶

Bases: BaseModel

A stored memory unit.

Memories are the fundamental storage unit in Bond's memory system. Each memory has content, metadata for filtering, and an embedding for semantic search.

Bases: BaseModel

Memory with similarity score from search.

Backends¶

Qdrant¶

Qdrant-backed memory store using PydanticAI Embedder.

Benefits over raw sentence-transformers: - Non-blocking embeddings (runs in thread pool via run_in_executor) - Supports OpenAI, Cohere, and Local models seamlessly - Automatic cost/latency tracking via OpenTelemetry - Zero-refactor provider swapping

Example

# In-memory for development/testing (local embeddings)
store = QdrantMemoryStore()

# Persistent with local embeddings
store = QdrantMemoryStore(qdrant_url="http://localhost:6333")

# OpenAI embeddings
store = QdrantMemoryStore(
    embedding_model="openai:text-embedding-3-small",
    qdrant_url="http://localhost:6333",
)

Initialize the Qdrant memory store.

Parameters:

collection_name (str, default: 'memories' ) –

Name of the Qdrant collection.
embedding_model (str, default: 'sentence-transformers:all-MiniLM-L6-v2' ) –

Embedding model string. Supports: - "sentence-transformers:all-MiniLM-L6-v2" (local, default) - "openai:text-embedding-3-small" - "cohere:embed-english-v3.0"
qdrant_url (str | None, default: None ) –

Qdrant server URL. None = in-memory (for dev/testing).
qdrant_api_key (str | None, default: None ) –

Optional API key for Qdrant Cloud.

Methods:

delete –

Delete a memory by ID (scoped to tenant).
get –

Retrieve a specific memory by ID (scoped to tenant).
search –

Semantic search with optional filtering.
store –

Store memory with embedding.

`delete(memory_id, *, tenant_id)` `async` ¶

Delete a memory by ID (scoped to tenant).

`get(memory_id, *, tenant_id)` `async` ¶

Retrieve a specific memory by ID (scoped to tenant).

`search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None)` `async` ¶

Semantic search with optional filtering.

`store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None)` `async` ¶

Store memory with embedding.

pgvector¶

pgvector-backed memory store using PydanticAI Embedder.

Benefits over Qdrant: - No separate infrastructure (uses existing Postgres) - Transactional consistency (CASCADE deletes, atomic commits) - Native tenant isolation via SQL WHERE clauses - Unified backup/restore with application data

Example

# Inject pool from dataing's AppDatabase
store = PgVectorMemoryStore(pool=app_db.pool)

# With OpenAI embeddings
store = PgVectorMemoryStore(
    pool=app_db.pool,
    embedding_model="openai:text-embedding-3-small",
)

Initialize the pgvector memory store.

Parameters:

pool (Pool) –

asyncpg connection pool (typically from AppDatabase).
table_name (str, default: 'agent_memories' ) –

Name of the memories table.
embedding_model (str, default: 'openai:text-embedding-3-small' ) –

PydanticAI embedding model string.

Methods:

delete –

Hard delete a specific memory (scoped to tenant for safety).
get –

Retrieve a specific memory by ID (scoped to tenant).
search –

Semantic search using cosine similarity.
store –

Store memory with transactional guarantee.

`delete(memory_id, *, tenant_id)` `async` ¶

Hard delete a specific memory (scoped to tenant for safety).

`get(memory_id, *, tenant_id)` `async` ¶

Retrieve a specific memory by ID (scoped to tenant).

`search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None)` `async` ¶

Semantic search using cosine similarity.

Note: Postgres '<=>' operator returns distance (0=same, 2=opposite). We convert distance to similarity (1 - distance) for the interface.

`store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None)` `async` ¶

Store memory with transactional guarantee.

Factory Function¶

Create a memory backend based on configuration.

Parameters:

backend_type (MemoryBackendType, default: PGVECTOR ) –

Which backend to use (default: pgvector).
pool (Pool | None, default: None ) –

asyncpg Pool (required for pgvector).
table_name (str, default: 'agent_memories' ) –

Postgres table name (pgvector only).
qdrant_url (str | None, default: None ) –

Qdrant server URL (qdrant only, None = in-memory).
qdrant_api_key (str | None, default: None ) –

Qdrant API key (qdrant only).
collection_name (str, default: 'memories' ) –

Qdrant collection (qdrant only).
embedding_model (str, default: 'openai:text-embedding-3-small' ) –

Model for embeddings (both backends).

Returns:

PgVectorMemoryStore | QdrantMemoryStore –

Configured memory backend instance.

Raises:

ValueError –

If pgvector selected but no pool provided.

Example

# pgvector (recommended)
memory = create_memory_backend(
    backend_type=MemoryBackendType.PGVECTOR,
    pool=app_db.pool,
)

# Qdrant (for specific use cases)
memory = create_memory_backend(
    backend_type=MemoryBackendType.QDRANT,
    qdrant_url="http://localhost:6333",
)

Toolset¶

Schema Toolset¶

The schema toolset provides database schema lookup capabilities.

Protocol¶

Bases: Protocol

Protocol for schema lookup operations.

Implementations provide access to database schema information and lineage data for agent tools.

Methods:

get_downstream –

Get downstream dependencies for a table.
get_table_schema –

Get schema for a specific table.
get_upstream –

Get upstream dependencies for a table.
list_tables –

List all available table names.

`get_downstream(table_name)` `async` ¶

Get downstream dependencies for a table.

Parameters:

table_name (str) –

Name of the table.

Returns:

list[str] –

List of downstream table names.

Source code in src/bond/tools/schema/_protocols.py

async def get_downstream(self, table_name: str) -> list[str]:
    """Get downstream dependencies for a table.

    Args:
        table_name: Name of the table.

    Returns:
        List of downstream table names.
    """
    ...

`get_table_schema(table_name)` `async` ¶

Get schema for a specific table.

Parameters:

table_name (str) –

Name of the table (can be qualified like schema.table).

Returns:

dict[str, Any] | None –

Table schema as dict with columns, types, etc. or None if not found.

Source code in src/bond/tools/schema/_protocols.py

async def get_table_schema(self, table_name: str) -> dict[str, Any] | None:
    """Get schema for a specific table.

    Args:
        table_name: Name of the table (can be qualified like schema.table).

    Returns:
        Table schema as dict with columns, types, etc. or None if not found.
    """
    ...

`get_upstream(table_name)` `async` ¶

Get upstream dependencies for a table.

Parameters:

table_name (str) –

Name of the table.

Returns:

list[str] –

List of upstream table names.

Source code in src/bond/tools/schema/_protocols.py

async def get_upstream(self, table_name: str) -> list[str]:
    """Get upstream dependencies for a table.

    Args:
        table_name: Name of the table.

    Returns:
        List of upstream table names.
    """
    ...

`list_tables()` `async` ¶

List all available table names.

Returns:

list[str] –

List of table names (may be qualified).

Source code in src/bond/tools/schema/_protocols.py

async def list_tables(self) -> list[str]:
    """List all available table names.

    Returns:
        List of table names (may be qualified).
    """
    ...

Models¶

Bases: BaseModel

Schema information for a table.

Attributes:

qualified_name (str) –

Get fully qualified table name.

`qualified_name` `property` ¶

Get fully qualified table name.

Bases: BaseModel

Schema information for a single column.

Toolset¶

GitHub Toolset¶

The GitHub toolset provides tools to browse and analyze any GitHub repository.

Protocol¶

Bases: Protocol

Protocol for GitHub API access.

Provides methods to: - Get repository metadata - Browse repository file tree - Read file contents - Search code - Get commit history - Get pull request details

Methods:

get_commits –

Get recent commits for file or repository.
get_file –

Read file content.
get_pr –

Get pull request details by number.
get_repo –

Get repository metadata.
list_tree –

List directory contents at path.
search_code –

Search code within repository or across GitHub.

`get_commits(owner, repo, path=None, ref=None, limit=10)` `async` ¶

Get recent commits for file or repository.

Parameters:

owner (str) –

Repository owner.
repo (str) –

Repository name.
path (str | None, default: None ) –

Optional path to filter commits by file.
ref (str | None, default: None ) –

Git ref to start from. Uses default branch if None.
limit (int, default: 10 ) –

Maximum commits to return.

Returns:

list[Commit] –

List of Commit sorted by date descending.

Raises:

GitHubError –

If repository not found or API error.

Source code in src/bond/tools/github/_protocols.py

async def get_commits(
    self,
    owner: str,
    repo: str,
    path: str | None = None,
    ref: str | None = None,
    limit: int = 10,
) -> list[Commit]:
    """Get recent commits for file or repository.

    Args:
        owner: Repository owner.
        repo: Repository name.
        path: Optional path to filter commits by file.
        ref: Git ref to start from. Uses default branch if None.
        limit: Maximum commits to return.

    Returns:
        List of Commit sorted by date descending.

    Raises:
        GitHubError: If repository not found or API error.
    """
    ...

`get_file(owner, repo, path, ref=None)` `async` ¶

Read file content.

Parameters:

owner (str) –

Repository owner.
repo (str) –

Repository name.
path (str) –

Path to file relative to repo root.
ref (str | None, default: None ) –

Git ref (branch, tag, commit). Uses default branch if None.

Returns:

FileContent –

FileContent with decoded file content.

Raises:

GitHubError –

If file not found or API error.

Source code in src/bond/tools/github/_protocols.py

async def get_file(
    self,
    owner: str,
    repo: str,
    path: str,
    ref: str | None = None,
) -> FileContent:
    """Read file content.

    Args:
        owner: Repository owner.
        repo: Repository name.
        path: Path to file relative to repo root.
        ref: Git ref (branch, tag, commit). Uses default branch if None.

    Returns:
        FileContent with decoded file content.

    Raises:
        GitHubError: If file not found or API error.
    """
    ...

`get_pr(owner, repo, number)` `async` ¶

Get pull request details by number.

Parameters:

owner (str) –

Repository owner.
repo (str) –

Repository name.
number (int) –

Pull request number.

Returns:

PullRequest –

PullRequest with PR details.

Raises:

GitHubError –

If PR not found or API error.

Source code in src/bond/tools/github/_protocols.py

async def get_pr(
    self,
    owner: str,
    repo: str,
    number: int,
) -> PullRequest:
    """Get pull request details by number.

    Args:
        owner: Repository owner.
        repo: Repository name.
        number: Pull request number.

    Returns:
        PullRequest with PR details.

    Raises:
        GitHubError: If PR not found or API error.
    """
    ...

`get_repo(owner, repo)` `async` ¶

Get repository metadata.

Parameters:

owner (str) –

Repository owner (user or organization).
repo (str) –

Repository name.

Returns:

RepoInfo –

RepoInfo with repository metadata.

Raises:

GitHubError –

If repository not found or API error.

Source code in src/bond/tools/github/_protocols.py

async def get_repo(
    self,
    owner: str,
    repo: str,
) -> RepoInfo:
    """Get repository metadata.

    Args:
        owner: Repository owner (user or organization).
        repo: Repository name.

    Returns:
        RepoInfo with repository metadata.

    Raises:
        GitHubError: If repository not found or API error.
    """
    ...

`list_tree(owner, repo, path='', ref=None)` `async` ¶

List directory contents at path.

Parameters:

owner (str) –

Repository owner.
repo (str) –

Repository name.
path (str, default: '' ) –

Path relative to repo root (empty string for root).
ref (str | None, default: None ) –

Git ref (branch, tag, commit). Uses default branch if None.

Returns:

list[TreeEntry] –

List of TreeEntry for files and directories at path.

Raises:

GitHubError –

If path not found or API error.

Source code in src/bond/tools/github/_protocols.py

async def list_tree(
    self,
    owner: str,
    repo: str,
    path: str = "",
    ref: str | None = None,
) -> list[TreeEntry]:
    """List directory contents at path.

    Args:
        owner: Repository owner.
        repo: Repository name.
        path: Path relative to repo root (empty string for root).
        ref: Git ref (branch, tag, commit). Uses default branch if None.

    Returns:
        List of TreeEntry for files and directories at path.

    Raises:
        GitHubError: If path not found or API error.
    """
    ...

`search_code(query, owner=None, repo=None, limit=10)` `async` ¶

Search code within repository or across GitHub.

Parameters:

query (str) –

Search query string.
owner (str | None, default: None ) –

Optional owner to scope search.
repo (str | None, default: None ) –

Optional repo name to scope search (requires owner).
limit (int, default: 10 ) –

Maximum results to return.

Returns:

list[CodeSearchResult] –

List of CodeSearchResult with matching files.

Raises:

GitHubError –

If search fails or rate limited.

Source code in src/bond/tools/github/_protocols.py

async def search_code(
    self,
    query: str,
    owner: str | None = None,
    repo: str | None = None,
    limit: int = 10,
) -> list[CodeSearchResult]:
    """Search code within repository or across GitHub.

    Args:
        query: Search query string.
        owner: Optional owner to scope search.
        repo: Optional repo name to scope search (requires owner).
        limit: Maximum results to return.

    Returns:
        List of CodeSearchResult with matching files.

    Raises:
        GitHubError: If search fails or rate limited.
    """
    ...

Adapter¶

GitHub API adapter implementing GitHubProtocol.

Uses httpx.AsyncClient for efficient HTTP requests with: - Automatic rate limit handling with exponential backoff - Token authentication from environment or constructor - Connection pooling for performance

Example

# Use token from environment
adapter = GitHubAdapter()

# Or provide token explicitly
adapter = GitHubAdapter(token="ghp_...")

# Use the adapter
repo = await adapter.get_repo("facebook", "react")
print(repo.description)

Initialize the adapter.

Parameters:

token (str | None, default: None ) –

GitHub personal access token. Falls back to GITHUB_TOKEN env var.
base_url (str, default: GITHUB_API_BASE ) –

GitHub API base URL (for GitHub Enterprise).
max_retries (int, default: 3 ) –

Maximum retries for rate-limited requests.

Methods:

close –

Close the HTTP client.
get_commits –

Get recent commits for file or repository.
get_file –

Read file content.
get_pr –

Get pull request details by number.
get_repo –

Get repository metadata.
list_tree –

List directory contents at path.
search_code –

Search code within repository or across GitHub.

`close()` `async` ¶

Close the HTTP client.

`get_commits(owner, repo, path=None, ref=None, limit=10)` `async` ¶

Get recent commits for file or repository.

`get_file(owner, repo, path, ref=None)` `async` ¶

Read file content.

`get_pr(owner, repo, number)` `async` ¶

Get pull request details by number.

`get_repo(owner, repo)` `async` ¶

Get repository metadata.

`list_tree(owner, repo, path='', ref=None)` `async` ¶

List directory contents at path.

`search_code(query, owner=None, repo=None, limit=10)` `async` ¶

Search code within repository or across GitHub.

Types¶

Repository metadata.

Attributes:

owner (str) –

Repository owner (user or organization).
name (str) –

Repository name.
full_name (str) –

Full name in owner/repo format.
description (str | None) –

Repository description.
default_branch (str) –

Default branch name (e.g., "main").
topics (tuple[str, ...]) –

List of repository topics.
language (str | None) –

Primary programming language.
stars (int) –

Star count.
forks (int) –

Fork count.
is_private (bool) –

Whether the repository is private.
created_at (datetime) –

Creation timestamp.
updated_at (datetime) –

Last update timestamp.

Entry in a repository file tree.

Attributes:

path (str) –

Path relative to repository root.
name (str) –

File or directory name.
type (str) –

Either "file" or "dir".
size (int | None) –

File size in bytes (None for directories).
sha (str) –

Git SHA hash.

File content from a repository.

Attributes:

path (str) –

Path relative to repository root.
content (str) –

Decoded file content.
encoding (str) –

Original encoding (usually "base64").
size (int) –

File size in bytes.
sha (str) –

Git SHA hash.

Result from code search.

Attributes:

path (str) –

File path where match was found.
repository (str) –

Repository full name (owner/repo).
html_url (str) –

URL to view file on GitHub.
text_matches (tuple[str, ...]) –

List of matching text fragments.

Git commit information.

Attributes:

sha (str) –

Full commit SHA.
message (str) –

Commit message.
author (CommitAuthor) –

Author information.
committer (CommitAuthor) –

Committer information.
html_url (str) –

URL to view commit on GitHub.

Commit author information.

Attributes:

name (str) –

Author's name.
email (str) –

Author's email.
date (datetime) –

Commit date.

Pull request information.

Attributes:

number (int) –

PR number.
title (str) –

PR title.
body (str | None) –

PR description/body.
state (str) –

PR state (open, closed, merged).
user (PullRequestUser) –

PR author.
html_url (str) –

URL to view PR on GitHub.
created_at (datetime) –

Creation timestamp.
updated_at (datetime) –

Last update timestamp.
merged_at (datetime | None) –

Merge timestamp (None if not merged).
base_branch (str) –

Target branch name.
head_branch (str) –

Source branch name.

GitHub user in PR context.

Attributes:

login (str) –

GitHub username.
html_url (str) –

Profile URL.

Exceptions¶

Bases: Exception

Base exception for GitHub operations.

Bases: GitHubError

Repository not found.

Initialize error.

Parameters:

owner (str) –

Repository owner.
repo (str) –

Repository name.

Source code in src/bond/tools/github/_exceptions.py

def __init__(self, owner: str, repo: str) -> None:
    """Initialize error.

    Args:
        owner: Repository owner.
        repo: Repository name.
    """
    self.owner = owner
    self.repo = repo
    super().__init__(f"Repository not found: {owner}/{repo}")

Bases: GitHubError

File not found in repository.

Initialize error.

Parameters:

owner (str) –

Repository owner.
repo (str) –

Repository name.
path (str) –

File path that was not found.

Source code in src/bond/tools/github/_exceptions.py

def __init__(self, owner: str, repo: str, path: str) -> None:
    """Initialize error.

    Args:
        owner: Repository owner.
        repo: Repository name.
        path: File path that was not found.
    """
    self.owner = owner
    self.repo = repo
    self.path = path
    super().__init__(f"File not found: {owner}/{repo}/{path}")

Bases: GitHubError

Pull request not found.

Initialize error.

Parameters:

owner (str) –

Repository owner.
repo (str) –

Repository name.
number (int) –

PR number.

Source code in src/bond/tools/github/_exceptions.py

def __init__(self, owner: str, repo: str, number: int) -> None:
    """Initialize error.

    Args:
        owner: Repository owner.
        repo: Repository name.
        number: PR number.
    """
    self.owner = owner
    self.repo = repo
    self.number = number
    super().__init__(f"PR not found: {owner}/{repo}#{number}")

Bases: GitHubError

GitHub API rate limit exceeded.

Initialize error.

Parameters:

reset_at (int | None, default: None ) –

Unix timestamp when rate limit resets.

Source code in src/bond/tools/github/_exceptions.py

def __init__(self, reset_at: int | None = None) -> None:
    """Initialize error.

    Args:
        reset_at: Unix timestamp when rate limit resets.
    """
    self.reset_at = reset_at
    msg = "GitHub API rate limit exceeded"
    if reset_at:
        msg += f" (resets at {reset_at})"
    super().__init__(msg)

Bases: GitHubError

GitHub authentication failed.

Initialize error.

Source code in src/bond/tools/github/_exceptions.py

def __init__(self) -> None:
    """Initialize error."""
    super().__init__("GitHub authentication failed. Check GITHUB_TOKEN.")

Toolset¶

GitHunter Toolset¶

The GitHunter toolset provides forensic code ownership analysis tools.

Protocol¶

Bases: Protocol

Protocol for Git Hunter forensic code ownership tool.

Provides methods to: - Blame individual lines to find who last modified them - Find PR discussions for commits - Determine file experts based on commit frequency

Methods:

blame_line –

Get blame information for a specific line.
find_pr_discussion –

Find the PR discussion for a commit.
get_expert_for_file –

Get experts for a file based on commit frequency.

`blame_line(repo_path, file_path, line_no)` `async` ¶

Get blame information for a specific line.

Parameters:

repo_path (Path) –

Path to the git repository root.
file_path (str) –

Path to file relative to repo root.
line_no (int) –

Line number to blame (1-indexed).

Returns:

BlameResult –

BlameResult with author, commit, and line information.

Raises:

RepoNotFoundError –

If repo_path is not a git repository.
FileNotFoundInRepoError –

If file doesn't exist in repo.
LineOutOfRangeError –

If line_no is invalid.
BinaryFileError –

If file is binary.

Source code in src/bond/tools/githunter/_protocols.py

async def blame_line(
    self,
    repo_path: Path,
    file_path: str,
    line_no: int,
) -> BlameResult:
    """Get blame information for a specific line.

    Args:
        repo_path: Path to the git repository root.
        file_path: Path to file relative to repo root.
        line_no: Line number to blame (1-indexed).

    Returns:
        BlameResult with author, commit, and line information.

    Raises:
        RepoNotFoundError: If repo_path is not a git repository.
        FileNotFoundInRepoError: If file doesn't exist in repo.
        LineOutOfRangeError: If line_no is invalid.
        BinaryFileError: If file is binary.
    """
    ...

`find_pr_discussion(repo_path, commit_hash)` `async` ¶

Find the PR discussion for a commit.

Parameters:

repo_path (Path) –

Path to the git repository root.
commit_hash (str) –

Full or abbreviated commit SHA.

Returns:

PRDiscussion | None –

PRDiscussion if commit is associated with a PR, None otherwise.

Raises:

RepoNotFoundError –

If repo_path is not a git repository.
RateLimitedError –

If GitHub rate limit exceeded.
GitHubUnavailableError –

If GitHub API is unavailable.

Source code in src/bond/tools/githunter/_protocols.py

async def find_pr_discussion(
    self,
    repo_path: Path,
    commit_hash: str,
) -> PRDiscussion | None:
    """Find the PR discussion for a commit.

    Args:
        repo_path: Path to the git repository root.
        commit_hash: Full or abbreviated commit SHA.

    Returns:
        PRDiscussion if commit is associated with a PR, None otherwise.

    Raises:
        RepoNotFoundError: If repo_path is not a git repository.
        RateLimitedError: If GitHub rate limit exceeded.
        GitHubUnavailableError: If GitHub API is unavailable.
    """
    ...

`get_expert_for_file(repo_path, file_path, window_days=90, limit=3)` `async` ¶

Get experts for a file based on commit frequency.

Parameters:

repo_path (Path) –

Path to the git repository root.
file_path (str) –

Path to file relative to repo root.
window_days (int, default: 90 ) –

Time window for commit history (0 or None for all time).
limit (int, default: 3 ) –

Maximum number of experts to return.

Returns:

list[FileExpert] –

List of FileExpert sorted by commit count (descending).

Raises:

RepoNotFoundError –

If repo_path is not a git repository.
FileNotFoundInRepoError –

If file doesn't exist in repo.

Source code in src/bond/tools/githunter/_protocols.py

async def get_expert_for_file(
    self,
    repo_path: Path,
    file_path: str,
    window_days: int = 90,
    limit: int = 3,
) -> list[FileExpert]:
    """Get experts for a file based on commit frequency.

    Args:
        repo_path: Path to the git repository root.
        file_path: Path to file relative to repo root.
        window_days: Time window for commit history (0 or None for all time).
        limit: Maximum number of experts to return.

    Returns:
        List of FileExpert sorted by commit count (descending).

    Raises:
        RepoNotFoundError: If repo_path is not a git repository.
        FileNotFoundInRepoError: If file doesn't exist in repo.
    """
    ...

Types¶

Result of git blame for a single line.

Attributes:

line_no (int) –

Line number that was blamed.
content (str) –

Content of the line.
author (AuthorProfile) –

Author who last modified the line.
commit_hash (str) –

Full SHA of the commit.
commit_date (datetime) –

UTC datetime of the commit (author date).
commit_message (str) –

First line of commit message.
is_boundary (bool) –

True if this is a shallow clone boundary commit.

Code ownership expert for a file based on commit history.

Attributes:

author (AuthorProfile) –

The author profile.
commit_count (int) –

Number of commits touching the file.
last_commit_date (datetime) –

UTC datetime of most recent commit.

Pull request discussion associated with a commit.

Attributes:

pr_number (int) –

PR number.
title (str) –

PR title.
body (str) –

PR description body.
url (str) –

URL to the PR on GitHub.
issue_comments (tuple[str, ...]) –

Top-level PR comments (not review comments).

Git commit author with optional GitHub enrichment.

Attributes:

git_email (str) –

Author email from git commit.
git_name (str) –

Author name from git commit.
github_username (str | None) –

GitHub username if resolved from email.
github_avatar_url (str | None) –

GitHub avatar URL if resolved.

Request Models¶

Bases: BaseModel

Request to get blame information for a specific line.

Agent Usage: Use this when you need to know who last modified a specific line of code, what commit changed it, and when.

Bases: BaseModel

Request to find PR discussion for a commit.

Agent Usage: Use this when you have a commit hash and want to find the pull request discussion that introduced it.

Bases: BaseModel

Request to get file experts based on commit frequency.

Agent Usage: Use this when you need to identify who has the most knowledge about a file based on their commit history.

Tools Module¶

Memory Toolset¶

Protocol¶

delete(memory_id, *, tenant_id) async ¶

get(memory_id, *, tenant_id) async ¶

search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None) async ¶

store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None) async ¶

Models¶

Backends¶

Qdrant¶

delete(memory_id, *, tenant_id) async ¶

get(memory_id, *, tenant_id) async ¶

search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None) async ¶

store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None) async ¶

pgvector¶

delete(memory_id, *, tenant_id) async ¶

get(memory_id, *, tenant_id) async ¶

search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None) async ¶

store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None) async ¶

Factory Function¶

Toolset¶

Schema Toolset¶

Protocol¶

get_downstream(table_name) async ¶

get_table_schema(table_name) async ¶

get_upstream(table_name) async ¶

list_tables() async ¶

Models¶

qualified_name property ¶

Toolset¶

GitHub Toolset¶

Protocol¶

get_commits(owner, repo, path=None, ref=None, limit=10) async ¶

get_file(owner, repo, path, ref=None) async ¶

get_pr(owner, repo, number) async ¶

get_repo(owner, repo) async ¶

list_tree(owner, repo, path='', ref=None) async ¶

search_code(query, owner=None, repo=None, limit=10) async ¶

Adapter¶

close() async ¶

get_commits(owner, repo, path=None, ref=None, limit=10) async ¶

get_file(owner, repo, path, ref=None) async ¶

get_pr(owner, repo, number) async ¶

get_repo(owner, repo) async ¶

list_tree(owner, repo, path='', ref=None) async ¶

search_code(query, owner=None, repo=None, limit=10) async ¶

Types¶

Exceptions¶

Toolset¶

GitHunter Toolset¶

Protocol¶

blame_line(repo_path, file_path, line_no) async ¶

find_pr_discussion(repo_path, commit_hash) async ¶

get_expert_for_file(repo_path, file_path, window_days=90, limit=3) async ¶

Types¶

Request Models¶

Toolset¶

`delete(memory_id, *, tenant_id)` `async` ¶

`get(memory_id, *, tenant_id)` `async` ¶

`search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None)` `async` ¶

`store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None)` `async` ¶

`delete(memory_id, *, tenant_id)` `async` ¶

`get(memory_id, *, tenant_id)` `async` ¶

`search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None)` `async` ¶

`store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None)` `async` ¶

`delete(memory_id, *, tenant_id)` `async` ¶

`get(memory_id, *, tenant_id)` `async` ¶

`search(query, *, tenant_id, top_k=10, score_threshold=None, tags=None, agent_id=None, embedding_model=None)` `async` ¶

`store(content, agent_id, *, tenant_id, conversation_id=None, tags=None, embedding=None, embedding_model=None)` `async` ¶

`get_downstream(table_name)` `async` ¶

`get_table_schema(table_name)` `async` ¶

`get_upstream(table_name)` `async` ¶

`list_tables()` `async` ¶

`qualified_name` `property` ¶

`get_commits(owner, repo, path=None, ref=None, limit=10)` `async` ¶

`get_file(owner, repo, path, ref=None)` `async` ¶

`get_pr(owner, repo, number)` `async` ¶

`get_repo(owner, repo)` `async` ¶

`list_tree(owner, repo, path='', ref=None)` `async` ¶

`search_code(query, owner=None, repo=None, limit=10)` `async` ¶

`close()` `async` ¶

`get_commits(owner, repo, path=None, ref=None, limit=10)` `async` ¶

`get_file(owner, repo, path, ref=None)` `async` ¶

`get_pr(owner, repo, number)` `async` ¶

`get_repo(owner, repo)` `async` ¶

`list_tree(owner, repo, path='', ref=None)` `async` ¶

`search_code(query, owner=None, repo=None, limit=10)` `async` ¶

`blame_line(repo_path, file_path, line_no)` `async` ¶

`find_pr_discussion(repo_path, commit_hash)` `async` ¶

`get_expert_for_file(repo_path, file_path, window_days=90, limit=3)` `async` ¶