Hypocaust: Core Overview

Hypocaust is an open-source backend system developed by lukeashford, built with Java 21 and Spring Boot. It orchestrates long-running AI agent workflows, addressing key challenges like reliability, real-time feedback, and efficient iteration. Key features include:

• Event sourcing for state consistency
• Transactional outbox for distributed system reliability
• Semantic tool discovery
• Real-time SSE updates
• Versioned artifact management and selective partial re-run

Its goal is to provide a robust infrastructure for production-grade AI agent applications.

Background & Problem Statement

As AI agent applications grow, orchestrating long-running workflows (minutes or longer) presents critical challenges:

• Ensuring asynchronous execution and state consistency after crashes
• Providing real-time progress feedback to users
• Integrating diverse AI/deterministic tools flexibly
• Managing versioned artifacts (images, audio, videos) and efficient iterations

Hypocaust is tailored to tackle these issues.

Core Architecture & Design

Event Sourcing

• Append-only event storage for all state changes
• Enables audit trails, time travel, and fault recovery

Transactional Outbox

• Solves double-write problem (atomic DB updates + message publishing)
• Uses bigserial for event order

SSE Real-Time Updates

• Pushes progress via Server-Sent Events
• Supports gapless reconnection with Last-Event-ID

Artifact Lifecycle

• State machine: GESTATING → MANIFESTED (or FAILED/CANCELLED)
• Version chain via supersedes_id

Bounded Executor

• Prevents web thread blocking, handles concurrent long tasks

Technology Stack

• Backend: Java21 + Spring Boot
• DB: PostgreSQL
• Containerization: Podman (Postgres, pgAdmin, FFmpeg sidecar)
• Media: FFmpeg sidecar

API Design

• REST endpoints: POST /tasks (submit), GET /task-executions/{id}/events (SSE)
• OpenAPI docs (/v3/api-docs) and Swagger UI

Quick Start

• Requirements: Java21, Podman, OpenAI/Anthropic keys
• Commands: ./gradlew pods-create (start dependencies), ./gradlew bootRun (run app)

Project Status

• Active development, FFmpeg decomposer integration in progress

Workflow Execution

Plan-Clarify-Execute

1. Plan: Analyze task, split into sub-tasks
2. Clarify: Ask user for missing info
3. Execute: Generate artifacts

Decomposer Pattern

• Split complex tasks into independent sub-tasks
• Each sub-task can retry/recover separately

Selective Partial Re-run

• Only re-run affected sub-tasks when requirements change
• Improves iteration efficiency for creative workflows

Tool System

SemanticSearchToolRegistry

• Embeds tool descriptions, uses vector similarity to find best tools

Core Tools

1. generate_creative: AI-based, uses RAG for model selection, fallback on failure
2. ffmpeg_process: Deterministic media tool, LLM constructs API requests from OpenAPI schema

Tool Lifecycle

• Follows AbstractArtifactTool for consistent, observable calls

Application Scenarios

Creative Content Generation

• Multimedia stories, marketing materials, personalized content

Intelligent Workflow Automation

• Data pipelines, document generation, media processing chains

Research & Experiment Platforms

• AI experiment management, A/B testing, collaborative creation

Comparison with Others

Feature	Hypocaust	LangChain	Temporal
Event Sourcing	✅	❌ (custom)	✅
Artifact Management	✅	❌ (custom)	❌ (custom)
Semantic Tool Discovery	✅	❌	❌
SSE Real-Time	✅	❌ (custom)	❌ (custom)
AI Native	✅	✅	❌

Conclusion & Future

Hypocaust is a specialized infrastructure for long-running AI workflows, focusing on reliability, real-time feedback, and efficiency. It solves critical production pain points, letting developers focus on business logic.

As AI agents move to production, systems like Hypocaust will be essential for ensuring scalability and reliability. The project is actively developing, with FFmpeg decomposer integration ongoing.