orka.contracts module

Type Contracts

This module defines the core data structures and type contracts used throughout the OrKa framework. These TypedDict classes establish a consistent interface for data exchange between components, ensuring type safety and providing documentation on the expected structure of data objects.

The contracts defined here serve several purposes: 1. Type checking and validation at development time 2. Documentation of data structure requirements 3. Standardization of interfaces between components 4. Support for IDE autocompletion and code navigation

These contracts are essential for maintaining a clean architecture and ensuring that components can be composed reliably with predictable data formats.

class orka.contracts.Context

Bases: TypedDict

Core context passed to all nodes during execution.

This is the primary data structure that flows through the OrKa pipeline, containing input data, accumulated outputs from previous nodes, and execution metadata.

input

The original query or input text to process

Type:

str

previous_outputs

Results from previously executed nodes in the pipeline

Type:

Dict[str, Any]

metadata

Additional information about the execution context

Type:

Dict[str, Any]

trace_id

Unique identifier for tracing the execution path

Type:

str | None

timestamp

When this context was created or last updated

Type:

datetime.datetime

input: str

previous_outputs: Dict[str, Any]

metadata: Dict[str, Any]

trace_id: str | None

timestamp: datetime

class orka.contracts.Output

Bases: TypedDict

Standard output format for all nodes.

Defines a consistent structure for node execution results, including success/failure status and relevant metadata.

result

The primary output data from the node execution

Type:

Any

status

Execution status - “success” or “error”

Type:

str

error

Error message if status is “error”, otherwise None

Type:

str | None

metadata

Additional information about the execution result

Type:

Dict[str, Any]

result: Any

status: str

error: str | None

metadata: Dict[str, Any]

class orka.contracts.ResourceConfig

Bases: TypedDict

Configuration for a resource in the registry.

Defines how external resources like LLMs, embedders, and databases should be initialized and configured.

type

The resource type identifier (e.g., “openai”, “sentence-transformer”)

Type:

str

config

Configuration parameters specific to the resource type

Type:

Dict[str, Any]

type: str

config: Dict[str, Any]

class orka.contracts.Registry

Bases: TypedDict

Resource registry containing all available resources.

Provides a central location for accessing shared resources like language models, embedding models, and memory systems.

embedder

Text embedding model (e.g., SentenceTransformer)

Type:

Any

llm

Language model client

Type:

Any

memory

Memory storage and retrieval system

Type:

Any

tools

Dictionary of additional tool resources

Type:

Dict[str, Any]

embedder: Any

llm: Any

memory: Any

tools: Dict[str, Any]

class orka.contracts.Trace

Bases: TypedDict

Execution trace for debugging and monitoring.

Records detailed information about each step in the execution pipeline for auditing, debugging, and performance analysis.

v

Schema version number

Type:

int

trace_id

Unique identifier for this trace

Type:

str

agent_id

Identifier of the agent/node that generated this trace

Type:

str

timestamp

When this trace was created

Type:

datetime.datetime

input

The input data provided to the agent/node

Type:

Dict[str, Any]

output

The output produced by the agent/node

Type:

Dict[str, Any]

metadata

Additional contextual information

Type:

Dict[str, Any]

v: int

trace_id: str

agent_id: str

timestamp: datetime

input: Dict[str, Any]

output: Dict[str, Any]

metadata: Dict[str, Any]

class orka.contracts.MemoryEntry

Bases: TypedDict

Single memory entry with importance score.

Represents a piece of information stored in the memory system, with metadata about its importance and origin.

content

The actual text content of the memory

Type:

str

importance

Numerical score indicating the memory’s importance (0.0-1.0)

Type:

float

timestamp

When this memory was created or last updated

Type:

datetime.datetime

metadata

Additional information about the memory’s source and context

Type:

Dict[str, Any]

is_summary

Whether this entry is a summary of other memories

Type:

bool

category

Category for memory separation (log, stored, etc.)

Type:

str | None

content: str

importance: float

timestamp: datetime

metadata: Dict[str, Any]

is_summary: bool

category: str | None