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.

By default, batches are sent directly to Bitfab. To send through a local OTel Collector instead, set BITFAB_OTEL_EXPORTER_ENDPOINT to its OTLP/HTTP base URL (for example, http://localhost:4318). The SDK uses OTel's official OTLP/HTTP exporter, appends /v1/traces, and sends protobuf. Production and replay traffic use this same pipeline. 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. This keeps Collector delivery batched without mistaking Collector acceptance for Bitfab persistence.

OTel schedules direct exports in internal batches of at most 512 carriers. The direct 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 direct-request concurrency; invalid values fall back to 32.

Collector delivery uses OTel's official exporter with at most 32 carriers per export. The SDK partitions Collector protobuf exports into requests of at most approximately 3 MB. Direct OTLP/JSON requests use the same limit while packing up to eight carriers. Set BITFAB_OTEL_MAX_REQUEST_BYTES to a positive integer no greater than 3000000 to use a smaller request target for a Collector or 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.

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.

receivers:
  otlp:
    protocols:
      http:

exporters:
  otlphttp/bitfab:
    endpoint: https://bitfab.ai/api/sdk/otel
    encoding: json
    headers:
      Authorization: Bearer ${env:BITFAB_API_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/bitfab]

Every trace uses one delivery path: when the Collector endpoint is configured, the SDK does not also send the same batch directly to Bitfab.

See the Python 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.33.6.tar.gz (105.2 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.33.6-py3-none-any.whl (110.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: bitfab_py-0.33.6.tar.gz
  • Upload date:
  • Size: 105.2 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.6.tar.gz
Algorithm Hash digest
SHA256 56fc9f14e576b72cb941452520ffc3ada695119e15b3cfbad2dec6aa1eb2f7f6
MD5 7b9000024eced66b509afa04c8c20ea5
BLAKE2b-256 da42c2d96200de00788b2722d2169ec71f0ed3f45cb4f646042b485ae8524f6b

See more details on using hashes here.

Provenance

The following attestation bundles were made for bitfab_py-0.33.6.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.33.6-py3-none-any.whl.

File metadata

  • Download URL: bitfab_py-0.33.6-py3-none-any.whl
  • Upload date:
  • Size: 110.9 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.33.6-py3-none-any.whl
Algorithm Hash digest
SHA256 a44197e07ea594b1bffbbce481bd9ead26c087685a5ccd432a8a51f85dd0d2e9
MD5 f9b1d0f4f4efdaae478c3b19aac4ed3e
BLAKE2b-256 520036a3cebd20a58c83749c00d21bd74193d00be1d6c6d7c6262717f86ba044

See more details on using hashes here.

Provenance

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

0.39.0

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

This release

0.33.6 This release

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