# 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](docs/LUMINA_VS_LANGCHAIN.md) for a detailed comparison of competitive advantages.

## 🚀 Quick Start

### Installation

#### Option 1: Install from Source (Recommended)

```bash
# 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)

```bash
pip install lumina
```

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

### Prerequisites

- **Rust** (latest stable): [Install Rust](https://www.rust-lang.org/tools/install)
- **Python** 3.8+ (for Python SDK)
- **Cargo** (comes with Rust)

### Python SDK Usage

```python
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

```typescript
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](docs/CORE_PRINCIPLES.md)** - Fundamental design principles
- **[Lumina vs LangChain](docs/LUMINA_VS_LANGCHAIN.md)** - Competitive advantages
- **[Deployment Guide](docs/DEPLOYMENT.md)** - Docker and containerization
- **[Usage Guide](USAGE.md)** - Complete usage guide with examples
- **[Concurrency Guide](docs/CONCURRENCY.md)** - Premium concurrency features
- [Installation Guide](INSTALLATION.md) - Setup instructions
- [Architecture Overview](ARCHITECTURE.md) - Technical architecture
- [Python SDK Guide](sdk/python/README.md) - Python API reference
- [Examples](examples/) - Code examples
- [Changelog](CHANGELOG.md) - Version history

## 🧪 Examples

See the `examples/` directory for:
- Simple agent creation
- Deterministic workflows
- Tool integration
- Multi-step agents

## 🛠️ Development

### Building the Rust Core

```bash
cd core
cargo build --release
```

### Running Tests

```bash
# Rust tests
cd core
cargo test

# Python tests
cd sdk/python
pytest

# JS tests
cd sdk/js
npm test
```

### Development Mode

```bash
# 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](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](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

