kalibr 1.0.18__py3-none-any.whl → 1.0.20__py3-none-any.whl

kalibr-1.0.20.data/data/examples/README.md

@@ -0,0 +1,173 @@
+# Enhanced Kalibr SDK Examples
+
+This directory contains examples demonstrating both the original function-level Kalibr capabilities and the new enhanced app-level features.
+
+## Examples Included
+
+### 1. Basic Kalibr Example (`basic_kalibr_example.py`)
+Demonstrates the original Kalibr SDK capabilities:
+- Simple function decoration with `@sdk.action()`
+- Basic parameter handling and type inference
+- Compatible with GPT Actions and Claude MCP
+- Simple API endpoints
+
+**Features shown:**
+- Text processing functions
+- Mathematical calculations  
+- Email validation
+- Text statistics
+
+**To run:**
+```bash
+kalibr serve basic_kalibr_example.py
+```
+
+**Test endpoints:**
+- `POST /proxy/greet` - Greeting function
+- `POST /proxy/calculate` - Basic calculator
+- `POST /proxy/validate_email` - Email validation
+- `POST /proxy/text_stats` - Text analysis
+
+### 2. Enhanced Kalibr Example (`enhanced_kalibr_example.py`)
+Demonstrates the new enhanced app-level capabilities:
+- File upload handling
+- Session management
+- Streaming responses
+- Complex workflows
+- Multi-model schema generation
+
+**Features shown:**
+- File upload and analysis
+- Session-based note taking
+- Real-time streaming data
+- Multi-step workflows
+- Advanced parameter handling
+
+**To run:**
+```bash
+kalibr serve enhanced_kalibr_example.py --app-mode
+```
+
+**Test endpoints:**
+- `POST /upload/analyze_document` - File upload analysis
+- `POST /session/save_note` - Session-based note saving
+- `GET /stream/count_with_progress` - Streaming counter
+- `POST /workflow/process_text_analysis` - Complex text workflow
+
+## Multi-Model Integration
+
+Both examples automatically generate schemas for multiple AI models:
+
+### Available Schema Endpoints:
+- **Claude MCP**: `/mcp.json`
+- **GPT Actions**: `/openapi.json` 
+- **Gemini Extensions**: `/schemas/gemini`
+- **Microsoft Copilot**: `/schemas/copilot`
+
+### Management Endpoints:
+- **Health Check**: `/health`
+- **Supported Models**: `/models/supported`
+- **API Documentation**: `/docs`
+
+## Usage Examples
+
+### Basic Function Call:
+```bash
+curl -X POST http://localhost:8000/proxy/greet \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice", "greeting": "Hi"}'
+```
+
+### File Upload:
+```bash
+curl -X POST http://localhost:8000/upload/analyze_document \
+  -F "file=@example.txt"
+```
+
+### Session Management:
+```bash
+# Save a note (creates session)
+curl -X POST http://localhost:8000/session/save_note \
+  -H "Content-Type: application/json" \
+  -d '{"note_title": "My Note", "note_content": "This is a test note"}'
+
+# Get notes (use session ID from previous response)
+curl -X POST http://localhost:8000/session/get_notes \
+  -H "Content-Type: application/json" \
+  -H "x-session-id: <session-id-here>" \
+  -d '{}'
+```
+
+### Streaming Data:
+```bash
+curl http://localhost:8000/stream/count_with_progress?max_count=5&delay_seconds=1
+```
+
+### Complex Workflow:
+```bash
+curl -X POST http://localhost:8000/workflow/process_text_analysis \
+  -H "Content-Type: application/json" \
+  -d '{"text": "This is a sample text for analysis. It contains multiple sentences and words for testing the workflow capabilities."}'
+```
+
+## Integration with AI Models
+
+### GPT Actions Setup:
+1. Copy the OpenAPI schema from `/openapi.json`
+2. Create a new GPT Action in ChatGPT
+3. Paste the schema and set the base URL
+
+### Claude MCP Setup:
+1. Add the MCP server configuration:
+```json
+{
+  "mcp": {
+    "servers": {
+      "kalibr": {
+        "command": "curl",
+        "args": ["http://localhost:8000/mcp.json"]
+      }
+    }
+  }
+}
+```
+
+### Gemini Extensions:
+1. Use the schema from `/schemas/gemini`
+2. Configure according to Gemini's extension documentation
+
+### Microsoft Copilot:
+1. Use the schema from `/schemas/copilot`  
+2. Follow Microsoft's plugin development guidelines
+
+## Advanced Features
+
+### Authentication (Optional):
+Uncomment the authentication line in enhanced example:
+```python
+app.enable_auth("your-secret-jwt-key-here")
+```
+
+### Custom Schema Generation:
+The framework supports extensible schema generation for future AI models through the `CustomModelSchemaGenerator` class.
+
+### Error Handling:
+All endpoints include comprehensive error handling with meaningful error messages.
+
+### Type Safety:
+Full support for Python type hints with automatic schema generation.
+
+## Development Notes
+
+- The enhanced framework is backward compatible with original Kalibr apps
+- Session data is stored in memory (use external storage for production)
+- File uploads are handled in memory (implement persistent storage as needed)
+- Streaming uses Server-Sent Events (SSE) format
+- All examples include proper async/await handling where needed
+
+## Next Steps
+
+1. Try the examples with different AI models
+2. Modify the examples to fit your specific use case
+3. Explore the source code in `/app/backend/kalibr/` for advanced customization
+4. Build your own enhanced Kalibr applications!

kalibr-1.0.20.data/data/examples/basic_kalibr_example.py

@@ -0,0 +1,66 @@
+"""
+Basic Kalibr SDK Example - Function-level API integration
+This demonstrates the original function-level capabilities of Kalibr.
+"""
+
+from kalibr import Kalibr
+
+# Create a basic Kalibr instance
+sdk = Kalibr(title="Basic Kalibr Demo", base_url="http://localhost:8000")
+
+@sdk.action("greet", "Greet someone with a personalized message")
+def greet_user(name: str, greeting: str = "Hello"):
+    """Simple greeting function"""
+    return {"message": f"{greeting}, {name}! Welcome to Kalibr SDK."}
+
+@sdk.action("calculate", "Perform basic mathematical operations")
+def calculate(operation: str, a: float, b: float):
+    """Basic calculator functionality"""
+    operations = {
+        "add": a + b,
+        "subtract": a - b,
+        "multiply": a * b,
+        "divide": a / b if b != 0 else None
+    }
+    
+    result = operations.get(operation)
+    if result is None:
+        return {"error": f"Invalid operation '{operation}' or division by zero"}
+    
+    return {
+        "operation": operation,
+        "operands": [a, b],
+        "result": result
+    }
+
+@sdk.action("validate_email", "Check if an email address is valid")
+def validate_email(email: str):
+    """Simple email validation"""
+    import re
+    
+    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+    is_valid = bool(re.match(pattern, email))
+    
+    return {
+        "email": email,
+        "is_valid": is_valid,
+        "message": "Valid email address" if is_valid else "Invalid email format"
+    }
+
+@sdk.action("text_stats", "Get statistics about a text string")
+def text_statistics(text: str):
+    """Analyze text and return statistics"""
+    words = text.split()
+    sentences = text.split('.') + text.split('!') + text.split('?')
+    sentences = [s.strip() for s in sentences if s.strip()]
+    
+    return {
+        "character_count": len(text),
+        "word_count": len(words),
+        "sentence_count": len(sentences),
+        "average_word_length": sum(len(word) for word in words) / len(words) if words else 0,
+        "longest_word": max(words, key=len) if words else None
+    }
+
+# The SDK instance is automatically discovered by the Kalibr CLI
+# To run this: kalibr serve basic_kalibr_example.py

kalibr-1.0.20.data/data/examples/enhanced_kalibr_example.py

@@ -0,0 +1,347 @@
+"""
+Enhanced Kalibr App Example - App-level capabilities
+This demonstrates the new enhanced capabilities including file uploads,
+sessions, streaming, workflows, and multi-model schema generation.
+"""
+
+from kalibr import KalibrApp
+from kalibr.types import FileUpload, Session, StreamingResponse, WorkflowState, AuthenticatedUser
+import asyncio
+import json
+from datetime import datetime
+from typing import List
+
+# Create an enhanced KalibrApp instance
+app = KalibrApp(title="Enhanced Kalibr Demo", base_url="http://localhost:8000")
+
+# Basic action (compatible with original Kalibr)
+@app.action("hello", "Say hello with enhanced capabilities")
+def hello_enhanced(name: str = "World", include_timestamp: bool = False):
+    """Enhanced hello function with optional timestamp"""
+    message = f"Hello, {name}! This is Enhanced Kalibr v2.0"
+    
+    response = {"message": message}
+    if include_timestamp:
+        response["timestamp"] = datetime.now().isoformat()
+    
+    return response
+
+# File upload handler
+@app.file_handler("analyze_document", [".txt", ".md", ".py", ".js", ".json"])
+async def analyze_document(file: FileUpload):
+    """Analyze uploaded document and return insights"""
+    try:
+        # Decode file content
+        content = file.content.decode('utf-8')
+        
+        # Basic analysis
+        lines = content.split('\n')
+        words = content.split()
+        
+        # Language detection based on file extension
+        language = "text"
+        if file.filename.endswith('.py'):
+            language = "python"
+        elif file.filename.endswith('.js'):
+            language = "javascript"
+        elif file.filename.endswith('.json'):
+            language = "json"
+            try:
+                json_data = json.loads(content)
+                return {
+                    "upload_id": file.upload_id,
+                    "filename": file.filename,
+                    "analysis": {
+                        "type": "json",
+                        "valid_json": True,
+                        "keys": list(json_data.keys()) if isinstance(json_data, dict) else None,
+                        "size_bytes": file.size
+                    }
+                }
+            except json.JSONDecodeError:
+                pass
+        
+        return {
+            "upload_id": file.upload_id,
+            "filename": file.filename,
+            "analysis": {
+                "language": language,
+                "line_count": len(lines),
+                "word_count": len(words),
+                "character_count": len(content),
+                "size_bytes": file.size,
+                "non_empty_lines": len([line for line in lines if line.strip()]),
+                "estimated_reading_time_minutes": len(words) / 200  # Average reading speed
+            }
+        }
+    except UnicodeDecodeError:
+        return {
+            "upload_id": file.upload_id,
+            "filename": file.filename,
+            "error": "File is not text-readable (binary file)",
+            "size_bytes": file.size
+        }
+
+# Session-aware action
+@app.session_action("save_note", "Save a note to user session")
+async def save_note(session: Session, note_title: str, note_content: str):
+    """Save a note to the user's session"""
+    
+    # Initialize notes if not exists
+    if 'notes' not in session.data:
+        session.data['notes'] = []
+    
+    # Create note object
+    note = {
+        "id": len(session.data['notes']) + 1,
+        "title": note_title,
+        "content": note_content,
+        "created_at": datetime.now().isoformat(),
+        "updated_at": datetime.now().isoformat()
+    }
+    
+    session.data['notes'].append(note)
+    session.set('last_note_id', note['id'])
+    
+    return {
+        "status": "saved",
+        "note": note,
+        "total_notes": len(session.data['notes']),
+        "session_id": session.session_id
+    }
+
+@app.session_action("get_notes", "Retrieve all notes from session")
+async def get_notes(session: Session):
+    """Get all notes from the user's session"""
+    notes = session.get('notes', [])
+    
+    return {
+        "notes": notes,
+        "count": len(notes),
+        "session_id": session.session_id,
+        "last_note_id": session.get('last_note_id')
+    }
+
+# Streaming action
+@app.stream_action("count_with_progress", "Stream counting with progress updates")
+async def count_with_progress(max_count: int = 10, delay_seconds: float = 1.0):
+    """Stream counting numbers with progress indication"""
+    
+    for i in range(max_count + 1):
+        progress_percent = (i / max_count) * 100
+        
+        yield {
+            "count": i,
+            "max_count": max_count,
+            "progress_percent": progress_percent,
+            "message": f"Counting: {i}/{max_count}",
+            "timestamp": datetime.now().isoformat(),
+            "is_complete": (i == max_count)
+        }
+        
+        if i < max_count:  # Don't delay after the last item
+            await asyncio.sleep(delay_seconds)
+
+@app.stream_action("generate_fibonacci", "Stream Fibonacci sequence")
+async def generate_fibonacci(count: int = 20, delay_seconds: float = 0.5):
+    """Generate Fibonacci sequence as a stream"""
+    
+    a, b = 0, 1
+    for i in range(count):
+        yield {
+            "position": i + 1,
+            "fibonacci_number": a,
+            "sequence_so_far": f"F({i+1}) = {a}",
+            "timestamp": datetime.now().isoformat()
+        }
+        
+        a, b = b, a + b
+        await asyncio.sleep(delay_seconds)
+
+# Complex workflow
+@app.workflow("process_text_analysis", "Complete text analysis workflow")
+async def text_analysis_workflow(text: str, workflow_state: WorkflowState):
+    """Multi-step text analysis workflow"""
+    
+    # Step 1: Validation
+    workflow_state.step = "validation"
+    workflow_state.status = "processing"
+    
+    if not text or len(text.strip()) < 10:
+        workflow_state.status = "error"
+        return {"error": "Text must be at least 10 characters long"}
+    
+    await asyncio.sleep(1)  # Simulate processing time
+    
+    # Step 2: Basic analysis
+    workflow_state.step = "basic_analysis"
+    workflow_state.data["validation_passed"] = True
+    
+    words = text.split()
+    sentences = [s.strip() for s in text.replace('!', '.').replace('?', '.').split('.') if s.strip()]
+    
+    basic_stats = {
+        "character_count": len(text),
+        "word_count": len(words),
+        "sentence_count": len(sentences),
+        "paragraph_count": len([p for p in text.split('\n\n') if p.strip()])
+    }
+    
+    workflow_state.data["basic_stats"] = basic_stats
+    await asyncio.sleep(1)
+    
+    # Step 3: Advanced analysis
+    workflow_state.step = "advanced_analysis"
+    
+    # Word frequency
+    word_freq = {}
+    for word in words:
+        clean_word = word.lower().strip('.,!?";:')
+        word_freq[clean_word] = word_freq.get(clean_word, 0) + 1
+    
+    # Top words
+    top_words = sorted(word_freq.items(), key=lambda x: x[1], reverse=True)[:5]
+    
+    advanced_stats = {
+        "unique_words": len(word_freq),
+        "average_word_length": sum(len(word) for word in words) / len(words) if words else 0,
+        "longest_word": max(words, key=len) if words else None,
+        "top_words": top_words,
+        "readability_score": min(100, max(0, 100 - (len(words) / len(sentences) if sentences else 1) * 2))
+    }
+    
+    workflow_state.data["advanced_stats"] = advanced_stats
+    await asyncio.sleep(1)
+    
+    # Step 4: Final compilation
+    workflow_state.step = "compilation"
+    
+    result = {
+        "workflow_id": workflow_state.workflow_id,
+        "analysis_type": "complete_text_analysis",
+        "input_text_preview": text[:100] + "..." if len(text) > 100 else text,
+        "basic_statistics": basic_stats,
+        "advanced_statistics": advanced_stats,
+        "processing_steps": ["validation", "basic_analysis", "advanced_analysis", "compilation"],
+        "completed_at": datetime.now().isoformat()
+    }
+    
+    workflow_state.step = "completed"
+    workflow_state.status = "success"
+    workflow_state.data["final_result"] = result
+    
+    return result
+
+# Data processing workflow
+@app.workflow("batch_text_processor", "Process multiple texts in batch")
+async def batch_text_processor(texts: List[str], workflow_state: WorkflowState):
+    """Process multiple texts as a batch workflow"""
+    
+    workflow_state.step = "initialization"
+    workflow_state.status = "processing"
+    
+    if not texts or len(texts) == 0:
+        workflow_state.status = "error"
+        return {"error": "No texts provided for processing"}
+    
+    results = []
+    workflow_state.data["total_texts"] = len(texts)
+    
+    for i, text in enumerate(texts):
+        workflow_state.step = f"processing_text_{i+1}"
+        workflow_state.data["current_text"] = i + 1
+        workflow_state.data["progress_percent"] = ((i + 1) / len(texts)) * 100
+        
+        # Process each text
+        words = text.split()
+        analysis = {
+            "text_id": i + 1,
+            "text_preview": text[:50] + "..." if len(text) > 50 else text,
+            "word_count": len(words),
+            "character_count": len(text),
+            "sentence_count": len([s for s in text.split('.') if s.strip()])
+        }
+        
+        results.append(analysis)
+        await asyncio.sleep(0.5)  # Simulate processing time
+    
+    # Final aggregation
+    workflow_state.step = "aggregation"
+    
+    total_words = sum(r["word_count"] for r in results)
+    total_chars = sum(r["character_count"] for r in results)
+    
+    final_result = {
+        "workflow_id": workflow_state.workflow_id,
+        "batch_summary": {
+            "total_texts_processed": len(results),
+            "total_words": total_words,
+            "total_characters": total_chars,
+            "average_words_per_text": total_words / len(results) if results else 0,
+            "average_chars_per_text": total_chars / len(results) if results else 0
+        },
+        "individual_results": results,
+        "completed_at": datetime.now().isoformat()
+    }
+    
+    workflow_state.step = "completed"
+    workflow_state.status = "success"
+    workflow_state.data["final_result"] = final_result
+    
+    return final_result
+
+# Advanced action with multiple parameters
+@app.action("advanced_search", "Perform advanced search with multiple filters")
+def advanced_search(
+    query: str,
+    category: str = "all",
+    min_score: float = 0.0,
+    max_results: int = 10,
+    include_metadata: bool = False,
+    sort_by: str = "relevance"
+):
+    """Advanced search function demonstrating complex parameter handling"""
+    
+    # Simulate search results
+    mock_results = [
+        {"id": 1, "title": f"Result matching '{query}'", "score": 0.95, "category": category},
+        {"id": 2, "title": f"Another match for '{query}'", "score": 0.87, "category": category},
+        {"id": 3, "title": f"Related to '{query}'", "score": 0.73, "category": category},
+    ]
+    
+    # Filter by score
+    filtered_results = [r for r in mock_results if r["score"] >= min_score]
+    
+    # Limit results
+    filtered_results = filtered_results[:max_results]
+    
+    # Sort results
+    if sort_by == "score":
+        filtered_results.sort(key=lambda x: x["score"], reverse=True)
+    
+    response = {
+        "query": query,
+        "filters": {
+            "category": category,
+            "min_score": min_score,
+            "max_results": max_results,
+            "sort_by": sort_by
+        },
+        "results": filtered_results,
+        "result_count": len(filtered_results)
+    }
+    
+    if include_metadata:
+        response["metadata"] = {
+            "search_performed_at": datetime.now().isoformat(),
+            "processing_time_ms": 45,
+            "total_available": len(mock_results)
+        }
+    
+    return response
+
+# Enable authentication (optional)
+# app.enable_auth("your-secret-jwt-key-here")
+
+# The app instance is automatically discovered by the Kalibr CLI
+# To run this: kalibr serve enhanced_kalibr_example.py --app-mode