orka-reasoning 0.9.13

Modular agent orchestrator for reasoning pipelines

What OrKa Does

OrKa is a local first solution that lets you define AI workflows in YAML files instead of writing complex Python code. You describe what you want - like "search memory, then ask an AI, then save the result" - and OrKa handles the execution.

Think of it as a streamlined, open-source alternative to CrewAI or LangChain, but with a focus on:

• Local LLM Vendor agnostic
• YAML configuration instead of code
• Built-in memory that remembers and forgets intelligently
• Local LLM support for privacy
• Simple setup with Docker

Basic Example

Instead of writing Python code like this:

# Complex Python orchestration code
memory_results = search_memory(query)
if not memory_results:
    web_results = search_web(query)
    answer = llm.generate(web_results + query)
else:
    answer = llm.generate(memory_results + query)
save_to_memory(query, answer)

You write a YAML file like this:

orchestrator:
  id: simple-qa
  agents: [memory_search, web_search, answer, memory_store]

agents:
  - id: memory_search
    type: memory
    operation: read
    prompt: "Find: {{ input }}"
    
  - id: web_search  
    type: search
    prompt: "Search: {{ input }}"
    
  - id: answer
    type: local_llm
    model: llama3.2:3b
    prompt: "Answer based on: {{ previous_outputs }}"
    
  - id: memory_store
    type: memory
    operation: write
    prompt: "Store: {{ input }} -> {{ previous_outputs.answer }}"

Installation

# Install OrKa
pip install orka-reasoning

# Start RedisStack + Backend + UI
# Automatically tries native RedisStack first, then Docker
# UI available at http://localhost:8080
orka-start

# Memory TUI
orka memory watch

# Run a workflow
orka run my-workflow.yml "What is machine learning?"

Visual Workflow Builder (OrKa UI)

Don't want to write YAML by hand? Use OrKa UI - a drag-and-drop visual editor:

Automatic Start (Recommended)

# UI automatically starts with orka-start
orka-start

# Access at http://localhost:8080

Manual Start (Alternative)

# Pull and run the UI manually
docker pull marcosomma/orka-ui:latest
docker run -d -p 8080:80 --name orka-ui \
  -e VITE_API_URL_LOCAL=http://localhost:8000/api/run@dist \
  marcosomma/orka-ui:latest

# Access at http://localhost:8080

Configuration

# Skip UI (Redis + Backend only)
export ORKA_DISABLE_UI=true
orka-start

# Use cached Docker image (faster startup)
export ORKA_UI_SKIP_PULL=true
orka-start

🆕 JSON Input Support

OrKa now supports JSON input for advanced workflows and structured use cases!

Why use JSON input?

• Pass complex data (objects, arrays, clinical records, etc.) as input to your workflow.
• Enable dynamic prompts and agents that access specific input fields via {{ input.field }}.
• Perfect for use cases like: medical assistants, document automation, multi-step workflows with structured data.

How to use

1. Prepare a JSON file, e.g. input.json:

   {
     "patient": {
       "name": "Fido",
       "species": "dog",
       "symptoms": ["vomiting", "lethargy"],
       "age": 7
     },
     "history": "No previous major illnesses."
   }
   

2. Pass the file as input to the workflow using the --json-input flag before the run command:

   orka --json-input run my-workflow.yml input.json
   

   Or pass inline JSON:

   orka --json-input run my-workflow.yml '{"foo": 123, "bar": "baz"}' 
   

3. In your YAML, access fields using Jinja2 syntax:

   prompt: "Patient: {{ input.patient.name }}, Symptoms: {{ input.patient.symptoms }}"
   

Note: If you use the --json-input flag, the plain text input is ignored and only the JSON is used.

For real-world examples, see the examples/ folder and the documentation.

---

Features:

• 🎨 Drag-and-drop workflow builder
• 🔧 Visual node configuration
• 📤 One-click YAML export
• 🚀 Built-in workflow execution
• 📚 Example workflow library

📖 Read the full OrKa UI documentation →

What orka-start Provides

When you run orka-start, it automatically sets up:

1. RedisStack (memory backend) - tries native first, then Docker
2. OrKa Backend API (port 8000) - workflow execution engine
3. OrKa UI (port 8080) - visual workflow builder (if Docker available)

RedisStack Setup:

• Tries native RedisStack (if installed on your system)
• Falls back to Docker (if Docker is running)
• Shows install instructions (if neither is available)

Choose your preferred method:

• Docker (easiest): Just have Docker running, orka-start handles everything
• Native (no Docker needed):
  • macOS: brew install redis-stack
  • Ubuntu: sudo apt install redis-stack-server
  • Windows: Download from redis.io

How It Works

1. Agent Types

OrKa provides several agent types you can use in your workflows:

• memory - Read from or write to persistent memory
• local_llm - Use local models (Ollama, LM Studio)
• openai-* - Use OpenAI models
• search - Web search
• router - Conditional branching
• fork/join - Parallel processing
• loop - Iterative workflows
• plan_validator - Validate and critique proposed execution paths
• graph_scout - [BETA] Find best path for workflow execution

2. Memory System

OrKa includes a memory system that:

• Stores conversations and facts
• Searches semantically (finds related content, not just exact matches)
• Automatically forgets old, unimportant information
• Uses Redis for fast retrieval

3. Workflow Execution

When you run orka run workflow.yml "input", OrKa:

1. Reads your YAML configuration
2. Creates the agents you defined
3. Runs them in the order you specified
4. Passes outputs between agents
5. Returns the final result

4. Local LLM Support

OrKa works with local models through:

• Ollama - ollama pull llama3.2 then use provider: lm_studio
• LM Studio - Point to your local API endpoint
• Any LLM-compatible API

---

📚 Complete Agent & Node Reference

🎯 NEW: Comprehensive Documentation for Every Agent, Node & Tool →

Detailed documentation for all agent types, control flow nodes, and tools:

• 🤖 7 LLM Agents - OpenAI, Local LLM, Binary, Classification, Validation, PlanValidator
• 💾 2 Memory Agents - Reader & Writer with 100x faster HNSW indexing
• 🔀 6 Control Flow Nodes - Router, Fork/Join, Loop, Failover, GraphScout
• 🔧 2 Search Tools - DuckDuckGo, RAG

Each with working examples, parameters, best practices, and troubleshooting!

---

Common Patterns

Memory-First Q&A

# Check memory first, search web if nothing found
agents:
  - id: check_memory
    type: memory
    operation: read

  - id: binary_agent
    type: local_llm
    prompt: |
      Given those memory {{get_agent_response('check_memory')}} and this input {{ input }}
      Is an search on internet required?
      Only answer with 'true' or 'false' 
    
  - id: route_decision
    type: router
    decision_key: 'binary_agent'
    routing_map:
      "true": [answer_from_memory]
      "false": [web_search, answer_from_web]

Parallel Processing

# Analyze sentiment and toxicity simultaneously
agents:
  - id: parallel_analysis
    type: fork
    targets:
      - [sentiment_analyzer]
      - [toxicity_checker]
      
  - id: combine_results
    group: parallel_analysis
    type: join

Iterative Improvement

# Keep improving until quality threshold met
agents:
  - id: improvement_loop
    type: loop
    max_loops: 5
    score_threshold: 0.85
    internal_workflow:
      agents: [analyzer, scorer]

Comparison to Alternatives

Feature	OrKa	LangChain	CrewAI
Configuration	YAML files	Python code	Python code
Memory	Built-in with decay	External/manual	External/manual
Local LLMs	First-class support	Via adapters	Limited
Parallel execution	Native fork/join	Manual threading	Agent-based
Learning	Automatic memory management	Manual	Manual

Quick Start Examples

1. Simple Q&A with Memory

# Copy example
cp examples/simple_memory_preset_demo.yml my-qa.yml

# Run it
orka run my-qa.yml "What is artificial intelligence?"

2. Web Search + Memory

# Copy example  
cp examples/person_routing_with_search.yml web-qa.yml

# Run it
orka run web-qa.yml "Latest news about quantum computing"

3. Local LLM Chat

# Start Ollama
ollama pull llama3.2

# Copy example
cp examples/multi_model_local_llm_evaluation.yml local-chat.yml

# Run it
orka run local-chat.yml "Explain machine learning simply"

Documentation

📚 Documentation Index → - Start Here!

Complete documentation hub with organized guides, tutorials, and references for all OrKa features.

Quick links:

• 📘 Quickstart - Get running in 5 minutes
• 🎯 Agent & Node Reference - Every agent, node & tool documented
• 🧠 Memory System - Intelligent memory configuration
• ⚙️ YAML Configuration - Complete workflow reference
• 🧭 GraphScout Agent - Dynamic routing system
• 📋 Examples - 50+ ready-to-use workflow templates

Getting Help

• GitHub Issues - Bug reports and feature requests
• Documentation - Full documentation
• Examples - Working examples you can copy and modify

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

Apache 2.0 License - see LICENSE for details.