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

Python 3.10 or newer is required.

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, add_trace_processor

bitfab = Bitfab(api_key="bf_your_api_key_here")

# Register the processor once: it captures agent internals (LLM/tool/handoff spans).
add_trace_processor(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.

OpenTelemetry Transport

Bitfab keeps its public decorators and framework handlers, while one private OpenTelemetry TracerProvider and BatchSpanProcessor per client manage the bounded queue, batch worker, export scheduling, flush, and shutdown lifecycle. Pipelines are created lazily on the first trace send and are not installed globally, so an unused or disabled client starts no OTel worker and the SDK does not replace an application's OTel setup. Framework integrations submit the existing replay-safe Bitfab payload through the same transport interface. Flush and shutdown honor one total caller-supplied deadline. Long-running processes that create transient clients should call client.close() or use with Bitfab(...) as client: to release that client's workers; shared clients still shut down automatically at process exit. The LangGraph/LangChain handler keeps langsmith:hidden scheduler callbacks only for local parent resolution and submits visible Bitfab spans through OTel.

OTel schedules exports in internal batches of at most 512 carriers. The exporter packs that candidate window into requests containing at most eight carriers and no more than the configured encoded-byte target, then runs up to 32 complete requests concurrently. Set BITFAB_OTEL_EXPORT_CONCURRENCY to an integer from 1 through 64 to tune that concurrency; invalid values fall back to 32.

Requests are limited to approximately 3 MB. Set BITFAB_OTEL_MAX_REQUEST_BYTES to a positive integer no greater than 3000000 to use a smaller target for a proxy with a stricter limit. Invalid or larger values fall back to 3000000. A carrier that exceeds the configured limit by itself cannot be split without changing the captured payload; the SDK logs the failed export without interrupting the host application.

Each carrier is encoded once and the request body is assembled from those encodings, so a batch is never re-encoded to measure its size.

Before finalizing a replay, the SDK flushes OTel and polls Bitfab's replay-status API until every expected trace completion and span count is persisted.

If Bitfab accepts only part of a batch, it returns the standard OTLP partialSuccess response and the SDK logs the rejected-span count and reason.

See the OpenTelemetry Transport Architecture for the full component ownership, carrier format, replay barrier, batching, and lifecycle design.

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:

  1. Run all tests
  2. Bump the version in pyproject.toml
  3. Commit and tag the changes
  4. Build the package
  5. 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>)

Key dates

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

1 maintainer

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

Credits

Author: Harvest Team

Requires

Python >=3.10

Provides Extra

baml claude-agent-sdk langgraph openai-tracing

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

bitfab_py-0.39.0.tar.gz (142.4 kB view details)

Uploaded Source

Built Distribution

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

bitfab_py-0.39.0-py3-none-any.whl (153.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: bitfab_py-0.39.0.tar.gz
  • Upload date:
  • Size: 142.4 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.39.0.tar.gz
Algorithm Hash digest
SHA256 e6494df3eb0fb1e0ad45e5dd240b8a695b444cfaf46e753a9345a224c0106245
MD5 f30e2c761a0ee15fbef7aa244212b937
BLAKE2b-256 d07e4f73e15fad850c6773b95fae447f035431d8dcb2a37230422099248480be

See more details on using hashes here.

Provenance

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

File details

Details for the file bitfab_py-0.39.0-py3-none-any.whl.

File metadata

  • Download URL: bitfab_py-0.39.0-py3-none-any.whl
  • Upload date:
  • Size: 153.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bitfab_py-0.39.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2889d235766e386cca826976bbd98c762614c83bee7d3ad187339b9529f97876
MD5 327358e26f35275bd7e24feb42b3586b
BLAKE2b-256 9e289e7e18153718de130b75c84d6421ef23a4b5e08b45b655acd0952a8bd24f

See more details on using hashes here.

Provenance

The following attestation bundles were made for bitfab_py-0.39.0-py3-none-any.whl:

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.

Release history Release notifications | RSS feed

0.52.4

2 files

0.52.3

2 files

0.52.2

2 files

0.52.1

2 files

0.52.0

2 files

0.51.0

2 files

0.50.0

2 files

0.49.0

2 files

0.48.0

2 files

0.47.0

2 files

0.46.0

2 files

0.45.0

2 files

0.44.1

2 files

0.43.0

2 files

0.42.3

2 files

0.42.2

2 files

0.42.1

2 files

0.42.0

2 files

0.41.0

2 files

0.40.1

2 files

0.40.0

2 files

0.39.2

2 files

0.39.1

2 files

This release

0.39.0 This release

2 files

0.38.7

2 files

0.38.6

2 files

0.38.5

2 files

0.38.4

2 files

0.38.3

2 files

0.38.2

2 files

0.38.1

2 files

0.38.0

2 files

0.37.12

2 files

0.37.11

2 files

0.37.10

2 files

0.37.9

2 files

0.37.8

2 files

0.37.7

2 files

0.37.6

2 files

0.37.5

2 files

0.37.4

2 files

0.37.3

2 files

0.37.2

2 files

0.37.1

2 files

0.37.0

2 files

0.36.1

2 files

0.36.0

2 files

0.34.0

2 files

0.33.9

2 files

0.33.8

2 files

0.33.7

2 files

0.33.6

2 files

0.33.5

2 files

0.33.4

2 files

0.33.3

2 files

0.33.2

2 files

0.33.1

2 files

0.33.0

2 files

0.32.0

2 files

0.31.0

2 files

0.30.1

2 files

0.30.0

2 files

0.29.2

2 files

0.29.1

2 files

0.29.0

2 files

0.27.8

2 files

0.27.7

2 files

0.27.6

2 files

0.27.5

2 files

0.27.4

2 files

0.27.3

2 files

0.27.2

2 files

0.27.1

2 files

0.27.0

2 files

0.26.2

2 files

0.26.1

2 files

0.26.0

2 files

0.25.1

2 files

0.25.0

2 files

0.24.0

2 files

0.23.2

2 files

0.23.1

2 files

0.23.0

2 files

0.22.0

2 files

0.21.3

2 files

0.21.2

2 files

0.21.1

2 files

0.21.0

2 files

0.20.0

2 files

0.19.1

2 files

0.19.0

2 files

0.18.2

2 files

0.18.1

2 files

0.18.0

2 files

0.17.0

2 files

0.16.2

2 files

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.5

2 files

0.13.4

2 files

0.13.3

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.12.1

2 files

0.12.0

2 files

0.11.7

2 files

0.11.6

2 files

0.11.5

2 files

0.11.4

2 files

0.11.3

2 files

0.11.2

2 files

0.11.1

2 files

0.11.0

2 files

0.10.1

2 files

0.10.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page