Skip to content
Navigation

orbiter-context

Hierarchical state, prompt building, processors, and workspace for the Orbiter framework.

Hierarchical state, prompt building, processors, and workspace for the Orbiter framework.

Module Path

code
orbiter.context

Installation

bash
pip install "orbiter-context @ git+https://github.com/Midsphere-AI/orbiter-ai.git#subdirectory=packages/orbiter-context"

Overview

The orbiter-context package provides the context engine that manages per-task state, prompt composition, context processing, artifact storage, and checkpointing. It implements a hierarchical state model where child contexts inherit from parents, a composable neuron-based prompt builder, an event-driven processor pipeline, and a versioned workspace for artifact management.

Exports

ExportTypeDescription
ContextClassPer-task context with fork/merge lifecycle
ContextErrorExceptionContext lifecycle errors
ContextConfigPydantic modelImmutable context configuration
AutomationModeStrEnumAutomation level (pilot/copilot/navigator)
make_configFunctionFactory for preset ContextConfig
ContextStateClassHierarchical key-value state
NeuronABCComposable prompt fragment producer
neuron_registryRegistry[Neuron]Global neuron instance registry
PromptBuilderClassComposes neurons into system prompts
ContextProcessorABCEvent-driven context processor
ProcessorPipelineClassRegisters and fires processors by event
SummarizeProcessorClassMarks context for summarization
ToolResultOffloaderClassOffloads large tool results
WorkspaceClassPersistent artifact storage with versioning
ArtifactTypeStrEnumArtifact classification
CheckpointDataclassImmutable state snapshot
CheckpointStoreClassPer-session checkpoint management
TokenTrackerClassPer-agent token usage tracking
get_context_toolsFunctionAll context tools (planning + knowledge + file)
get_planning_toolsFunctionTodo/checklist tools
get_knowledge_toolsFunctionKnowledge retrieval tools
get_file_toolsFunctionFile reading tools

Import Patterns

python
# Import from package root
from orbiter.context import (
    Context, ContextConfig, ContextState,
    PromptBuilder, Neuron, neuron_registry,
    Workspace, ArtifactType,
    Checkpoint, CheckpointStore,
    TokenTracker,
)

# Import specific modules
from orbiter.context.context import Context, ContextError
from orbiter.context.config import ContextConfig, AutomationMode, make_config
from orbiter.context.state import ContextState
from orbiter.context.neuron import Neuron, neuron_registry
from orbiter.context.prompt_builder import PromptBuilder
from orbiter.context.processor import ContextProcessor, ProcessorPipeline
from orbiter.context.workspace import Workspace, ArtifactType
from orbiter.context.tools import get_context_tools

Quick Example

python
import asyncio
from orbiter.context import (
    Context, ContextConfig, AutomationMode,
    PromptBuilder, Workspace,
)

async def main():
    # Create context with navigator automation
    ctx = Context("task-1", config=ContextConfig(mode=AutomationMode.NAVIGATOR))

    # Set task state
    ctx.state.set("task_input", "Write a Python function to sort a list")

    # Build prompt from neurons
    builder = PromptBuilder(ctx)
    builder.add("task").add("system")
    prompt = await builder.build()
    print(prompt)

    # Fork for sub-task
    child = ctx.fork("subtask-1")
    child.state.set("progress", "step 1 done")

    # Merge back
    ctx.merge(child)

    # Workspace for artifacts
    ws = Workspace("ws-1")
    await ws.write("solution.py", "def sort_list(lst): return sorted(lst)")
    print(ws.read("solution.py"))

asyncio.run(main())

Architecture

code
Context
  |-- ContextConfig (immutable settings)
  |-- ContextState (hierarchical key-value, parent chain)
  |-- CheckpointStore (save/restore snapshots)
  |
  |-- fork() --> child Context (inherited state)
  |-- merge() <-- child state consolidated back

PromptBuilder
  |-- add("neuron_name") --> resolves from neuron_registry
  |-- build() --> sorted by priority, formatted, joined

ProcessorPipeline
  |-- register(SummarizeProcessor())
  |-- fire("pre_llm_call", ctx, payload)

Workspace
  |-- write/read/delete artifacts
  |-- version history with revert
  |-- observer callbacks (on_create, on_update, on_delete)
  |-- KnowledgeStore integration (auto-indexing)

See Also