Core (Advanced)

The caesura-io-core package is the framework-agnostic shared engine that powers all CaesuraO Python SDK integrations. It contains the shared analysis, injection, and credit-metering logic.

warning

This package is not meant to be used directly by most developers.

You should use the framework-specific adapters instead:

• caesura-io-openai

What's Inside

If you are building a custom integration for a framework we don't currently support, the core package provides the following building blocks:

Module	Purpose
CaesuraClient / AsyncCaesuraClient	HTTP client that calls the backend analysis endpoints.
MemoryCaesuraStore	In-memory conversation state with LRU + idle-time eviction.
CaesuraEngine / AsyncCaesuraEngine	Orchestrator: cadence checks, observe/analyze cycle, buffering, event emission.
create_credit_meter	Accumulates and queries credit-usage metrics.
create_debug_logger	Structured on_event logger for debugging.
Helpers	hash_message, select_active, render_analysis, render_block, build_analyze_messages.
Types	CaesuraConfig, CaesuraEvent, InjectConfig, SendConfig, etc.

Usage for Custom Integrations

To build your own integration, you instantiate the engine and manually orchestrate the observation and injection cycles:

import time
from caesura_core import (
    AnalyzeMessage,
    CaesuraConfig,
    create_caesura_engine,
    select_active,
    render_block,
)

engine = create_caesura_engine(CaesuraConfig(mode="sync"))
conversation_id = engine.create_conversation(name="Support session")

# Reuse this backend ID for subsequent turns.
engine.observe(conversation_id, [
    AnalyzeMessage(
        speaker_role="user",
        speaker_name="Customer",
        text="I need help preparing for the next meeting",
    ),
])

state = engine.store.get(conversation_id)
active = select_active(state, engine.config.inject, time.time() * 1000)
blocks = render_block(active, engine.config.inject)

mode="sync" finishes analysis before the snippet reads guidance. Configuration and collected messages use CaesuraConfig and AnalyzeMessage dataclasses. For an async integration, use create_async_caesura_engine and await create_conversation() and observe().

observe() advances the turn counter itself. Keep the engine or store across calls and preserve in-flight states in custom stores. See Conversations & Persistence and Configuration for session IDs, budgets, and analysis values.