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[source]
Bases:
TypedDictCore 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[source]
Bases:
TypedDictStandard 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[source]
Bases:
TypedDictConfiguration 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[source]
Bases:
TypedDictResource 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[source]
Bases:
TypedDictExecution 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[source]
Bases:
TypedDictSingle 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