Lumina: The Deterministic Future of AI Agents Framework

Lumina isn't just a framework, it is a fundamental re-engineering of AI agent systems. Built on a Rust core for uncompromised speed and an event-driven architecture that crushes Python-based concurrency limits, Lumina mandates determinism. We deliver the only auditable, reproducible, and truly scalable runtime designed to replace legacy frameworks and power mission-critical enterprise AI.

Why Lumina? See Lumina vs LangChain for a detailed comparison of competitive advantages.

🚀 Quick Start

Installation

Option 1: Install from Source (Recommended)

# Clone the repository
git clone https://github.com/sefineh-ai/Lumina.git
cd Lumina

# Build Rust core
cd core
cargo build --release

# Install Python SDK with pip
cd ../sdk/python
pip install -e .

Option 2: Install from PyPI (Recommended)

pip install lumina

Note: The Rust core is automatically built and included in the PyPI package. See INSTALLATION.md for complete instructions.

Prerequisites

• Rust (latest stable): Install Rust
• Python 3.8+ (for Python SDK)
• Cargo (comes with Rust)

Python SDK Usage

from lumina import Agent, Runtime
import json
import os

# Initialize runtime
runtime = Runtime()
runtime.start()

# Create agent with Gemini API key
agent = Agent(
    name="MyAgent",
    seed=42,  # For deterministic execution
    runtime=runtime,
    gemini_api_key=os.getenv("GEMINI_API_KEY")
)

# Create workflow with LLM step
workflow = json.dumps([{
    "step_id": "llm_step",
    "step_type": "LLMCall",
    "prompt": "Answer: {input}",
    "tool_calls": [],
    "condition": None
}])

agent.set_workflow(workflow)

# Set up event handlers (optional)
@agent.on("LLMCallCompleted")
def on_complete(event):
    payload = event.get('payload', {})
    print(f"Response: {payload.get('response')}")

# Run agent
result = agent.run("What is artificial intelligence?")
print(result)

# Clean up
runtime.stop()

JavaScript/TypeScript SDK Usage

import { Agent, Runtime } from 'lumina-sdk';

const runtime = new Runtime();
runtime.start();

const agent = new Agent({
  name: 'MyAgent',
  seed: 42,
  runtime: runtime
});

const result = await agent.run('Summarize recent AI research');
console.log(result);

🏗️ Architecture

Core Components

• core/engine/ - Tokio-based event loop, scheduler, and event bus
• core/tools/ - Deterministic tool orchestration with caching and retries
• core/adapters/ - LLM adapters (Gemini) and vector DB integrations
• core/lumina-core/ - Public API and FFI bindings for SDKs
• sdk/python/ - Python SDK with PyO3 bindings
• sdk/js/ - JavaScript/TypeScript SDK
• playground/ - Visual debugger and trace viewer

Core Principles

🎯 Event-Driven - Every LLM call, agent step, and workflow action emits events. Agents react to events instead of blocking.
⚡ Rust Concurrency - All CPU- or I/O-heavy operations run in Rust-native concurrency. Python is optional and sequential if needed.
🎲 Determinism - Seeded RNG and deterministic scheduling for reproducibility.
⭐ Premium Features - Parallel execution, worker pools, channel-based event bus, task throttling, and priority queues.

Key Features

✅ Event-Driven Architecture - Pure pub/sub system, all operations emit events
✅ Deterministic Execution - Seeded RNG for reproducible workflows
✅ LLM Integration - Built-in Gemini adapter with event-driven calls
✅ Error Handling - Automatic termination on errors, no hanging
✅ True Concurrency - Rust async runtime, no Python GIL limits
✅ Native Tool System - Built-in tool orchestration with caching
✅ Hierarchical Memory - Global → Agent → Step → Tool layers
✅ Production Ready - Timeout protection, proper error propagation
⭐ Premium Concurrency - Parallel event handling, concurrent tools, task scheduling

📚 Documentation

• Core Principles - Fundamental design principles
• Lumina vs LangChain - Competitive advantages
• Deployment Guide - Docker and containerization
• Usage Guide - Complete usage guide with examples
• Concurrency Guide - Premium concurrency features
• Installation Guide - Setup instructions
• Architecture Overview - Technical architecture
• Python SDK Guide - Python API reference
• Examples - Code examples
• Changelog - Version history

🧪 Examples

See the examples/ directory for:

• Simple agent creation
• Deterministic workflows
• Tool integration
• Multi-step agents

🛠️ Development

Building the Rust Core

cd core
cargo build --release

Running Tests

# Rust tests
cd core
cargo test

# Python tests
cd sdk/python
pytest

# JS tests
cd sdk/js
npm test

Development Mode

# Watch mode for Rust
cd core
cargo watch -x "test"

# Python SDK in editable mode
cd sdk/python
pip install -e .

📊 Performance Goals

Metric	Target
Step latency	< 20ms
Concurrent agents/node	> 1000
Memory per agent	< 5MB
Cold start	< 200ms
Trace replay	< 10ms

🤝 Contributing

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License

Lumina © 2025 — MIT License. See LICENSE for details.

👤 Author

Sefineh — AI Engineer & LLM Framework Builder

Building Lumina to redefine how agentic systems think, act, and scale.

---

Status: 🚧 In Active Development