Metadata-Version: 2.4
Name: bitpulse
Version: 0.1.0
Summary: Automatically capture and send LLM trace data from GraphBit applications to your observability API endpoint
Author-email: GraphBit Team <contact@infinitibit.ai>
Maintainer-email: GraphBit Team <contact@infinitibit.ai>
License: # GRAPHBIT FRAMEWORK LICENSE
        
        Copyright © 2023–2025 InfinitiBit GmbH. All rights reserved.
        
        By downloading, installing, or using the GraphBit framework (the “framework”), you agree to this License.
        
        ## 1. Parties
        
        Licensor: **InfinitiBit GmbH**, Heiglhofstr. 90, 81377 Munich, Germany.
        Licensee: The individual or legal entity using the framework.
        
        ## 2. Definitions
        
        * **framework**: The complete source code and related materials provided by Licensor, including the Rust core, Python wrapper, scripts, libraries, and configuration described in the GraphBit documentation.
        * **Outputs**: Results, data, and artifacts generated by the framework.
        * **Enterprise Use**: Any use not expressly permitted under Model A or Model B, including but not limited to: (i) use by organizations with more than ten (10) employees or more than ten (10) active users, (ii) embedding in commercial products/services, or (iii) offering the framework or derivative works as a hosted service (e.g., API, SaaS, managed platform).
        * **Active Users**: All persons using the framework, including employees, contractors, and/or end users accessing a product or service built on the framework.
        
        ## 3. License Models
        
        Any use not covered by Model A or Model B requires **Model C (Enterprise)** and a separate, executed license.
        
        ### Model A — Free Use
        
        **Eligibility:** Natural persons, academic/research institutions, and companies/startups with up to ten (10) employees **and** up to ten (10) Active Users.
        **Grant:** Non-exclusive, revocable, non-transferable right to install and use the framework.
        **Restrictions:** Redistribution (modified or unmodified) is **prohibited**.
        
        ### Model B — Free Trial (Evaluation Only)
        
        **Eligibility:** Legal entities/companies.
        **Grant:** Non-exclusive, revocable, non-transferable right to install and use the framework **solely for internal evaluation** for up to thirty (30) consecutive days.
        **Restrictions:** Redistribution and any commercial or production use are **prohibited**.
        
        ### Model C — Enterprise License (Paid)
        
        **Eligibility:** Anyone not covered by Model A or B.
        **Grant:** Rights for commercial/production use are available **only** under a separately executed Enterprise License with agreed fees and terms.
        **Restrictions:** **No** redistribution rights are granted by this public License. **Any** redistribution or sublicensing (modified or unmodified) must be expressly permitted in the separate Enterprise License.
        
        ## 4. Ownership of Outputs
        
        You own your **Outputs**. However, Outputs, logs, artifacts, or derived model weights may **not** be used to train, fine-tune, or distill any **competing large language model** without an Enterprise License.
        
        ## 5. Responsible Use (Prohibited Uses)
        
        You shall not use the framework or Outputs for:
        
        * illegal activities;
        * surveillance without lawful authority;
        * military or autonomous weapon systems;
        * disinformation;
        * life-critical systems (including medical devices, aviation, nuclear) **without** an Enterprise License;
        * any use reasonably expected to cause material harm to individuals, society, or the environment.
        
        ## 6. Additional Restrictions
        
        Except as expressly permitted above, you shall **not**:
        
        * copy, distribute, publish, sublicense, rent, lease, or otherwise make the framework available to third parties;
        * modify, adapt, or create derivative works **for any form of distribution**;
        * remove or alter any copyright, attribution, or proprietary notices.
        
        ## 7. Attribution & Trademarks
        
        If you publicly reference or showcase the framework (e.g., in documentation, UI credits, research papers, product pages) where such use is **permitted under this License or a separate Enterprise License**, include the attribution:
        
        > “Based on GraphBit by InfinitiBit GmbH https://graphbit.ai
        
        No rights are granted to use the Licensor’s names, logos, or trademarks beyond the attribution above. **This clause does not grant any right to distribute the framework.**
        
        ## 8. Termination
        
        Licensor may terminate this License with one month’s notice to the end of the following month. Either party may terminate for cause without notice if the other party materially breaches this License and fails to cure within a reasonable period after written notice, or upon the Licensee’s insolvency, or in case of actions likely to cause significant reputational damage to Licensor.
        Upon termination, you must immediately stop using the framework and destroy all copies. Unauthorized Enterprise Use obligates Licensee to pay retroactive license fees and damages.
        
        ## 9. Warranty Disclaimer
        
        THE FRAMEWORK IS PROVIDED “AS IS,” as described in the GraphBit documentation, **without** warranties of any kind, express or implied, including merchantability, fitness for a particular purpose, or non-infringement.
        
        ## 10. Limitation of Liability
        
        Licensor is liable only for defects and damages caused by intentional or grossly negligent conduct, and for damages resulting from injury to life, limb, or health, in accordance with applicable law.
        
        ## 11. Governing Law & Jurisdiction
        
        This License is governed by the laws of the Federal Republic of Germany. Exclusive jurisdiction lies with the competent courts of Munich, Germany.
        
        ## 12. Contact
        
        For Enterprise Licensing or commercial inquiries:
        [accounting@infinitibit.com](mailto:accounting@infinitibit.com) — [https://graphbit.ai](https://graphbit.ai)
        
Project-URL: Homepage, https://github.com/InfinitiBit/bitpulse
Project-URL: Documentation, https://docs.graphbit.ai
Project-URL: Repository, https://github.com/InfinitiBit/bitpulse
Project-URL: Bug Tracker, https://github.com/InfinitiBit/bitpulse/issues
Keywords: observability,tracing,llm,monitoring,graphbit,api,http
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: graphbit>=0.5.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: structlog>=23.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: loguru==0.7.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: black>=23.12.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Provides-Extra: export
Requires-Dist: pyarrow>=13.0.0; extra == "export"
Requires-Dist: openpyxl>=3.1.0; extra == "export"
Dynamic: license-file

# BitPulse

![Python Version](https://img.shields.io/badge/python-3.10--3.13-blue)
![License](https://img.shields.io/badge/license-GraphBit%20Framework-orange)
[![PyPI](https://img.shields.io/pypi/v/bitpulse.svg)](https://pypi.org/project/bitpulse/)




Production-grade LLM observability for GraphBit workflows.

- Zero-config automatic tracing for LLM calls and workflows
- Captures prompts, responses, tokens, latency, errors
- Sends trace data to your observability API endpoint

## Project Info

- Python: 3.10–3.13
- License: GraphBit Framework License
- PyPI: [bitpulse](https://pypi.org/project/bitpulse/)
- PRs: Welcome via GitHub pull requests

## Install

```bash
pip install bitpulse
```

Python: 3.10–3.13

## What It Does

BitPulse automatically captures detailed trace data from GraphBit LLM clients and workflows and submits it to your observability endpoint for monitoring, analytics, and debugging.

## Key Features

- Automatic tracing for LLM calls and workflows
- Rich metadata: prompts, responses, tokens, latency, finish reasons, errors
- Tool-call detection for agent workflows
- Works with OpenAI and GraphBit internals
- Type-safe models (Pydantic) and robust async I/O

## Quick Start

```python
import asyncio, os
from graphbit import LlmClient, LlmConfig
from bitpulse import AutoTracer

async def main():
    tracer = await AutoTracer.create()
    cfg = LlmConfig.openai(api_key=os.getenv("OPENAI_API_KEY"), model="gpt-4o-mini")
    client = tracer.wrap_client(LlmClient(cfg), cfg)
    resp = await client.complete_full_async("What is GraphBit?", max_tokens=100)
    results = await tracer.send()
    print("sent:", results["sent"], "failed:", results["failed"])

asyncio.run(main())
```

## Configuration

Set environment variables to configure external endpoints:

```bash
export BITPULSE_TRACING_API_KEY="your-api-key"
export BITPULSE_TRACEABLE_PROJECT="your-project-name"
# optional
export BITPULSE_TRACING_API_URL="https://your-api-endpoint.com/traces"
```

## Links


- GitHub: [InfinitiBit/bitpulse](https://github.com/InfinitiBit/bitpulse)
- Issues: [issue tracker](https://github.com/InfinitiBit/bitpulse/issues)

## License

GraphBit Framework License. See `LICENSE.md` in the repository.

## Trace Data Format Example

Example JSON payload sent to your observability endpoint:

```json
{
    "tracing_api_key": "your-api-key",
    "traceable_project_name": "your-project",
    "run_name": "LlmClient",
    "run_type": "llm",
    "status": "success",
    "input": "Hello, world!",
    "output": "Hi there!",
    "error": null,
    "start_time": "2025-01-01T00:00:00Z",
    "latency": 123.45,
    "tokens": 50,
    "metadata": {
        "model_name": "gpt-4o-mini",
        "provider": "openai",
        "input_tokens": 10,
        "output_tokens": 40,
        "finish_reason": "stop"
    }
}
```

## API Reference

High-level AutoTracer methods:

- `AutoTracer.create()`: Initialize tracer
- `wrap_client(llm_client, llm_config)`: Trace LLM client calls
- `wrap_executor(executor, llm_config)`: Trace workflow execution
- `send()`: Convert and submit captured spans to your endpoint
- `export()`: Export captured traces locally
