🤖 Soni Framework

Open Source Conversational AI Framework with Prompt Optimization

Soni is a modern framework for building task-oriented dialogue systems that combines the power of DSPy for prompt optimization with LangGraph for robust dialogue management.

The Three Laws of Soni

1. Declarative First: Define behavior, not implementation
2. Optimizable: Learn from data through DSPy optimization
3. No Black Boxes: Full transparency and explainability

Inspired by Asimov's vision of intelligent, helpful AI

Features

• 🤖 Prompt Optimization - Uses DSPy's MIPROv2 to optimize NLU prompts
• 🔄 Stateful Dialogue Management - Built on LangGraph for reliable conversation flows
• 📝 YAML-Based Configuration - Declarative DSL for defining dialogue flows
• ⚡ Async-First Architecture - High-performance async/await throughout
• 🎯 Zero-Leakage Design - Technical details don't leak into configuration
• 📊 Streaming Support - Real-time token streaming with Server-Sent Events (SSE)
• 🎯 Dynamic Scoping - Context-aware action filtering reduces tokens by 39.5%
• 🔧 Slot Normalization - Automatic normalization improves validation by 11.11%
• ⚡ Performance Optimizations - Caching, connection pooling, and async checkpointing

Quick Start

Installation

# Clone the repository
git clone https://github.com/jmorenobl/soni.git
cd soni

# Install dependencies
uv sync

# Install the package
uv pip install -e .

# Set API key
export OPENAI_API_KEY="your-api-key-here"

Start the Server

# Run the example
uv run soni server --config examples/flight_booking/soni.yaml

Test the API

# Health check
curl http://localhost:8000/health

# Start a conversation
curl -X POST http://localhost:8000/chat/user-123 \
  -H "Content-Type: application/json" \
  -d '{"message": "I want to book a flight"}'

See Quickstart Guide for detailed instructions.

Example

The flight booking example demonstrates a complete dialogue system:

flows:
  book_flight:
    trigger:
      intents: [book_flight, i_want_to_book]
    steps:
      - step: collect_origin
        type: collect
        slot: origin
      - step: collect_destination
        type: collect
        slot: destination
      - step: search_flights
        type: action
        call: search_available_flights

See Flight Booking Example for a complete example.

Documentation

• Quickstart Guide - Get started in 5 minutes
• Architecture Guide - Understand how Soni works
• Migration Guide v0.3.0 - Upgrade from v0.2.x
• ADR-001: Framework Architecture - Detailed architecture decisions
• ADR-003: Architectural Refactoring - v0.3.0 improvements

Requirements

• Python 3.11+
• OpenAI API key (or other supported LLM provider)

Code Quality

v0.3.0 Quality Metrics:

• Overall Rating: 9.2/10 ⭐ (improved from 7.8/10)
• Architecture Score: 95/100 🏗️ (improved from 56/100)
• Coverage: 80%+ (exceeds 80% target) 🎯
• Linting: ✅ Ruff passes (all checks)
• Type Checking: ✅ Mypy passes (39 source files, 0 errors)
• Tests: 245 passed, 13 skipped

Architecture Improvements:

• ✅ Dependency Injection: 100% (was 0%)
• ✅ God Objects: 0 (was 2)
• ✅ RuntimeContext pattern (clean state/config separation)
• ✅ Modular design (FlowCompiler, ValidatorRegistry, ActionRegistry)

Contributing

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

License

MIT License - see LICENSE file for details.

Why "Soni"?

The name Soni is inspired by Sonny, the remarkable robot from Isaac Asimov's classic story collection "I, Robot". Like Sonny, who was special among robots—capable of learning, reasoning, and continuously optimizing his behavior—Soni represents a framework that learns and improves itself through automatic prompt optimization.

Just as Sonny questioned and refined his own programming, Soni uses DSPy to optimize conversational AI systems through manual optimization runs, making them smarter with each optimization cycle. The framework embodies Asimov's vision of intelligent, helpful AI that can be improved to better serve its purpose.

"The Three Laws of Robotics are built into the very foundation of Soni's architecture: to assist, to optimize, and to improve—all while maintaining transparency and control."

Acknowledgments

• DSPy - For prompt optimization
• LangGraph - For dialogue management
• FastAPI - For the API framework
• Typer - For the CLI interface

Built with ❤️ by the Soni Framework Contributors