contd 0.1.5

Durable workflow execution engine with time-travel debugging

Contd.ai

The Durable Execution Engine for Agentic Workflows.

Contd.ai is a lightweight, multi-tenant framework designed to build, run, and recover long-running AI agent workflows. It provides durable execution guarantees, meaning your agents can pause, resume, crash, and recover exactly where they left off—without losing state or context.

Key Features

• Durable Execution: Workflows are resumable by default. State is persisted after every step.
• Multi-Tenancy: Built-in organization isolation. Data and execution contexts are strictly scoped to organizations.
• Epistemic Savepoints: Specialized markers for AI agents to save their logic state (hypotheses, goals, decisions) alongside execution state.
• Hybrid Recovery: Fast restoration using snapshots + event replay.
• Idempotency: Automatic retries and de-duplication of steps.
• Context Preservation: Prevents "context rot" in long-running agents with reasoning ledgers and distillation.
• LLM Cost Tracking: Built-in token counting and cost management for LLM-powered workflows.

Architecture

Contd.ai follows a layered architecture:

• SDK (contd.sdk): Python decorators (@workflow, @step) to define workflows. Handles context propagation and serialization.
• Engine (contd.core): The brain. Manages the event loop, recovery logic, and lease management.
• API (contd.api): FastAPI interactions for submitting workflows, querying status, and time-travel.
• Persistence (contd.persistence): Pluggable storage adapters. Currently supports Postgres (Journal/Leases) and S3 (Snapshots).

Client Libraries

Contd provides SDKs for multiple languages:

Language	Package	Install
Python	contd	pip install contd
TypeScript/Node.js	@contd.ai/sdk	npm install @contd.ai/sdk
Go	github.com/bhavdeep98/contd.ai/sdks/go	go get github.com/bhavdeep98/contd.ai/sdks/go
Java	ai.contd:contd-sdk	Coming soon

See the sdks/ directory for full documentation on each SDK.

Getting Started

Prerequisites

• Python 3.10+
• PostgreSQL (Local or Remote)

Installation

From PyPI (Recommended):

pip install contd

View on PyPI

With optional dependencies:

pip install contd[postgres]      # PostgreSQL support
pip install contd[redis]         # Redis support
pip install contd[s3]            # S3 storage support
pip install contd[observability] # Metrics & tracing
pip install contd[all]           # Everything

From Source:

git clone https://github.com/bhavdeep98/contd.ai.git
cd contd.ai
pip install -e .

Database Setup

1. Create a PostgreSQL database.
2. Run the schema script to initialize tables:

psql -d contd_db -f contd/persistence/schema.sql

Running the Server

Start the API and gRPC server:

python -m contd.api.server

The server listens on:

• HTTP API: http://localhost:8000
• gRPC: localhost:50051

Usage Example

Defining a Workflow

from contd.sdk.decorators import workflow, step
from contd.sdk.llm import llm_step, LLMStepConfig
from contd.sdk.context import ExecutionContext

@step
def research_topic(topic: str):
    # Simulate work
    return {"summary": f"Research on {topic} complete."}

@llm_step(LLMStepConfig(model="gpt-4o", cost_budget=0.50))
def generate_content(context: dict):
    # LLM call with automatic token tracking
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": f"Write about: {context['summary']}"}]
    )
    return {"response": response, "content": response.choices[0].message.content}

@workflow
def blog_agent(topic: str):
    # Add reasoning breadcrumb
    ctx = ExecutionContext.current()
    ctx.annotate(f"Starting research on topic: {topic}")
    
    data = research_topic(topic)
    final = generate_content(data)
    return final

Triggering a Workflow

Use your API Key to trigger the workflow via HTTP:

POST /v1/workflows
X-API-Key: sk_live_...

{
  "workflow_name": "blog_agent",
  "input": { "topic": "AI Agents" }
}

CLI Usage

Contd includes a powerful CLI for local development and workflow management.

Installation

pip install -e .

Initialize a Project

contd init                    # Initialize with SQLite (default)
contd init --backend postgres # Initialize with Postgres

Run a Workflow

contd run my_workflow --input '{"key": "value"}'
contd run my_workflow -f input.json

Check Workflow Status

contd status <workflow_id>

Resume a Suspended Workflow

contd resume <workflow_id>

Inspect Workflow State

contd inspect <workflow_id>           # Basic info
contd inspect <workflow_id> --verbose # Full state and events

Time-Travel Debugging

contd time-travel <workflow_id> <savepoint_id>      # Create new workflow from savepoint
contd time-travel <workflow_id> <savepoint_id> --dry-run # Preview without creating

View Execution Logs

contd logs <workflow_id>
contd logs <workflow_id> -n 100 -l DEBUG # More lines, debug level

List Workflows

contd list                    # All workflows
contd list --status running   # Filter by status

Testing

Run the test suite:

pytest tests/

Documentation

Document	Description
Quickstart Guide	Get started in 5 minutes
Architecture	System design and components
API Reference	Complete REST/gRPC/SDK reference
Metrics Setup	Observability configuration
Troubleshooting	Common issues and solutions
Contributing	How to contribute

Examples

See the examples/ directory for 12+ real-world workflow examples:

• Basic pipelines and error handling
• AI agents with tools
• RAG pipelines
• E-commerce order processing (saga pattern)
• ETL workflows
• Human-in-the-loop approvals
• Batch processing
• Webhook integrations
• Research and code review agents
• Customer support automation

License

Business Source License 1.1 - see LICENSE for details.

Free for non-commercial use. Converts to Apache 2.0 on January 27, 2030. Contact [e-mail] for commercial licensing.