High-performance research service for bundlab
A cutting-edge microservice combining Python's flexibility with C++ performance for blazing-fast research operations.
Features • Installation • Quick Start • API Documentation • Architecture
bundlab service is a production-ready research microservice designed for high-throughput data processing and analysis. It leverages a Python/FastAPI interface for ease of development and a low-latency C++ worker bridge for computationally intensive operations, delivering enterprise-grade performance without sacrificing developer experience.
- ⚡ High Performance: C++ worker backend for CPU-intensive operations
- 🐍 Pythonic API: Modern FastAPI interface for seamless integration
- 🔄 Async-First: Built on async/await for non-blocking I/O
- 📊 Research-Ready: Optimized for data-intensive research workflows
- 🛡️ Production-Grade: Error handling, logging, and monitoring built-in
- 🔌 RESTful Design: Standard HTTP/REST API with comprehensive documentation
- Fast Data Processing: Optimized C++ backend for research computations
- Scalable Architecture: Designed for horizontal scaling and load balancing
- Low Latency: Worker bridge minimizes overhead between Python and C++ layers
- Comprehensive Logging: Built-in request/response logging and performance metrics
- Type Safety: Full type hints and validation throughout the codebase
- API Documentation: Auto-generated interactive Swagger/OpenAPI docs
- Batch processing support for bulk operations
- Request queuing and prioritization
- Real-time performance monitoring
- Graceful degradation and fallback mechanisms
- Configurable worker pool management
- Python 3.9 or higher
- pip or poetry for dependency management
- C++ Compiler (g++, clang, or MSVC) for building the worker bridge
- CMake 3.15+ (optional, for advanced builds)
# Clone the repository
git clone https://github.com/bundlab/bundlab-service.git
cd bundlab-service
# Create a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Build C++ worker bridge
python setup.py build_ext --inplace
# Or with poetry
poetry install# Build the Docker image
docker build -t bundlab-service:latest .
# Run the container
docker run -p 8000:8000 bundlab-service:latestpip install bundlab-service# Development server with auto-reload
uvicorn main:app --reload
# Production server with multiple workers
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4import httpx
# Create async client
async with httpx.AsyncClient() as client:
# Example research operation
response = await client.post(
"http://localhost:8000/api/v1/process",
json={"data": [...], "parameters": {...}},
timeout=30.0
)
result = response.json()
print(result)# Health check
curl http://localhost:8000/health
# Process data
curl -X POST http://localhost:8000/api/v1/process \
-H "Content-Type: application/json" \
-d '{"data": [...], "parameters": {...}}'
# Get status
curl http://localhost:8000/api/v1/status/{task_id}Once the service is running, visit:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
GET /health
Returns service health status and version information.
POST /api/v1/process
Content-Type: application/json
{
"data": [...],
"parameters": {
"algorithm": "string",
"config": {...}
}
}
GET /api/v1/status/{task_id}
Retrieve the status and results of a submitted task.
POST /api/v1/batch
Content-Type: application/json
{
"tasks": [
{"data": [...], "parameters": {...}},
{"data": [...], "parameters": {...}}
]
}
┌─────────────────────────────────────┐
│ Client Applications │
└──────────────┬──────────────────────┘
│ HTTP/REST
┌──────────────▼──────────────────────┐
│ FastAPI Application Server │
│ (Async Request Handling) │
└──────────────┬──────────────────────┘
│ IPC/Native Bridge
┌──────────────▼──────────────────────┐
│ C++ Worker Pool │
│ (High-Performance Computation) │
└─────────────────────────────────────┘
- Request routing and validation
- Async request/response handling
- Caching and rate limiting
- Logging and monitoring
- Authentication and authorization
- Optimized data processing algorithms
- Native memory management
- Multi-threaded computation
- Zero-copy data transfer where possible
- Performance profiling hooks
┌──────────────────────────────────────┐
│ Load Balancer (nginx/HAProxy) │
└──────────────┬───────────────────────┘
│
┌──────────┼──────────┐
│ │ │
┌───▼───┐ ┌──▼───┐ ┌───▼───┐
│ App-1 │ │ App-2 │ │ App-3 │
└───────┘ └───────┘ └───────┘
from bundlab_service.client import BundlabClient
import asyncio
async def main():
client = BundlabClient("http://localhost:8000")
# Process single request
result = await client.process(
data=[1, 2, 3, 4, 5],
parameters={"operation": "analyze"}
)
print(f"Result: {result}")
# Batch processing
tasks = [
{"data": [1, 2, 3], "parameters": {"op": "sum"}},
{"data": [4, 5, 6], "parameters": {"op": "avg"}},
]
results = await client.batch_process(tasks)
print(f"Batch Results: {results}")
asyncio.run(main())const axios = require('axios');
async function processData() {
try {
const response = await axios.post('http://localhost:8000/api/v1/process', {
data: [1, 2, 3, 4, 5],
parameters: { operation: 'analyze' }
});
console.log('Result:', response.data);
} catch (error) {
console.error('Error:', error.message);
}
}
processData();# Server Configuration
SERVICE_PORT=8000
SERVICE_HOST=0.0.0.0
LOG_LEVEL=INFO
DEBUG_MODE=false
# Worker Configuration
WORKER_THREADS=4
WORKER_TIMEOUT=30
MAX_QUEUE_SIZE=1000
# Performance Tuning
CACHE_ENABLED=true
CACHE_TTL=3600
BATCH_SIZE=100Create config.yaml:
server:
host: 0.0.0.0
port: 8000
workers: 4
workers:
thread_pool_size: 4
timeout: 30
max_retries: 3
logging:
level: INFO
format: json
file: logs/service.log
performance:
enable_caching: true
cache_ttl: 3600
batch_size: 100# Run all tests
pytest
# Run with coverage
pytest --cov=src --cov-report=html
# Run specific test file
pytest tests/test_api.py
# Run with verbose output
pytest -v# Generate coverage report
pytest --cov=src --cov-report=term-missing- Worker Pool Size: Set to 2x CPU cores for optimal throughput
- Batch Processing: Use batch endpoints for bulk operations (10-50% faster)
- Caching: Enable for repeated queries on same data
- Connection Pooling: Use connection pools in clients
- Load Balancing: Distribute across multiple instances
Example performance metrics (hardware-dependent)
| Operation | Latency | Throughput |
|---|---|---|
| Health Check | < 1ms | > 10k req/s |
| Single Process | 10-50ms | 1-5k req/s |
| Batch Process (100) | 200-500ms | 5-10k req/s |
- ✅ Always validate and sanitize input data
- ✅ Use HTTPS in production
- ✅ Implement authentication (JWT, API keys)
- ✅ Enable CORS appropriately
- ✅ Rate limit API endpoints
- ✅ Monitor for suspicious activity
- ✅ Keep dependencies updated
from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer
security = HTTPBearer()
async def verify_token(credentials = Depends(security)):
token = credentials.credentials
# Validate token
return tokenDEBUG - Detailed diagnostic information
INFO - General informational messages
WARNING - Warning messages for unusual situations
ERROR - Error messages for failed operations
CRITICAL - Critical errors requiring immediate attention
# View real-time logs
tail -f logs/service.log
# Search logs
grep "error" logs/service.log
# Parse JSON logs
cat logs/service.log | jq '.level == "ERROR"'We welcome contributions! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
# Install dev dependencies
pip install -r requirements-dev.txt
# Run linters
flake8 src/ tests/
black --check src/ tests/
mypy src/
# Format code
black src/ tests/
isort src/ tests/This project is licensed under the MIT License - see the LICENSE file for details.
- 📖 Documentation: Check our docs directory
- 💬 GitHub Issues: Report bugs or request features
- 📧 Email: support@bundlab.org
- 🐦 Twitter: @bundlab
Please report security vulnerabilities responsibly to security@bundlab.org instead of using the issue tracker.
Built with ❤️ using:
- FastAPI - Modern Python web framework
- Uvicorn - Lightning-fast ASGI server
- Pydantic - Data validation using Python type hints
- ✅ Actively maintained
- ✅ Production-ready
- ✅ Well-tested
- ✅ Continuously improving
Made with ❤️ by the bundlab Team