orcapt-sdk 1.0.5

Clean, minimal package for Orca platform integration

Orca SDK

Professional Python SDK for building real-time AI agents with streaming and production-ready deployment.

Features

• 🚀 Real-time Streaming - Stream responses to users in real-time
• 🏗️ Clean Architecture - SOLID principles, dependency injection, modular design
• ⚡ AWS Lambda Ready - Deploy to Lambda with one command
• 🎨 Design Patterns - Builder, middleware, context managers
• 📦 Storage SDK - Integrated file storage management
• 🔒 Production Ready - Error handling, logging, type safety
• ⚙️ Focused Core - Lean dependency surface for core streaming and deployment

Quick Start

Installation

pip install orcapt-sdk

Note: The package name on PyPI is orcapt-sdk, but imports still use orca:

from orca import OrcaHandler  # ✅ Correct

Basic Usage

FastAPI / Web App (Standard Factory):

from orca import create_agent_app, ChatMessage, OrcaHandler

async def process_msg(data: ChatMessage):
    handler = OrcaHandler()
    session = handler.begin(data)
    session.stream(f"Echo: {data.message}")
    session.close()

app = create_agent_app(process_message_func=process_msg)
# Run with: uvicorn main:app

SessionBuilder (Queued Operations):

from orca import OrcaHandler
from orca.patterns import SessionBuilder

handler = OrcaHandler(dev_mode=True)

# All operations are queued until execute() or complete() is called
builder = SessionBuilder(handler).start_session(data)
builder.add_stream("Hello, world!")
builder.add_image("https://example.com/image.jpg")
builder.add_button("Click", "https://example.com")
builder.execute()  # Execute all queued operations
result = builder.complete()  # Execute remaining + close session

Lambda Deployment

from orca import create_hybrid_handler, ChatMessage, OrcaHandler

async def my_agent_logic(data: ChatMessage):
    handler = OrcaHandler()
    session = handler.begin(data)
    session.stream("Response from Lambda!")
    session.close()

# Unified handler for HTTP (FastAPI), SQS, and Cron
handler = create_hybrid_handler(process_message_func=my_agent_logic)

Documentation

Document	Description
Quick Reference	API reference and quick examples
Developer Guide	Complete development guide
API Reference	Complete API documentation
Patterns Guide	Design patterns and best practices
Utilities Guide	Exceptions, decorators, and logging
Storage SDK Guide	Storage SDK and API reference
Lambda Deploy Guide	AWS Lambda deployment guide
Dev Mode Guide	Local development setup
Contributing	How to contribute
Security	Security policies
Changelog	Version history

Examples

Complete examples are available in the examples/ directory:

Quick Start

• basic_usage.py - Basic streaming and buttons
• advanced_usage.py - Advanced features
• error_handling.py - Error handling patterns

Deployment

• lambda_deployment_simple.py - Production-ready Lambda template
• lambda_usage_example.py - Advanced Lambda examples
• Dockerfile.lambda - Docker template
• requirements-lambda.txt - Lambda requirements

Features

• patterns_example.py - Design patterns
• storage_example.py - Storage SDK

Core Features

Streaming

session.loading.start("thinking")
session.stream("Processing your request...")
session.loading.end("thinking")
session.close()

Buttons

session.button.link("Visit Website", "https://example.com")
session.button.action("Regenerate", "regenerate")

Tracing

session.tracing.begin("Processing", visibility="all")
session.tracing.append("Step 1: Analyzing...")
session.tracing.append("Step 2: Generating...")
session.tracing.end("Complete!")

Usage Tracking

session.usage.track(
    tokens=1500,
    token_type="gpt4",
    cost="0.03",
    label="OpenAI GPT-4"
)

Error Handling

try:
    # Your logic
    pass
except Exception as e:
    session.error("An error occurred", exception=e)

Architecture

Orca SDK follows clean architecture principles with 14 distinct layers:

orca/
├── core/           # Core handler and session
├── domain/         # Interfaces and models
├── services/       # Business logic services
├── infrastructure/ # External clients
├── factories/      # Factory patterns
├── helpers/        # Helper utilities
├── utils/          # Utility functions
├── common/         # Cross-cutting concerns
├── patterns/       # Design patterns
├── adapters/       # Deployment adapters
└── storage/        # Storage SDK

Requirements

• Python 3.8+
• requests>=2.31.0
• pydantic>=2.0.0
• boto3>=1.34.0 (optional, for Lambda/SQS)

Development

Setup

# Clone repository
git clone https://github.com/orcapt/orca-pip
cd orca-pip

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest

# Run examples
python examples/basic_usage.py

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=orca

# Run specific test
pytest tests/test_handler.py

Deployment

AWS Lambda

1. Copy templates:

cp examples/lambda_deployment_simple.py lambda_handler.py
cp examples/Dockerfile.lambda .
cp examples/requirements-lambda.txt .

2. Build image:

docker build -f Dockerfile.lambda -t my-agent:latest .

3. Deploy:

orca ship my-agent --image my-agent:latest --env-file .env

See Lambda Deploy Guide for complete instructions.

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 📚 Docs: docs.orcaplatform.ai
• 🐛 Issues: GitHub Issues

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Acknowledgments

Built with ❤️ by the Orca team.

---

Made with 🚀 by Orca