handit-ai

Name	handit-ai JSON
Version	1.0.2 JSON
	download
home_page	None
Summary	None
upload_time	2025-09-12 22:24:54
maintainer	None
docs_url	None
author	Handit
requires_python	>=3.8
license	Apache-2.0
keywords
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Python Package - Handit AI

🐍 **Python API and packaging for Handit tracing system**

This directory contains the Python interface to the Rust-powered Handit tracing engine. It provides both high-level APIs for easy integration and low-level bindings for advanced usage, packaged as `handit-ai` on PyPI.

## 📦 Package Structure

```
python/
├── pyproject.toml           # 📋 Package configuration & build settings
├── dist/                    # 📦 Built wheels and source distributions
├── handit_ai/              # 🎯 High-level Python API
│   ├── __init__.py         # Main public API
│   └── fastapi.py          # FastAPI middleware integration
└── handit_core/            # ⚙️ Low-level Rust bindings
    ├── __init__.py         # Core tracing functionality
    ├── http_instrumentation.py    # HTTP client patching
    ├── openai_instrumentation.py  # OpenAI API tracing
    └── handit_core_native.so      # Compiled Rust extension
```

## 🎯 High-Level API (`handit_ai`)

### Purpose
Provides a clean, developer-friendly interface for integrating Handit into Python applications.

### Key Features
- **Zero-config operation** with sensible defaults
- **Decorator-based tracing** for functions
- **Context manager sessions** for request boundaries
- **FastAPI middleware** for automatic web app tracing
- **Automatic instrumentation** enabling on import

### Usage Examples

#### Basic Function Tracing
```python
import handit

@handit.tracing(agent="payment-processor")
def process_payment(amount: float, token: str) -> dict:
    # Business logic here
    return {"status": "success", "charge_id": "ch_123"}

# Alternative using context manager
with handit.session(tag="checkout-flow"):
    result = process_payment(100.0, "tok_abc123")
```

#### Configuration
```python
import handit

# Configure endpoints and API keys
handit.configure(
    HANDIT_ENDPOINT="https://your-endpoint.com/events",
    HANDIT_API_KEY="your-api-key",
    HANDIT_SAMPLE_RATE="0.1",  # Sample 10% of traces
    HANDIT_MAX_STR="500"       # Limit string capture length
)
```

#### FastAPI Integration
```python
from fastapi import FastAPI
from handit_ai import HanditMiddleware

app = FastAPI()
app.add_middleware(HanditMiddleware, agent="api-server")

@app.get("/users/{user_id}")
async def get_user(user_id: str):
    # Automatically traced with request context
    return {"user_id": user_id, "name": "John Doe"}
```

## ⚙️ Low-Level Bindings (`handit_core`)

### Purpose
Provides direct access to the Rust engine with full control over tracing behavior.

### Key Components

#### Core Session Management
```python
from handit_core import session, start_session, on_call, on_return

# Manual session control
session_id = start_session(tag="custom-session", attrs={"env": "prod"})

# Manual event recording
on_call(session_id, "my_function", "__main__", "/app/main.py", 42, time_ns)
on_return(session_id, "my_function", end_time_ns, duration_ns)
```

#### Configuration Access
```python
import handit_core

# Low-level configuration
handit_core.configure(
    HANDIT_INCLUDE="myapp\..*",  # Only trace functions in 'myapp' module
    HANDIT_EXCLUDE="^(requests|urllib3)::",  # Exclude HTTP libraries
    HANDIT_CAPTURE_ONLY_CWD=True,  # Only trace current working directory
    HANDIT_REDACT="(?i)(password|token|secret)"  # PII redaction pattern
)
```

## 🌐 HTTP Instrumentation

### Automatic Patching
The system automatically instruments popular HTTP clients:

#### Supported Libraries
- **`requests`** - Synchronous HTTP client
- **`httpx`** - Modern async/sync HTTP client  
- **`aiohttp`** - Async HTTP client/server framework

#### What's Captured
```python
import requests  # Automatically patched on handit import

# This call is automatically traced:
response = requests.post(
    "https://api.stripe.com/v1/charges",
    headers={"Authorization": "Bearer sk_..."},  # Automatically redacted
    json={"amount": 10000, "currency": "usd"}
)

# Generates events:
# 1. http_request - method, URL, headers, body, timestamp
# 2. http_response - status, headers, body, duration, errors
```

#### Custom Instrumentation
```python
from handit_core.http_instrumentation import patch_requests

# Manual patching control
patch_requests(capture_request_body=True, capture_response_body=False)
```

## 🤖 OpenAI Integration

### Automatic API Tracing
```python
import openai  # Automatically patched
import handit

client = openai.OpenAI(api_key="sk-...")

with handit.session(tag="ai-assistant"):
    # Automatically traces both function calls AND HTTP requests
    completion = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}],
        temperature=0.7
    )
```

### Captured Data
- **Function calls**: `client.chat.completions.create()` with full parameters
- **HTTP requests**: Raw OpenAI API calls with request/response bodies
- **Return values**: Complete ChatCompletion objects
- **Timing**: Precise duration of LLM calls
- **Error handling**: Failed requests and API errors

## 🏗️ Build System

### PyO3 + Maturin
The package uses modern Rust-Python integration:

```toml
# pyproject.toml
[build-system]
requires = ["maturin>=1.0,<2.0"]
build-backend = "maturin"

[tool.maturin]
bindings = "pyo3"
manifest-path = "../handit-runtime/crates/py/Cargo.toml"
module-name = "handit_core.handit_core_native"
python-packages = ["handit_ai", "handit_core"]
```

### Building from Source
```bash
# Install build dependencies
pip install maturin

# Development build (with Python bindings)
maturin develop --features python

# Release build for distribution
maturin build --release --features python --sdist

# Create wheels for multiple platforms
maturin build --release --features python --target x86_64-unknown-linux-gnu
```

### Local Development
```bash
# Install in development mode
cd python/
pip install -e .

# Run with local changes
python examples/basic_demo.py
```

## 📊 Event Processing

### Event Flow
1. **Python code execution** triggers native profiler callbacks
2. **Rust engine** captures events with minimal overhead  
3. **Background thread** processes and buffers events
4. **Export system** flushes to files or HTTP endpoints

### Event Types Generated

#### Function Calls
```json
{
  "type": "call",
  "session_id": "sess_abc123",
  "func": "process_payment",
  "module": "myapp.payments",
  "file": "/app/payments.py",
  "line": 45,
  "t0_ns": 1703123456789000000,
  "args_preview": {
    "amount": "100.0",
    "token": "<redacted>"
  }
}
```

#### HTTP Requests
```json
{
  "type": "http_request", 
  "session_id": "sess_abc123",
  "method": "POST",
  "url": "https://api.stripe.com/v1/charges",
  "t0_ns": 1703123456789000000,
  "headers": {"authorization": "<redacted>"},
  "bytes_out": 1024,
  "request_body": "{\"amount\": 10000}"
}
```

#### Return Values
```json
{
  "type": "return",
  "session_id": "sess_abc123", 
  "func": "process_payment",
  "t1_ns": 1703123456890000000,
  "dt_ns": 101000000,
  "locals_preview": {
    "return": "{\"id\": \"ch_123\", \"status\": \"succeeded\"}"
  }
}
```

## 🔧 Configuration Options

### Environment Variables
```bash
# Core behavior
HANDIT_INCLUDE=".*"                    # Function inclusion pattern
HANDIT_EXCLUDE="^(requests|urllib3)::" # Function exclusion pattern
HANDIT_SAMPLE_RATE="1.0"               # Sampling rate (0.0-1.0)

# Data capture limits
HANDIT_MAX_STR="1000"                  # Max string length
HANDIT_MAX_LOCALS="50"                 # Max local variables to capture

# Export configuration  
HANDIT_OUTPUT_FILE="./handit_events.jsonl"  # Local file output
HANDIT_ENDPOINT="https://api.handit.ai/events"  # HTTP endpoint
HANDIT_API_KEY="your-api-key"          # API authentication

# Security
HANDIT_REDACT="(?i)(api_key|token|password|secret)"  # PII redaction
HANDIT_CAPTURE_ONLY_CWD="false"       # Restrict to current directory
```

### Programmatic Configuration
```python
import handit

handit.configure(
    # Export settings
    HANDIT_ENDPOINT="https://your-endpoint.com/events",
    HANDIT_API_KEY="your-key",
    
    # Performance tuning
    HANDIT_SAMPLE_RATE=0.1,  # 10% sampling
    HANDIT_MAX_STR=500,      # Shorter string previews
    
    # Security
    HANDIT_REDACT=r"(?i)(password|token|key|secret|auth)",
    
    # Filtering
    HANDIT_INCLUDE="myapp\..*",  # Only trace your app
    HANDIT_EXCLUDE="^(requests|urllib3|json)::"  # Skip common libraries
)
```

## 🚀 Performance Considerations

### Overhead Profile
- **Function calls**: ~0.5-1μs per call
- **HTTP requests**: ~5-10μs additional overhead
- **Memory usage**: ~1-2MB baseline + configurable buffers
- **CPU impact**: <1% for typical applications

### Optimization Tips
```python
# Reduce data capture for high-volume functions
handit.configure(
    HANDIT_MAX_STR=100,      # Shorter previews
    HANDIT_MAX_LOCALS=10,    # Fewer variables
    HANDIT_SAMPLE_RATE=0.01, # 1% sampling for hot paths
)

# Exclude noisy libraries
handit.configure(
    HANDIT_EXCLUDE=r"^(requests|urllib3|json|logging|threading)::"
)

# Restrict to application code only
handit.configure(
    HANDIT_INCLUDE="myapp\..*",
    HANDIT_CAPTURE_ONLY_CWD=True
)
```

## 🧪 Testing

### Unit Tests
```bash
# Test Python components
cd python/
python -m pytest tests/

# Test specific modules
python -m pytest tests/test_instrumentation.py -v
```

### Integration Tests  
```bash
# Test with real HTTP calls
python examples/nested_http_demo.py

# Test OpenAI integration (requires API key)
OPENAI_API_KEY=sk-... python examples/openai_test.py

# Test FastAPI middleware
python examples/fastapi_demo.py
```

### Performance Testing
```bash
# Benchmark overhead
python benchmarks/function_call_overhead.py

# Memory usage profiling
python -m memory_profiler examples/memory_benchmark.py
```

## 📚 Examples Usage

### Web Framework Integration
```python
# FastAPI
from fastapi import FastAPI
from handit_ai import HanditMiddleware

app = FastAPI()
app.add_middleware(HanditMiddleware, agent="api")

# Flask (manual)
from flask import Flask
import handit

app = Flask(__name__)

@app.route('/api/users')
@handit.tracing(agent="user-api")
def get_users():
    return {"users": []}
```

### Background Task Tracing
```python
import handit
from celery import Celery

app = Celery('tasks')

@app.task
@handit.tracing(agent="background-worker")
def process_upload(file_id: str):
    # Task processing automatically traced
    return {"status": "processed", "file_id": file_id}
```

### Database Query Tracing
```python
import handit
import psycopg2

@handit.tracing(agent="database")
def get_user_orders(user_id: str):
    with psycopg2.connect(DATABASE_URL) as conn:
        # SQL queries can be traced by decorating helper functions
        return fetch_orders(conn, user_id)

@handit.tracing(agent="sql-query") 
def fetch_orders(conn, user_id):
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM orders WHERE user_id = %s", (user_id,))
    return cursor.fetchall()
```

## 🔮 Future Enhancements

### Planned Features
- **Database instrumentation** for SQLAlchemy, Django ORM
- **Message queue tracing** for Celery, RQ, Kafka
- **Template engine instrumentation** for Jinja2, Django templates  
- **Custom metrics collection** beyond function calls

### API Improvements
- **Async context managers** for better async/await support
- **Type hints** for better IDE integration
- **Plugin system** for custom instrumentation
- **Real-time streaming** for live monitoring dashboards

---

**The Python package provides the friendly developer interface while leveraging Rust's performance for the heavy lifting.**

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "handit-ai",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": null,
    "author": "Handit",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/3b/6f/cc508c54f81effa0776057eb9ce74856bcefb2a1bdff01e00b6745ad415e/handit_ai-1.0.2.tar.gz",
    "platform": null,
    "description": "# Python Package - Handit AI\n\n\ud83d\udc0d **Python API and packaging for Handit tracing system**\n\nThis directory contains the Python interface to the Rust-powered Handit tracing engine. It provides both high-level APIs for easy integration and low-level bindings for advanced usage, packaged as `handit-ai` on PyPI.\n\n## \ud83d\udce6 Package Structure\n\n```\npython/\n\u251c\u2500\u2500 pyproject.toml           # \ud83d\udccb Package configuration & build settings\n\u251c\u2500\u2500 dist/                    # \ud83d\udce6 Built wheels and source distributions\n\u251c\u2500\u2500 handit_ai/              # \ud83c\udfaf High-level Python API\n\u2502   \u251c\u2500\u2500 __init__.py         # Main public API\n\u2502   \u2514\u2500\u2500 fastapi.py          # FastAPI middleware integration\n\u2514\u2500\u2500 handit_core/            # \u2699\ufe0f Low-level Rust bindings\n    \u251c\u2500\u2500 __init__.py         # Core tracing functionality\n    \u251c\u2500\u2500 http_instrumentation.py    # HTTP client patching\n    \u251c\u2500\u2500 openai_instrumentation.py  # OpenAI API tracing\n    \u2514\u2500\u2500 handit_core_native.so      # Compiled Rust extension\n```\n\n## \ud83c\udfaf High-Level API (`handit_ai`)\n\n### Purpose\nProvides a clean, developer-friendly interface for integrating Handit into Python applications.\n\n### Key Features\n- **Zero-config operation** with sensible defaults\n- **Decorator-based tracing** for functions\n- **Context manager sessions** for request boundaries\n- **FastAPI middleware** for automatic web app tracing\n- **Automatic instrumentation** enabling on import\n\n### Usage Examples\n\n#### Basic Function Tracing\n```python\nimport handit\n\n@handit.tracing(agent=\"payment-processor\")\ndef process_payment(amount: float, token: str) -> dict:\n    # Business logic here\n    return {\"status\": \"success\", \"charge_id\": \"ch_123\"}\n\n# Alternative using context manager\nwith handit.session(tag=\"checkout-flow\"):\n    result = process_payment(100.0, \"tok_abc123\")\n```\n\n#### Configuration\n```python\nimport handit\n\n# Configure endpoints and API keys\nhandit.configure(\n    HANDIT_ENDPOINT=\"https://your-endpoint.com/events\",\n    HANDIT_API_KEY=\"your-api-key\",\n    HANDIT_SAMPLE_RATE=\"0.1\",  # Sample 10% of traces\n    HANDIT_MAX_STR=\"500\"       # Limit string capture length\n)\n```\n\n#### FastAPI Integration\n```python\nfrom fastapi import FastAPI\nfrom handit_ai import HanditMiddleware\n\napp = FastAPI()\napp.add_middleware(HanditMiddleware, agent=\"api-server\")\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: str):\n    # Automatically traced with request context\n    return {\"user_id\": user_id, \"name\": \"John Doe\"}\n```\n\n## \u2699\ufe0f Low-Level Bindings (`handit_core`)\n\n### Purpose\nProvides direct access to the Rust engine with full control over tracing behavior.\n\n### Key Components\n\n#### Core Session Management\n```python\nfrom handit_core import session, start_session, on_call, on_return\n\n# Manual session control\nsession_id = start_session(tag=\"custom-session\", attrs={\"env\": \"prod\"})\n\n# Manual event recording\non_call(session_id, \"my_function\", \"__main__\", \"/app/main.py\", 42, time_ns)\non_return(session_id, \"my_function\", end_time_ns, duration_ns)\n```\n\n#### Configuration Access\n```python\nimport handit_core\n\n# Low-level configuration\nhandit_core.configure(\n    HANDIT_INCLUDE=\"myapp\\..*\",  # Only trace functions in 'myapp' module\n    HANDIT_EXCLUDE=\"^(requests|urllib3)::\",  # Exclude HTTP libraries\n    HANDIT_CAPTURE_ONLY_CWD=True,  # Only trace current working directory\n    HANDIT_REDACT=\"(?i)(password|token|secret)\"  # PII redaction pattern\n)\n```\n\n## \ud83c\udf10 HTTP Instrumentation\n\n### Automatic Patching\nThe system automatically instruments popular HTTP clients:\n\n#### Supported Libraries\n- **`requests`** - Synchronous HTTP client\n- **`httpx`** - Modern async/sync HTTP client  \n- **`aiohttp`** - Async HTTP client/server framework\n\n#### What's Captured\n```python\nimport requests  # Automatically patched on handit import\n\n# This call is automatically traced:\nresponse = requests.post(\n    \"https://api.stripe.com/v1/charges\",\n    headers={\"Authorization\": \"Bearer sk_...\"},  # Automatically redacted\n    json={\"amount\": 10000, \"currency\": \"usd\"}\n)\n\n# Generates events:\n# 1. http_request - method, URL, headers, body, timestamp\n# 2. http_response - status, headers, body, duration, errors\n```\n\n#### Custom Instrumentation\n```python\nfrom handit_core.http_instrumentation import patch_requests\n\n# Manual patching control\npatch_requests(capture_request_body=True, capture_response_body=False)\n```\n\n## \ud83e\udd16 OpenAI Integration\n\n### Automatic API Tracing\n```python\nimport openai  # Automatically patched\nimport handit\n\nclient = openai.OpenAI(api_key=\"sk-...\")\n\nwith handit.session(tag=\"ai-assistant\"):\n    # Automatically traces both function calls AND HTTP requests\n    completion = client.chat.completions.create(\n        model=\"gpt-4\",\n        messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n        temperature=0.7\n    )\n```\n\n### Captured Data\n- **Function calls**: `client.chat.completions.create()` with full parameters\n- **HTTP requests**: Raw OpenAI API calls with request/response bodies\n- **Return values**: Complete ChatCompletion objects\n- **Timing**: Precise duration of LLM calls\n- **Error handling**: Failed requests and API errors\n\n## \ud83c\udfd7\ufe0f Build System\n\n### PyO3 + Maturin\nThe package uses modern Rust-Python integration:\n\n```toml\n# pyproject.toml\n[build-system]\nrequires = [\"maturin>=1.0,<2.0\"]\nbuild-backend = \"maturin\"\n\n[tool.maturin]\nbindings = \"pyo3\"\nmanifest-path = \"../handit-runtime/crates/py/Cargo.toml\"\nmodule-name = \"handit_core.handit_core_native\"\npython-packages = [\"handit_ai\", \"handit_core\"]\n```\n\n### Building from Source\n```bash\n# Install build dependencies\npip install maturin\n\n# Development build (with Python bindings)\nmaturin develop --features python\n\n# Release build for distribution\nmaturin build --release --features python --sdist\n\n# Create wheels for multiple platforms\nmaturin build --release --features python --target x86_64-unknown-linux-gnu\n```\n\n### Local Development\n```bash\n# Install in development mode\ncd python/\npip install -e .\n\n# Run with local changes\npython examples/basic_demo.py\n```\n\n## \ud83d\udcca Event Processing\n\n### Event Flow\n1. **Python code execution** triggers native profiler callbacks\n2. **Rust engine** captures events with minimal overhead  \n3. **Background thread** processes and buffers events\n4. **Export system** flushes to files or HTTP endpoints\n\n### Event Types Generated\n\n#### Function Calls\n```json\n{\n  \"type\": \"call\",\n  \"session_id\": \"sess_abc123\",\n  \"func\": \"process_payment\",\n  \"module\": \"myapp.payments\",\n  \"file\": \"/app/payments.py\",\n  \"line\": 45,\n  \"t0_ns\": 1703123456789000000,\n  \"args_preview\": {\n    \"amount\": \"100.0\",\n    \"token\": \"<redacted>\"\n  }\n}\n```\n\n#### HTTP Requests\n```json\n{\n  \"type\": \"http_request\", \n  \"session_id\": \"sess_abc123\",\n  \"method\": \"POST\",\n  \"url\": \"https://api.stripe.com/v1/charges\",\n  \"t0_ns\": 1703123456789000000,\n  \"headers\": {\"authorization\": \"<redacted>\"},\n  \"bytes_out\": 1024,\n  \"request_body\": \"{\\\"amount\\\": 10000}\"\n}\n```\n\n#### Return Values\n```json\n{\n  \"type\": \"return\",\n  \"session_id\": \"sess_abc123\", \n  \"func\": \"process_payment\",\n  \"t1_ns\": 1703123456890000000,\n  \"dt_ns\": 101000000,\n  \"locals_preview\": {\n    \"return\": \"{\\\"id\\\": \\\"ch_123\\\", \\\"status\\\": \\\"succeeded\\\"}\"\n  }\n}\n```\n\n## \ud83d\udd27 Configuration Options\n\n### Environment Variables\n```bash\n# Core behavior\nHANDIT_INCLUDE=\".*\"                    # Function inclusion pattern\nHANDIT_EXCLUDE=\"^(requests|urllib3)::\" # Function exclusion pattern\nHANDIT_SAMPLE_RATE=\"1.0\"               # Sampling rate (0.0-1.0)\n\n# Data capture limits\nHANDIT_MAX_STR=\"1000\"                  # Max string length\nHANDIT_MAX_LOCALS=\"50\"                 # Max local variables to capture\n\n# Export configuration  \nHANDIT_OUTPUT_FILE=\"./handit_events.jsonl\"  # Local file output\nHANDIT_ENDPOINT=\"https://api.handit.ai/events\"  # HTTP endpoint\nHANDIT_API_KEY=\"your-api-key\"          # API authentication\n\n# Security\nHANDIT_REDACT=\"(?i)(api_key|token|password|secret)\"  # PII redaction\nHANDIT_CAPTURE_ONLY_CWD=\"false\"       # Restrict to current directory\n```\n\n### Programmatic Configuration\n```python\nimport handit\n\nhandit.configure(\n    # Export settings\n    HANDIT_ENDPOINT=\"https://your-endpoint.com/events\",\n    HANDIT_API_KEY=\"your-key\",\n    \n    # Performance tuning\n    HANDIT_SAMPLE_RATE=0.1,  # 10% sampling\n    HANDIT_MAX_STR=500,      # Shorter string previews\n    \n    # Security\n    HANDIT_REDACT=r\"(?i)(password|token|key|secret|auth)\",\n    \n    # Filtering\n    HANDIT_INCLUDE=\"myapp\\..*\",  # Only trace your app\n    HANDIT_EXCLUDE=\"^(requests|urllib3|json)::\"  # Skip common libraries\n)\n```\n\n## \ud83d\ude80 Performance Considerations\n\n### Overhead Profile\n- **Function calls**: ~0.5-1\u03bcs per call\n- **HTTP requests**: ~5-10\u03bcs additional overhead\n- **Memory usage**: ~1-2MB baseline + configurable buffers\n- **CPU impact**: <1% for typical applications\n\n### Optimization Tips\n```python\n# Reduce data capture for high-volume functions\nhandit.configure(\n    HANDIT_MAX_STR=100,      # Shorter previews\n    HANDIT_MAX_LOCALS=10,    # Fewer variables\n    HANDIT_SAMPLE_RATE=0.01, # 1% sampling for hot paths\n)\n\n# Exclude noisy libraries\nhandit.configure(\n    HANDIT_EXCLUDE=r\"^(requests|urllib3|json|logging|threading)::\"\n)\n\n# Restrict to application code only\nhandit.configure(\n    HANDIT_INCLUDE=\"myapp\\..*\",\n    HANDIT_CAPTURE_ONLY_CWD=True\n)\n```\n\n## \ud83e\uddea Testing\n\n### Unit Tests\n```bash\n# Test Python components\ncd python/\npython -m pytest tests/\n\n# Test specific modules\npython -m pytest tests/test_instrumentation.py -v\n```\n\n### Integration Tests  \n```bash\n# Test with real HTTP calls\npython examples/nested_http_demo.py\n\n# Test OpenAI integration (requires API key)\nOPENAI_API_KEY=sk-... python examples/openai_test.py\n\n# Test FastAPI middleware\npython examples/fastapi_demo.py\n```\n\n### Performance Testing\n```bash\n# Benchmark overhead\npython benchmarks/function_call_overhead.py\n\n# Memory usage profiling\npython -m memory_profiler examples/memory_benchmark.py\n```\n\n## \ud83d\udcda Examples Usage\n\n### Web Framework Integration\n```python\n# FastAPI\nfrom fastapi import FastAPI\nfrom handit_ai import HanditMiddleware\n\napp = FastAPI()\napp.add_middleware(HanditMiddleware, agent=\"api\")\n\n# Flask (manual)\nfrom flask import Flask\nimport handit\n\napp = Flask(__name__)\n\n@app.route('/api/users')\n@handit.tracing(agent=\"user-api\")\ndef get_users():\n    return {\"users\": []}\n```\n\n### Background Task Tracing\n```python\nimport handit\nfrom celery import Celery\n\napp = Celery('tasks')\n\n@app.task\n@handit.tracing(agent=\"background-worker\")\ndef process_upload(file_id: str):\n    # Task processing automatically traced\n    return {\"status\": \"processed\", \"file_id\": file_id}\n```\n\n### Database Query Tracing\n```python\nimport handit\nimport psycopg2\n\n@handit.tracing(agent=\"database\")\ndef get_user_orders(user_id: str):\n    with psycopg2.connect(DATABASE_URL) as conn:\n        # SQL queries can be traced by decorating helper functions\n        return fetch_orders(conn, user_id)\n\n@handit.tracing(agent=\"sql-query\") \ndef fetch_orders(conn, user_id):\n    cursor = conn.cursor()\n    cursor.execute(\"SELECT * FROM orders WHERE user_id = %s\", (user_id,))\n    return cursor.fetchall()\n```\n\n## \ud83d\udd2e Future Enhancements\n\n### Planned Features\n- **Database instrumentation** for SQLAlchemy, Django ORM\n- **Message queue tracing** for Celery, RQ, Kafka\n- **Template engine instrumentation** for Jinja2, Django templates  \n- **Custom metrics collection** beyond function calls\n\n### API Improvements\n- **Async context managers** for better async/await support\n- **Type hints** for better IDE integration\n- **Plugin system** for custom instrumentation\n- **Real-time streaming** for live monitoring dashboards\n\n---\n\n**The Python package provides the friendly developer interface while leveraging Rust's performance for the heavy lifting.**\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": null,
    "version": "1.0.2",
    "project_urls": {
        "Homepage": "https://example.com"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "41a9815d4c66d61ae035928a81ba3c18ca700af801730090bbf30d7648d72ec7",
                "md5": "6e41e7a04643cef7cb635e9c255074f5",
                "sha256": "343f536084d93293d4379b397e520132b51d380b2a8a4a63f1a486bf42d177fa"
            },
            "downloads": -1,
            "filename": "handit_ai-1.0.2-cp313-cp313-macosx_11_0_arm64.whl",
            "has_sig": false,
            "md5_digest": "6e41e7a04643cef7cb635e9c255074f5",
            "packagetype": "bdist_wheel",
            "python_version": "cp313",
            "requires_python": ">=3.8",
            "size": 2566793,
            "upload_time": "2025-09-12T22:24:52",
            "upload_time_iso_8601": "2025-09-12T22:24:52.948228Z",
            "url": "https://files.pythonhosted.org/packages/41/a9/815d4c66d61ae035928a81ba3c18ca700af801730090bbf30d7648d72ec7/handit_ai-1.0.2-cp313-cp313-macosx_11_0_arm64.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "3b6fcc508c54f81effa0776057eb9ce74856bcefb2a1bdff01e00b6745ad415e",
                "md5": "171a9fe75545cdbb504a19303710b794",
                "sha256": "edb4284d26e75803e928ae1255ce2ad0a03e7d7e047d5636cac8b66077032ad9"
            },
            "downloads": -1,
            "filename": "handit_ai-1.0.2.tar.gz",
            "has_sig": false,
            "md5_digest": "171a9fe75545cdbb504a19303710b794",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 53565,
            "upload_time": "2025-09-12T22:24:54",
            "upload_time_iso_8601": "2025-09-12T22:24:54.228613Z",
            "url": "https://files.pythonhosted.org/packages/3b/6f/cc508c54f81effa0776057eb9ce74856bcefb2a1bdff01e00b6745ad415e/handit_ai-1.0.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-09-12 22:24:54",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "handit-ai"
}