Core (Advanced)

The caesura-io-core package is the framework-agnostic shared engine that powers all Caesura 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:

from caesura_core import create_caesura_engine, select_active, render_block

engine = create_caesura_engine({
    "base_url": "https://dev.caesura.io",
    # api_key auto-read from CAESURA_API_KEY if omitted
})

# 1. Observe a conversation turn
engine.observe("conversation-id", [
    {
        "speaker_role": "user",
        "speaker_name": "Customer",
        "text": "I need help preparing for the next meeting"
    }
])

# 2. Retrieve buffered recommendations
state = engine.store.get("conversation-id")
active = select_active(state, engine.config.inject, time.time() * 1000)

# 3. Render the insights for injection into your specific LLM prompt
blocks = render_block(active, engine.config.inject)
# -> `blocks` contains rendered recommendation text ready for injection