🌊 TourFlow AI Processing Engine

"Deterministic State Machines for Non-Deterministic Models."

A production-grade, modular orchestrator for building complex, multi-modal conversation flows with LLMs. This engine treats AI interactions as a structured state machine, ensuring reliability while maintaining the flexibility of generative models.

---

🏛️ Production Case Study: "Crown Uncovered"

This engine powers the Crown Uncovered mission, a real-world multi-modal AI tour of London.

• Live Application: Production Demo Trial
• The Challenge: Creating a non-linear, voice-first guided experience that feels like a conversation with an expert, not a menu-driven bot.
• The Solution: Using the Strategy Pattern to manage state transitions and Multi-Modal Native processing to integrate high-fidelity STT/TTS.

Look at the src/tourflow/data/ folder to see the exact Production Prompts and JSON Flows used in the live mission.

---

🚀 Why this exists?

Most LLM applications rely on fragile "mega-prompts" or basic linear chains. This engine solves the Reliability Gap by:

1. Decoupling Logic from Content: The AI's personality is separate from the flow's state machine.
2. Strategy-Based Execution: Completion and routing logic are injected via a strategy pattern, making them testable and reusable.
3. Native Multi-Modal Support: Speech-to-Text and Text-to-Speech are integrated into the main orchestration loop, not added as an afterthought.

---

🧠 Core Engineering Patterns

1. The Orchestration Studio (Observability)

Includes a Gradio-based dashboard to visualize transitions in real-time. Proving that your AI isn't a "black box," but a controlled system.

2. Compositional Step Context

Every turn is governed by a StepContext assembled at runtime.

• Behavior Strategy: What the AI should achieve.
• Completion Strategy: How the engine knows to move on (LLM-verified).
• Routing Strategy: How the engine chooses the next path (Hub-and-Spoke, Linear, or Branching).

3. Stateless Engine Design

Designed to plug into any backend. Whether you use Django, FastAPI, or a CLI, the engine only requires a simple interface to process state.

---

🛠️ Quick Start

# Clone and install in editable mode
git clone https://github.com/ankbeg/tourflow
cd tourflow
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Run the Orchestration Studio (Local)
python3 examples/interactive_ui.py

Open http://localhost:7860 to see the Live State Graph and Decision Trace.

---

📂 Project Structure

• src/tourflow/core/: The logic engine (Processor, Strategies, Registry).
• src/tourflow/utils/: Helper utilities (Mermaid visualization, etc.).
• src/tourflow/data/: Real-world "Crown Uncovered" mission data.
• docs/: Technical specifications and ARCHITECTURE guides.
• examples/: Gradio UI, terminal chat, and mock implementations.
• tests/: Automated logic verification suite.

---

🧪 Testing

The engine prioritizes deterministic testing.

# Run logic tests (Mocked)
pytest tests/test_engine_logic.py

# Run integration tests (Live OpenAI)
export OPENAI_API_KEY=sk-xxxx
pytest tests/test_openai_integration.py

---

💼 Enterprise & Consulting

This engine is free for personal and commercial use under the Apache 2.0 license. However, orchestrating complex AI agents at scale requires deep architectural experience.

I am available for consulting and custom implementations, including:

• Custom Strategy development for complex business logic.
• Integration with specialized Enterprise RAG systems.
• Production-grade multi-modal scaling (STT/TTS optimization).
• Security & Guardrail architecture for LLM agents.

Interested in building something similar? Let's talk: MyLinkedIn

---

⚖️ License

Apache 2.0 - Created by Franco Begue