orka package
OrKa: Orchestrator Kit Agents
OrKa is a comprehensive orchestration framework for AI agents that provides structured workflows, intelligent memory management, and production-ready infrastructure for building sophisticated AI applications.
Architecture Overview
OrKa features a modular architecture with specialized components designed for maintainability, testability, and extensibility while preserving complete backward compatibility.
Core Components
- Orchestrator System
Modular orchestration engine with specialized components:
OrchestratorBase
- Configuration and initializationAgentFactory
- Agent registry and instantiationExecutionEngine
- Workflow executionMetricsCollector
- Performance monitoringErrorHandler
- Error managementPromptRenderer
- Template processing
- Agent Ecosystem
Comprehensive agent implementations for various AI tasks:
LLM Agents: OpenAI integration, local model support
Decision Agents: Binary decisions, classification, routing
Memory Agents: Intelligent storage and retrieval
Search Agents: Web search and information gathering
Validation Agents: Data validation and structuring
- Node System
Specialized workflow control components:
Router Nodes: Conditional branching and decision trees
Fork/Join Nodes: Parallel execution and synchronization
Memory Nodes: Data persistence and retrieval operations
RAG Nodes: Retrieval-augmented generation workflows
- Memory System
High-performance memory backends with vector search capabilities:
RedisStackMemoryLogger
- HNSW vector indexingRedisMemoryLogger
- Redis-based storageKafkaMemoryLogger
- Event streamingModular Components: Serialization, compression, file operations
- Command Line Interface
Comprehensive CLI for development and production operations:
Workflow Execution: Run and debug AI workflows
Memory Management: Statistics, cleanup, monitoring
Configuration Validation: YAML validation and error reporting
Development Tools: Interactive testing and debugging
Key Features
Production-Ready Infrastructure - Thread-safe execution with concurrency control - Comprehensive error handling and retry logic - Performance metrics and monitoring - Graceful shutdown and resource cleanup
Intelligent Memory Management - Vector similarity search with HNSW indexing - Automatic memory decay and lifecycle management - Namespace isolation for multi-tenant scenarios - Hybrid search combining semantic and metadata filtering
Developer Experience - Declarative YAML configuration - Interactive CLI with real-time feedback - Comprehensive error reporting and debugging - Hot-reload for development workflows
Scalability and Performance - Async/await patterns for non-blocking operations - Connection pooling and resource management - Horizontal scaling with stateless architecture - Optimized data structures and algorithms
Usage Patterns
Basic Workflow Execution
from orka import Orchestrator
# Initialize with YAML configuration
orchestrator = Orchestrator("workflow.yml")
# Execute workflow
result = await orchestrator.run("input data")
Memory Backend Configuration
from orka.memory_logger import create_memory_logger
# High-performance RedisStack backend with HNSW
memory = create_memory_logger("redisstack")
# Standard Redis backend
memory = create_memory_logger("redis")
# Kafka backend for event streaming
memory = create_memory_logger("kafka")
Custom Agent Development
from orka.agents.base_agent import BaseAgent
class CustomAgent(BaseAgent):
async def _run_impl(self, ctx):
input_data = ctx.get("input")
# Process input asynchronously
return await self.process(input_data)
CLI Operations
# Execute workflow
orka run workflow.yml "input text" --verbose
# Memory management
orka memory stats
orka memory cleanup --dry-run
# Real-time monitoring
orka memory watch --live
Backward Compatibility
OrKa maintains 100% backward compatibility with existing code:
All existing imports continue to work unchanged
Legacy agent patterns are fully supported
Configuration files remain compatible
API interfaces are preserved
This ensures smooth migration paths and protects existing investments while providing access to new features and performance improvements.
For More Information
Documentation: https://github.com/marcosomma/orka-resoning
License: Apache 2.0
Author: Marco Somma (marcosomma.work@gmail.com)
Subpackages
- orka.agents package
- orka.cli package
- orka.memory package
- Memory Package
BaseMemoryLogger
BaseMemoryLogger.__init__()
BaseMemoryLogger.cleanup_expired_memories()
BaseMemoryLogger.delete()
BaseMemoryLogger.get()
BaseMemoryLogger.get_memory_stats()
BaseMemoryLogger.hdel()
BaseMemoryLogger.hget()
BaseMemoryLogger.hkeys()
BaseMemoryLogger.hset()
BaseMemoryLogger.log()
BaseMemoryLogger.sadd()
BaseMemoryLogger.set()
BaseMemoryLogger.smembers()
BaseMemoryLogger.srem()
BaseMemoryLogger.stop_decay_scheduler()
BaseMemoryLogger.tail()
FileOperationsMixin
KafkaMemoryLogger
KafkaMemoryLogger.__del__()
KafkaMemoryLogger.__init__()
KafkaMemoryLogger.cleanup_expired_memories()
KafkaMemoryLogger.close()
KafkaMemoryLogger.delete()
KafkaMemoryLogger.ensure_index()
KafkaMemoryLogger.get()
KafkaMemoryLogger.get_memory_stats()
KafkaMemoryLogger.hdel()
KafkaMemoryLogger.hget()
KafkaMemoryLogger.hkeys()
KafkaMemoryLogger.hset()
KafkaMemoryLogger.log()
KafkaMemoryLogger.log_memory()
KafkaMemoryLogger.redis
KafkaMemoryLogger.sadd()
KafkaMemoryLogger.search_memories()
KafkaMemoryLogger.set()
KafkaMemoryLogger.smembers()
KafkaMemoryLogger.srem()
KafkaMemoryLogger.tail()
RedisMemoryLogger
RedisMemoryLogger.__del__()
RedisMemoryLogger.__init__()
RedisMemoryLogger.cleanup_expired_memories()
RedisMemoryLogger.close()
RedisMemoryLogger.delete()
RedisMemoryLogger.get()
RedisMemoryLogger.get_memory_stats()
RedisMemoryLogger.hdel()
RedisMemoryLogger.hget()
RedisMemoryLogger.hkeys()
RedisMemoryLogger.hset()
RedisMemoryLogger.log()
RedisMemoryLogger.redis
RedisMemoryLogger.sadd()
RedisMemoryLogger.set()
RedisMemoryLogger.smembers()
RedisMemoryLogger.srem()
RedisMemoryLogger.tail()
RedisStackMemoryLogger
RedisStackMemoryLogger.__init__()
RedisStackMemoryLogger.cleanup_expired_memories()
RedisStackMemoryLogger.clear_all_memories()
RedisStackMemoryLogger.close()
RedisStackMemoryLogger.delete()
RedisStackMemoryLogger.delete_memory()
RedisStackMemoryLogger.ensure_index()
RedisStackMemoryLogger.get()
RedisStackMemoryLogger.get_all_memories()
RedisStackMemoryLogger.get_memory_stats()
RedisStackMemoryLogger.get_performance_metrics()
RedisStackMemoryLogger.get_recent_stored_memories()
RedisStackMemoryLogger.hdel()
RedisStackMemoryLogger.hget()
RedisStackMemoryLogger.hkeys()
RedisStackMemoryLogger.hset()
RedisStackMemoryLogger.log()
RedisStackMemoryLogger.log_memory()
RedisStackMemoryLogger.redis
RedisStackMemoryLogger.sadd()
RedisStackMemoryLogger.search_memories()
RedisStackMemoryLogger.set()
RedisStackMemoryLogger.smembers()
RedisStackMemoryLogger.srem()
RedisStackMemoryLogger.tail()
SerializationMixin
- Submodules
- orka.nodes package
- orka.orchestrator package
- Orchestrator Package
AgentFactory
ErrorHandler
ExecutionEngine
MetricsCollector
Orchestrator
OrchestratorBase
OrchestratorBase.loader
OrchestratorBase.orchestrator_cfg
OrchestratorBase.agent_cfgs
OrchestratorBase.memory
OrchestratorBase.fork_manager
OrchestratorBase.queue
OrchestratorBase.run_id
OrchestratorBase.step_index
OrchestratorBase.error_telemetry
OrchestratorBase.__init__()
OrchestratorBase.enqueue_fork()
PromptRenderer
- Submodules
- orka.startup package
- OrKa Startup Package
main()
run_startup()
start_infrastructure()
cleanup_services()
get_memory_backend()
get_docker_dir()
start_backend()
is_backend_running()
terminate_backend_process()
start_native_redis()
start_redis_docker()
wait_for_redis()
start_kafka_docker()
wait_for_kafka_services()
initialize_schema_registry()
wait_for_services()
configure_backend_environment()
get_service_endpoints()
cleanup_specific_backend()
terminate_all_processes()
force_kill_processes()
monitor_backend_process()
check_process_health()
display_service_endpoints()
display_startup_success()
display_shutdown_message()
display_shutdown_complete()
display_error()
terminate_redis_process()
cleanup_redis_docker()
cleanup_kafka_docker()
get_kafka_services()
- Subpackages
- orka.startup.infrastructure package
- Infrastructure Management Package
check_process_health()
display_error()
display_service_endpoints()
display_shutdown_complete()
display_shutdown_message()
display_startup_success()
monitor_backend_process()
wait_for_services()
cleanup_kafka_docker()
get_kafka_services()
initialize_schema_registry()
start_kafka_docker()
wait_for_kafka_services()
cleanup_redis_docker()
start_native_redis()
start_redis_docker()
terminate_redis_process()
wait_for_redis()
- Submodules
- orka.startup.infrastructure package
- Submodules
- orka.tools package
- orka.tui package
DashboardScreen
HealthScreen
HealthWidget
LogsWidget
LongMemoryScreen
MemoryLogsScreen
MemoryTableWidget
ModernTUIInterface
OrKaTextualApp
OrKaTextualApp.BINDINGS
OrKaTextualApp.CSS_PATH
OrKaTextualApp.SUB_TITLE
OrKaTextualApp.TITLE
OrKaTextualApp.action_refresh()
OrKaTextualApp.action_show_dashboard()
OrKaTextualApp.action_show_health()
OrKaTextualApp.action_show_long_memory()
OrKaTextualApp.action_show_memory_logs()
OrKaTextualApp.action_show_short_memory()
OrKaTextualApp.action_toggle_fullscreen()
OrKaTextualApp.on_mount()
OrKaTextualApp.on_screen_resume()
OrKaTextualApp.refresh_current_screen()
ShortMemoryScreen
StatsWidget
- Submodules
Submodules
- orka.contracts module
- orka.fork_group_manager module
- Fork Group Manager
ForkGroupManager
ForkGroupManager.__init__()
ForkGroupManager.create_group()
ForkGroupManager.mark_agent_done()
ForkGroupManager.is_group_done()
ForkGroupManager.list_pending_agents()
ForkGroupManager.delete_group()
ForkGroupManager.generate_group_id()
ForkGroupManager.track_branch_sequence()
ForkGroupManager.next_in_sequence()
SimpleForkGroupManager
SimpleForkGroupManager.__init__()
SimpleForkGroupManager.create_group()
SimpleForkGroupManager.mark_agent_done()
SimpleForkGroupManager.is_group_done()
SimpleForkGroupManager.list_pending_agents()
SimpleForkGroupManager.delete_group()
SimpleForkGroupManager.generate_group_id()
SimpleForkGroupManager.track_branch_sequence()
SimpleForkGroupManager.next_in_sequence()
SimpleForkGroupManager.remove_group()
- orka.loader module
- orka.memory_logger module
- orka.orchestrator package
- Orchestrator Package
AgentFactory
ErrorHandler
ExecutionEngine
MetricsCollector
Orchestrator
OrchestratorBase
OrchestratorBase.loader
OrchestratorBase.orchestrator_cfg
OrchestratorBase.agent_cfgs
OrchestratorBase.memory
OrchestratorBase.fork_manager
OrchestratorBase.queue
OrchestratorBase.run_id
OrchestratorBase.step_index
OrchestratorBase.error_telemetry
OrchestratorBase.__init__()
OrchestratorBase.enqueue_fork()
PromptRenderer
- Submodules
- orka.orchestrator_error_wrapper module
- orka.orka_cli module
- orka.orka_start module
- orka.registry module
- orka.server module
- orka.start_kafka module
- orka.start_redis_only module
- orka.tui_interface module