soplex-ai 0.1.5

Compile plain-English SOPs into executable, cost-optimized agent graphs

soplex

Compile plain-English SOPs into executable, cost-optimized agent graphs

Transform Standard Operating Procedures into hybrid agent graphs where conversation steps use LLMs, decision steps run as deterministic code, and tool/API steps execute as function calls. The result: 77% cheaper than pure-LLM agents with 99%+ accuracy on branching decisions.

🚀 Key Features

• Hybrid execution: LLM for conversation, code for logic, APIs for actions
• Multi-provider support: OpenAI, Anthropic, Google Gemini, Ollama, LiteLLM, or any OpenAI-compatible endpoint
• Cost optimization: Dramatically reduce LLM costs by running decisions as code
• High accuracy: Deterministic branching logic eliminates LLM reasoning errors
• Production ready: Comprehensive testing, type safety, and security best practices

📦 Installation

pip install soplex-ai

# Optional providers
pip install soplex-ai[anthropic]    # Anthropic Claude
pip install soplex-ai[litellm]      # LiteLLM
pip install soplex-ai[all]          # All providers

🔧 Quick Start

1. Create a SOP file

PROCEDURE: Customer Refund Request
TRIGGER: Customer requests refund for order
TOOLS: order_db, payments_api, identity_check

1. Greet the customer and ask for their order number
2. Lookup the order details in order_db using the provided order number
3. Check if the order was placed within the last 30 days
   - YES: Proceed to step 4
   - NO: Inform customer that refunds are only available for orders within 30 days and end
4. Verify customer identity using identity_check with order email
5. Ask customer for the reason for the refund
6. Process the refund using payments_api
7. Confirm with customer that refund has been processed

2. Analyze the SOP

soplex analyze refund.sop

Output shows step classification and cost estimates:

📊 SOP Analysis: Customer Refund Request

Step Classification:
🧠 LLM Steps:    4 (conversation)
⚡ CODE Steps:   2 (deterministic logic)
🔀 BRANCH Steps: 1 (conditional)

💰 Cost Estimate:
Pure LLM:    $0.0084
Hybrid:      $0.0019  (77% savings)

3. Compile and run

# Compile SOP to executable graph
soplex compile refund.sop --output ./compiled/

# Interactive chat with the agent
soplex chat ./compiled/refund.json

🚀 Programmatic Python API

For engineers who prefer native Python code over parsing text files, Soplex provides a PythonGraphBuilder. This bypasses LLM code synthesis entirely, allowing robust deterministic routing logic.

from soplex import PythonGraphBuilder

builder = PythonGraphBuilder(name="Native Support Flow")

# 1. Add LLM interaction
builder.add_llm_step(id="start", action="Greet customer")

# 2. Add specific explicit Python logic
def process_data(state):
    state["verified"] = True
    return state
    
builder.add_code_step(
    id="verify", 
    action="Verify data", 
    handler_func=process_data
)

# 3. Add a branch decision point
builder.add_branch_step(id="check", action="Check verified")
builder.add_end_step(id="success", action="Finish")
builder.add_end_step(id="fail", action="Fail")

# 4. Wire edges with strict Python conditions
builder.add_edge("start", "verify")
builder.add_edge("verify", "check")
builder.add_edge("check", "success", condition_func=lambda s: s.get("verified"))
builder.add_edge("check", "fail", condition_func=lambda s: not s.get("verified"))

graph = builder.build()

🎯 Step Types

soplex automatically classifies each step based on keywords:

Type	Keywords	Execution	Example
LLM	ask, greet, inform, confirm, explain	Conversational AI	"Greet the customer warmly"
CODE	check, lookup, calculate, verify, process	Deterministic logic	"Check if order was placed within 30 days"
HYBRID	Mixed LLM + CODE keywords	LLM + validation	"Ask customer for order number and verify it"
BRANCH	if, when, check:, conditional patterns	Conditional logic	"Check: Is the payment successful?"
END	end, complete, done, finish	Terminal	"End the process successfully"
ESCALATE	escalate, hand off, transfer	Human handoff	"Escalate to supervisor"

⚙️ Configuration

Configure via environment variables (.env) or CLI flags:

# .env file
OPENAI_API_KEY=sk-...
SOPLEX_PROVIDER=openai
SOPLEX_MODEL=gpt-4o-mini
SOPLEX_TEMPERATURE=0.3

Supported providers:

• openai - OpenAI GPT models
• anthropic - Anthropic Claude models
• gemini - Google Gemini models
• ollama - Local Ollama models
• litellm - Any LiteLLM-supported provider
• custom - Custom OpenAI-compatible endpoint

📊 CLI Commands

# Analyze SOP structure and costs
soplex analyze refund.sop --provider anthropic --model claude-sonnet-4-20250514

# Compile SOP to executable graph
soplex compile refund.sop --output ./compiled/

# Interactive agent chat
soplex chat ./compiled/refund.json

# Generate flowchart visualization
soplex visualize ./compiled/refund.json --output refund.svg

# Run test scenarios
soplex test ./compiled/refund.json --scenarios test_cases.yaml

# View execution statistics
soplex stats

🏗️ Architecture

Plain Text SOP → Parser → Classifier → Graph Builder → Executor
                    ↓         ↓            ↓           ↓
                 Structure  LLM/CODE    Execution    Runtime
                            Types       Graph

• Parser: Converts plain text to structured data
• Classifier: Determines execution type (LLM/CODE/HYBRID) via keywords
• Graph Builder: Creates executable node graph with conditional edges
• Executor: Runs graph step-by-step, calling LLM only when needed

🧪 Testing

# Run all tests (without API calls)
pytest tests/ -v

# Run with real API integration tests
pytest tests/test_e2e.py -v -m e2e

# Run specific test categories
pytest tests/test_parser.py -v
pytest tests/test_classifier.py -v

🔐 Security

• Environment variables loaded securely via python-dotenv
• API keys never logged or exposed in output
• Production-grade error handling and validation
• Comprehensive input sanitization

📈 Cost Savings

Traditional pure-LLM agents call the LLM for every step. soplex only calls LLMs for conversation, running logic and decisions as code:

Traditional:  🧠🧠🧠🧠🧠🧠🧠  (7 LLM calls)
soplex:       🧠⚡🧠⚡⚡🧠⚡  (3 LLM calls, 4 code calls)
Savings:      ~57-77% cost reduction

🤝 Contributing

git clone https://github.com/pratikbhande/soplex
cd soplex
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -e ".[dev]"
pytest

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Documentation
• Examples
• PyPI Package
• Issues