Bitfab

Bitfab client for provider-based API calls.

Monorepo Structure

This package is part of the Harvest monorepo. While the TypeScript/JavaScript packages use a pnpm workspace for shared dependencies, this Python package uses Poetry for its dependency management.

Note: The pnpm workspace includes:

bitfab-web - Next.js web application
bitfab-typescript-sdk - TypeScript SDK
bitfab-vscode - VS Code extension
frontend - Legacy frontend

From the root directory, you can run TypeScript tests and validation across all packages with pnpm test or pnpm validate.

Installation

Basic Installation

pip install bitfab-py

With OpenAI Tracing Support

If you want to use the OpenAI Agents SDK tracing integration:

pip install bitfab-py[openai-tracing]

Local Development

For local development:

cd bitfab-python-sdk
poetry install --with dev

After installation, you can use developer tasks. For the best experience, add Poetry's venv to your PATH:

# Add to your ~/.zshrc or ~/.bashrc
export PATH="$(poetry env info --path)/bin:$PATH"

# Then you can use 'dev' directly (no ./run or poetry run needed!)
dev list
dev test

See Development Tasks below for all available commands.

Or install as an editable package from the parent directory:

poetry add --editable ../bitfab-python-sdk

Usage

Basic Usage

from bitfab import Bitfab

client = Bitfab(
    api_key="bf_your_api_key_here",
    service_url="https://bitfab.ai",  # Optional, defaults to production
    env_vars={"OPENAI_API_KEY": "sk-your-openai-key"},  # Optional, for local BAML execution
)

result = client.call("method_name", arg1="value1", arg2="value2")

OpenAI Agents SDK Tracing

If you have the openai-agents package installed (via pip install bitfab-py[openai-tracing]), you can use the tracing processor:

from bitfab import Bitfab
from agents import Agent, set_trace_processors

bitfab = Bitfab(api_key="bf_your_api_key_here")

# Register the processor once: it captures agent internals (LLM/tool/handoff spans).
set_trace_processors([bitfab.get_openai_tracing_processor()])

agent = Agent(name="my-agent", instructions="...")
# The run wrapper records a replayable root carrying the run input.
handler = bitfab.get_openai_agent_handler("my-agent")

# Swap Runner.run(agent, input) -> handler.wrap_run(agent, input)
result = await handler.wrap_run(agent, "user input here")

The processor alone records a root with no input, so a processor-only trace is not replayable; wrap_run (a drop-in for Runner.run) records the keyed, replayable root.

Note: If you try to use get_openai_tracing_processor() without installing the openai-tracing extra, you'll get a helpful error message telling you to install it.

Configuration

api_key: Required - Your Bitfab API key (generate from your Bitfab dashboard)
service_url: Optional - The Bitfab service URL (defaults to https://bitfab.ai)
env_vars: Optional - Environment variables for LLM providers (e.g., {"OPENAI_API_KEY": "..."})
enabled: Optional - Enable/disable tracing (defaults to True). When False, decorated functions still execute but no spans are sent.

Development Tasks

This project uses a Python-based developer tasks module (dev/) instead of Makefiles for better cross-platform support and more robust CLI capabilities.

Using Developer Tasks

After running poetry install --with dev, you can use developer tasks:

Quick Setup (One-time)

# Install dependencies (creates the 'dev' script in the venv)
poetry install --with dev

# Run this script to add to PATH for current session and get command to make it permanent
./setup-dev-path.sh

# Copy-paste the command it outputs, then reload your shell config:
source ~/.zshrc  # or ~/.bashrc

The setup-dev-path.sh script will:

Add the venv bin to PATH for your current session
Detect your shell (zsh/bash) and output a command you can copy-paste to make it permanent
Skip if already configured

Using Developer Commands

Once PATH is set up, use commands directly - just like make <target>:

dev list              # List all available commands
dev test              # Run tests
dev test --verbose    # Run tests with verbose output
dev lint              # Lint code
dev format            # Format code
dev build             # Build package
dev publish patch      # Publish with version bump

How it works: When you define [tool.poetry.scripts] in pyproject.toml, Poetry creates executable scripts in the venv's bin/ directory. Adding that bin/ to PATH makes those scripts available as commands.

Key advantage: Just like Makefiles, it's super clear - dev <command> is as obvious as make <target>!

Module Structure

Each command is in its own file in the dev/ module:

dev/test.py - Test commands
dev/lint.py - Linting
dev/build.py - Building
dev/publish.py - Publishing
etc.

This makes it easy to find and modify individual commands.

Publishing

This package uses bump-my-version for version management. To publish a new version:

# Use the dev command
dev publish patch          # Bump patch (0.3.0 -> 0.3.1)
dev publish minor          # Bump minor (0.3.0 -> 0.4.0)
dev publish major          # Bump major (0.3.0 -> 1.0.0)
dev publish version=1.2.3  # Custom version

# Or just bump version without publishing
dev bump patch
dev bump minor

The publish process will:

Run all tests
Bump the version in pyproject.toml
Commit and tag the changes
Build the package
Prompt for confirmation before publishing to PyPI

Note: Publishing requires:

A clean git working directory (no uncommitted changes)
Poetry installed and configured
PyPI credentials configured (via poetry config pypi-token.pypi <token>)

Download files

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

Source Distribution

bitfab_py-0.33.1.tar.gz (92.5 kB view details)

Uploaded Jul 29, 2026 Source

Built Distribution

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.

bitfab_py-0.33.1-py3-none-any.whl (99.0 kB view details)

Uploaded Jul 29, 2026 Python 3

File details

Details for the file bitfab_py-0.33.1.tar.gz.

File metadata

Download URL: bitfab_py-0.33.1.tar.gz
Upload date: Jul 29, 2026
Size: 92.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bitfab_py-0.33.1.tar.gz
Algorithm	Hash digest
SHA256	`a0ea5a795bdbc2f41dad8ca5cecde52aaf16840845fc731d0d6150741888c706`
MD5	`a424fe2c9c68f9854f6bfde1a9d820a2`
BLAKE2b-256	`3842237078f32ed5337cd07095974fa2a265fc357699134c8737966483e2e4bf`

See more details on using hashes here.

Provenance

The following attestation bundles were made for bitfab_py-0.33.1.tar.gz:

Publisher: publish-python-sdk.yml on Project-White-Rabbit/ai-assistant

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: bitfab_py-0.33.1.tar.gz
- Subject digest: a0ea5a795bdbc2f41dad8ca5cecde52aaf16840845fc731d0d6150741888c706
- Sigstore transparency entry: 2282377486
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: Project-White-Rabbit/ai-assistant@b136f887aa66c01396f744df6a8e30d76112e812
- Branch / Tag: refs/heads/main
- Owner: https://github.com/Project-White-Rabbit
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: self-hosted
- Publication workflow: publish-python-sdk.yml@b136f887aa66c01396f744df6a8e30d76112e812
- Trigger Event: push