Project Bootstrap

The bootstrap is the SDK entry point that every consumer project calls to register itself with ContextRouter. It replaces ~500 lines of per-project boilerplate with a single function call.

What Bootstrap Does

The SDK bootstrap pipeline runs four phases sequentially, with automatic retry on transient failures:

┌────────────────────────────────────┐
│ 1. Shield Session Token            │  (if Shield enabled)
│    Acquire session-scoped token    │
├────────────────────────────────────┤
│ 2. Shield Secrets Sync             │  (if Shield enabled)
│    Push API keys → Shield vault    │
├────────────────────────────────────┤
│ 3. Router Manifest Registration    │
│    RegisterManifest RPC → Router   │
├────────────────────────────────────┤
│ 4. Worker Schedule Registration    │
│    Sync cron schedules → Worker    │
├────────────────────────────────────┤
│ 5. BiDi Tool Executor Stream       │
│    Open persistent ToolExecutor    │
└────────────────────────────────────┘

After all registrations succeed, the bootstrap opens a persistent ToolExecutorStream for federated bidirectional tool execution.

Quick Start

Django Projects

myproject/apps.py

from django.apps import AppConfig

class ChatConfig(AppConfig):
    name = "chat"

    def ready(self):
        import chat.tools  # triggers @federated_tool registration

        from contextunity.core.sdk.bootstrap import bootstrap_django
        from chat.prompts import PLANNER_PROMPT, DB_SCHEMA

        bootstrap_django(
            prompts={"planner": PLANNER_PROMPT, "schema_description": DB_SCHEMA},
        )

bootstrap_django() auto-resolves the manifest path from settings.BASE_DIR / "contextunity.project.yaml" and handles Django’s runserver/gunicorn double-load guard.

Standalone Services

main.py

from contextunity.core.sdk.bootstrap import bootstrap_standalone

def main():
    import myproject.tools  # triggers @federated_tool registration

    bootstrap_standalone(
        prompts=load_prompts(),
        background=True,  # runs in daemon thread
    )
    asyncio.run(run_bot())

bootstrap_standalone() uses double-checked locking to ensure single initialization in long-running processes.

Low-Level API

For full control, use register_and_start() directly:

from contextunity.core.sdk.bootstrap import register_and_start

register_and_start(
    manifest_path="path/to/contextunity.project.yaml",
    prompt_map={
        "src/chat/prompts.py::PLANNER_PROMPT": PLANNER_PROMPT,
    },
    tool_handler=my_tool_handler,
    background=True,          # daemon thread (default)
    graceful_fallback=True,   # log error instead of crashing (default)
)

Manifest Discovery

The SDK resolves the manifest path using this priority chain:

1. Explicit argument — manifest_path="..." parameter
2. Environment variable — CU_MANIFEST_PATH (via SharedConfig)
3. Walk up from CWD — searches parent directories for contextunity.project.yaml

Prompt Map

The prompts parameter accepts two formats:

Format	Example	When
Short keys (recommended)	{"planner": text}	Keys match graph node names from the manifest
Full refs	{"src/chat/prompts.py::PLANNER_PROMPT": text}	Direct reference to source location

Short keys are resolved by inspecting the manifest’s graph node configuration:

• {node_name} → matches prompt_ref for that node
• {node_name}_sub_prompts → matches prompt_variants_ref

Prompt Integrity

After prompt resolution, bootstrap handles prompts according to the manifest security mode:

# Inside bootstrap (automatic)
sign_prompt_integrity(manifest_dict, project_id)

• Open Source: computes prompt_version and prompt_signature; SecureNode verifies the HMAC signature at execution time.
• Shield: computes prompt_version, publishes canonical prompts to Shield, strips resolved prompt text from Router registration, and lets Router fetch the prompt from Shield during execution.

Shield prompt reads use coarse shield:secrets:read plus tenant/project/node identity checks in Shield. Bootstrap writes use coarse shield:secrets:write; project policy does not need per-prompt Shield scopes.

Error Handling

Scenario	Behavior
Router unreachable	Infinite retry with exponential backoff
Shield unreachable	Retry → eventually proceeds without Shield (open-source mode)
Manifest not found	ConfigurationError raised immediately
Invalid manifest YAML	ConfigurationError raised immediately
graceful_fallback=True	Catches all errors, logs them, returns None
graceful_fallback=False	Propagates exceptions to the caller

Module Layout

packages/core/src/contextunity/core/sdk/bootstrap/
├── __init__.py      # Public exports: register_and_start, bootstrap_django, bootstrap_standalone
├── api.py           # register_and_start() — the core entry point
├── helpers.py       # bootstrap_django(), bootstrap_standalone() — convenience wrappers
├── loop.py          # _bootstrap_loop() — retry-resilient 4-phase orchestration
├── client.py        # gRPC transport: RegisterManifest, Shield secret/prompt sync
└── manifest.py      # Manifest loading, prompt resolution, prompt integrity metadata