KDCube Platform Documentation

What Is a Bundle?

A Bundle is your application package. It combines Python backend code with optional TypeScript UI widgets and views into a single deployable unit. The package becomes a bundle by subclassing the platform's base class (BaseEntrypoint or a derived variant) and registering with @agentic_workflow.

App sources live in git. The platform's assembly descriptor points to a git repo, ref, and subdirectory. On deploy, the CLI or CI pipeline pulls the ref and registers the bundle. You can update a running deployment by pushing a new ref and re-running the deploy step — no service restart required.

Most example bundles use the ReAct agent (ReactStateV2), but a bundle does not have to. You can use any LangGraph graph, a simple request→response pipeline, or no LLM at all.

Example Bundles

Start from any of the examples in sdk/examples/bundles/. The simplest starting point is react@2026-02-10-02-44 — a minimal ReAct agent with no custom tools.

Platform Architecture for Bundle Developers

See also: Platform Overview

KDCube is a multi-tenant AI application platform. It provides the infrastructure for deploying conversational AI agents at scale — with streaming, storage, economics, tooling, and extensibility all built in.

A Bundle is your unit of deployment. It's a Python package that plugs into the platform and defines how your AI agent thinks, what tools it uses, how it stores data, what UI widgets it exposes, and how it bills users.

Big Picture: How It All Fits Together

Two Services, One Platform

Bundle Anatomy

A bundle is a Python package with a required entrypoint.py and optional supporting files:

Minimal Entrypoint

from kdcube_ai_app.infra.plugin.agentic_loader import agentic_workflow
from kdcube_ai_app.apps.chat.sdk.solutions.chatbot.entrypoint import BaseEntrypoint
from langgraph.graph import StateGraph, START, END
from typing import Dict, Any

BUNDLE_ID = "my-bundle"

@agentic_workflow(bundle_id=BUNDLE_ID)
class MyBundle(BaseEntrypoint):

    @property
    def configuration(self) -> Dict[str, Any]:
        return {
            "role_models": {
                "solver.react.v2.decision.v2.strong": {
                    "provider": "anthropic",
                    "model": "claude-sonnet-4-6"
                }
            }
        }

    def on_bundle_load(self, **kwargs):
        # Called ONCE per process when bundle first loads.
        self.logger.info("Bundle loaded!")

    async def execute_core(self, state, thread_id, params):
        graph = StateGraph(dict)
        graph.add_node("run", self._run_node)
        graph.add_edge(START, "run"); graph.add_edge("run", END)
        return await graph.compile().ainvoke(state)

    async def _run_node(self, state):
        await self._comm.delta(text="Hello from my bundle!", index=0, marker="answer")
        return {"final_answer": "Done", "followups": []}

BaseEntrypoint Lifecycle

Interface: In & Out

Using the Communicator

# Stream answer text
await self._comm.delta(text="chunk...", index=0, marker="answer")

# Announce a step
await self._comm.step(step="web_search", status="started", title="Searching the web...")
await self._comm.step(step="web_search", status="completed")

# Emit follow-up suggestions
await self._comm.followups(["Tell me more", "Show examples"])

# Final complete signal
await self._comm.complete(data={"answer": "..."})

REST Operations (for UI Widgets)

Your bundle exposes additional REST operations via the Operations API hosted by the Processor:

POST /bundles/{tenant}/{project}/operations/{operation}

The platform calls your_workflow.{operation}(**request_body). Define operations as async methods in your workflow or entrypoint. This is how UI widgets communicate back to your bundle (see Widgets / UI).

Continuation Types

Storage

KDCube is a distributed, multi-tenant system. Three storage tiers are available to your bundle:

Cloud Storage (AIBundleStorage)

from kdcube_ai_app.apps.chat.sdk.storage.ai_bundle_storage import AIBundleStorage

storage = AIBundleStorage(
    tenant="my-tenant", project="my-project",
    ai_bundle_id="my-bundle@1-0",
    storage_uri="s3://my-bucket"  # or file:///data/bundle-storage
)

storage.write("reports/latest.json", data='{"count": 42}')
content = storage.read("reports/latest.json", as_text=True)
keys = storage.list("reports/")

Local FS (Shared Bundle Storage)

# In entrypoint or workflow
root = self.bundle_storage_root()  # pathlib.Path
index_path = root / "knowledge_index"
index_path.mkdir(exist_ok=True)

Path namespaced: {BUNDLE_STORAGE_ROOT}/{tenant}/{project}/{bundle_id}/. Ideal for knowledge indexes, model weights, large caches. In production, mount an EFS volume.

Redis Cache

# Low-level Redis client (aioredis)
await self.redis.set("my:key", "value", ex=3600)
val = await self.redis.get("my:key")

# KVCache wrapper
await self.kv_cache.set("user_prefs", {"theme": "dark"}, ttl=86400)

Configuration & Secrets

bundles.yaml — Your Bundle Definition

bundles:
  version: "1"
  default_bundle_id: "my-bundle@1-0"
  items:
    - id: "my-bundle@1-0"
      name: "My Bundle"
      repo: "git@github.com:org/my-bundle-repo.git"   # optional git source
      ref: "v1.0.0"
      subdir: "src/my_bundle"
      module: "my-bundle@1-0.entrypoint"
      config:
        embedding:
          provider: "openai"
          model: "text-embedding-3-small"
        role_models:
          solver.react.v2.decision.v2.strong:
            provider: "anthropic"
            model: "claude-sonnet-4-6"
        economics:
          reservation_amount_dollars: 2.0
        execution:
          runtime:
            mode: "docker"   # docker is default — see Exec Runtime section
            enabled: true

Bundle Secrets — Managed by kdcube-secrets (Never on Disk)

Bundle secrets are provisioned via the Admin UI or injected into kdcube-secrets at setup time. They are resolved in-memory at runtime and are never written to disk. The bundles.secrets.yaml format below is only used as a transient CLI input during initial provisioning — it is not stored in the workdir.

bundles:
  version: "1"
  items:
    - id: "my-bundle@1-0"
      secrets:
        openai:
          api_key: null          # null = resolve from env OPENAI_API_KEY
        my_service:
          api_key: "sk-live-..."  # inline value — consumed by CLI, not stored
          webhook_url: "env:MY_WEBHOOK_URL"  # or env: reference

Reading Config & Secrets in Code

value = self.bundle_prop("some.nested.key")   # dot-path navigation
all_props = self.bundle_props                    # full merged dict

from kdcube_ai_app.apps.chat.sdk.config import get_secret
api_key = get_secret("bundles.my-bundle@1-0.secrets.my_service.api_key")

Configuration Resolution Order

Reserved Property Paths

See full config docs: bundle-configuration-README.md

Workflow Orchestration

The platform uses LangGraph for workflow orchestration. Your execute_core builds and invokes a StateGraph. For common patterns, use BaseWorkflow:

from kdcube_ai_app.apps.chat.sdk.solutions.chatbot.base_workflow import BaseWorkflow

class MyWorkflow(BaseWorkflow):
    def __init__(self, *args, bundle_props=None, **kwargs):
        super().__init__(*args, bundle_props=bundle_props, **kwargs)

    async def process(self, payload):
        scratchpad = self.start_turn(payload)
        try:
            react = await self.build_react(
                scratchpad=scratchpad,
                tools_module="my_bundle.tools_descriptor",
                skills_module="my_bundle.skills_descriptor",
            )
            result = await react.run(payload)
            self.finish_turn(scratchpad, ok=True)
            return result
        except Exception as e:
            self.finish_turn(scratchpad, ok=False); raise

BaseWorkflow Key Parameters

Simplest Agentic Workflow Pattern

A bundle can use any orchestration pattern — it is not required to use the ReAct agent. This is one common pattern that combines a Gate agent with the ReAct agent:

Tools System

# tools/my_tools.py
from typing import Annotated
import semantic_kernel as sk
from semantic_kernel.functions import kernel_function

class MyTools:
    @kernel_function(name="search", description="Search product catalog")
    async def search(self,
        query: Annotated[str, "Search query"],
        limit: Annotated[int, "Max results"] = 5
    ) -> str:
        # your logic here
        return "results..."

# tools_descriptor.py
TOOLS_SPECS = [
    # SDK built-in tool modules (installed package)
    {"module": "kdcube_ai_app.apps.chat.sdk.tools.web_tools", "alias": "web_tools", "use_sk": True},
    {"module": "kdcube_ai_app.apps.chat.sdk.tools.exec_tools", "alias": "exec_tools", "use_sk": True},
    # Bundle-local tools ("ref" = path relative to bundle root, works in Docker too)
    {"ref": "tools/my_tools.py", "alias": "my_tools", "use_sk": True},
]
# Tool IDs: web_tools.web_search, exec_tools.execute_code_python, my_tools.search

# Optional: per-tool runtime overrides
TOOL_RUNTIME = {
    "web_tools.web_search": "local",       # subprocess sandbox
    "exec_tools.execute_code_python": "docker",  # Docker container
}

# tools_descriptor.py
MCP_TOOL_SPECS = [
    {"server_id": "web_search", "alias": "web_search", "tools": ["web_search"]},
    {"server_id": "docs", "alias": "docs", "tools": ["*"]},  # all tools
    {"server_id": "stack", "alias": "stack", "tools": ["*"]},
]
# Tool IDs: mcp.docs.some_tool, mcp.stack.some_tool

# bundles.yaml config section — how to connect
config:
  mcp:
    services:
      mcpServers:
        docs:
          transport: http
          url: https://mcp.example.com
          auth:
            type: bearer
            secret: bundles.my-bundle.secrets.docs.token
        stack:
          transport: stdio
          command: npx
          args: ["mcp-remote", "mcp.stackoverflow.com"]

Artifact Path Families

Skills System

Skills are reusable instruction sets that give agents specialized capabilities. A skill bundles a natural-language instruction (SKILL.md), tool references, and source references.

Built-in Platform Skills

Custom Bundle Skill

# skills/my_skill/SKILL.md
You are an expert in our product catalog.
When asked about products, use the `product_search` tool to find relevant items.
Always include pricing and availability.

# skills/my_skill/tools.yaml
tools:
  - id: product_search
    role: search
    why: Search the product catalog

# skills_descriptor.py
AGENTS_CONFIG = {
    "solver": {
        "enabled_skills": ["my_skill", "pdf-press", "url-gen"],
        "disabled_skills": []
    }
}

ReAct Agent (V2)

The ReAct V2 agent is a single autonomous loop — no separate planner, no gate. It starts in runtime.py as a ReactStateV2 with up to max_iterations=6 rounds. In each round the agent makes a decision (LLM call) then executes one or more tools. Planning is available as a tool the agent can call on itself — not a separate orchestration layer.

ReAct Agent V2 — Loop & Tool Integration

Creating and Running the ReAct Agent

# In your workflow (BaseWorkflow subclass)
react = await self.build_react(
    scratchpad=scratchpad,
    tools_module="my_bundle.tools_descriptor",
    skills_module="my_bundle.skills_descriptor",
    knowledge_space_fn=self._search_knowledge,   # optional
    knowledge_read_fn=self._read_knowledge,      # optional
)
result = await react.run(payload)

Timeline

The timeline (timeline.py) is the single source of truth for turn context. It is persisted as artifact:conv.timeline.v1 and loaded at the start of each turn. A separate artifact:conv:sources_pool tracks all sources referenced in the conversation.

Cache checkpoints are computed by rounds (tool call rounds + final completion). They allow LLM context caching to skip retokenizing earlier parts of long conversations. See timeline-README.md, source-pool-README.md, and react-announce-README.md.

Multi-Channel Streaming

ReAct Agent Documentation

Full docs live in docs/sdk/agents/react/. Key files:

Isolated Execution Runtime

The platform provides a sandboxed code execution runtime — your agent can generate and run arbitrary Python code in complete isolation. The runtime has a clear two-zone model:

• Supervisor — networked, has env secrets and full runtime context. All bundle tools from tools_descriptor.py execute here, including MCP tools, bundle-local tools, and custom SDK tools. The ChatCommunicator is also available to tool code, streaming events via Redis Pub/Sub to the client SSE.
• Executor — completely isolated: no network, no env secrets, separate Linux namespace (UID 1001). Runs LLM-generated code. All tool calls are proxied to the Supervisor over a Unix socket. Can only write to /workspace/work and /workspace/out.

Two execution backends are practical:

execution:
  runtime:
    mode: "docker"
    enabled: true  # default

execution:
  runtime:
    mode: "fargate"
    cluster: "arn:aws:ecs:..."
    task_definition: "exec-task"

Exec Environment Variables (Inside Executed Code)

See external-exec-README.md

Knowledge Space

Bundles can expose a searchable knowledge space built from a Git repository's docs, source code, deployment configs, and tests.

return {
    "knowledge": {
        "repo": "https://github.com/org/repo.git",  # "" = local repo
        "ref": "main",
        "docs_root": "app/docs",
        "src_root": "app/src",
        "deploy_root": "app/deploy",
        "tests_root": "app/tests",
        "validate_refs": True
    }
}

• on_bundle_load() — Builds the index once per process (file-locked, signature-cached)
• pre_run_hook() — Reconciles if config changed

Agent access via ks: paths: react.search_knowledge(query=..., limit=5) and react.read(["ks:docs/architecture.md"])

Context, RAG & Conversations

Context RAG Client

# self.ctx_client is ContextRAGClient
results = await self.ctx_client.search(
    query="previous analysis of sales data",
    kind="assistant",   # or "user" | "attachment"
    limit=5
)
artifact = await self.ctx_client.fetch_ctx(["ar:turn_abc.artifacts.summary"])

Conversations API Endpoints

GET  /conversations/{tenant}/{project}
POST /conversations/{tenant}/{project}/fetch
POST /conversations/{tenant}/{project}/{conv_id}/turns-with-feedbacks
POST /conversations/{tenant}/{project}/feedback/conversations-in-period

The react.memsearch tool provides vector search in past turns directly inside the agent loop. The ConversationStore (accessible via BaseWorkflow.store) manages turn payloads, timelines, and artifacts.

Timeline & Context Layout

Each conversation maintains a rolling timeline of turn artifacts stored as artifact:conv.timeline.v1. The timeline is the canonical cross-turn context passed to the LLM. It is structured as an ordered sequence of turn records, each containing user input, assistant output, tool calls, and any attached artifacts.

Cache Points

The platform inserts up to three LLM-level cache checkpoints per turn: prev-turn (the end of the prior turn), pre-tail (just before the current turn's tail), and tail (after the current turn). These cache points allow the LLM inference layer to reuse context prefix KV-cache across turns, reducing both latency and token cost for multi-turn conversations.

Compaction

When the accumulated timeline approaches the configured context budget ceiling, the platform triggers compaction: older turn ranges are summarized into a compact conv.range.summary artifact and replaced in the timeline. This is a hard-ceiling guard — it ensures context never silently overflows the model's context window. Compaction is transparent to bundle code.

Hosting & File Resources

Your bundle can produce files (PDFs, PNGs, data exports) and make them available via hosted URLs. The platform handles upload, serving, and access control automatically.

# ApplicationHostingService (via BaseWorkflow.hosting_service)
url = hosting.get_artifact_url("fi:turn_123.files/report.pdf")

# Resource Name format
# ef:{tenant}:{project}:chatbot:{stage}:{user_id}:{conv_id}:{turn_id}:{role}:{path}
# Resolved by POST /by-rn with authentication enforced by platform

Files written to OUTPUT_DIR/turn_{id}/files/ during exec are automatically tracked and can be served. User attachments appear as fi:{turn_id}.user.attachments/{filename}.

Citations & Sources

Citation Tokens

The company was founded in 2015 [[S:1]] and expanded by 2020 [[S:2,3]].
According to multiple sources [[S:1-4]], the trend is clear.

Sources Pool Fields

See citations-system.md and source-pool-README.md

Feedback System

POST /conversations/{tenant}/{project}/{conv_id}/turns/{turn_id}/feedback

{ "reaction": "ok", "text": "Very helpful!", "ts": "2026-03-21T10:00:00Z" }
# reaction: ok | not_ok | neutral | null

Your bundle can also emit machine feedback (origin: "machine") for confidence scores or quality checks — additive, not replacing user feedback. Satisfaction rate: ok / (ok + not_ok + neutral).

See feedback-system.md

Bundle Economics & Rate Limiting

from kdcube_ai_app.apps.chat.sdk.solutions.chatbot.entrypoint_with_economic import (
    BaseEntrypointWithEconomics
)

@agentic_workflow(bundle_id=BUNDLE_ID)
class MyBundle(BaseEntrypointWithEconomics):
    @property
    def configuration(self):
        return {"economics": {"reservation_amount_dollars": 2.0}, ...}

Default Quota Policies

Widgets & Custom UI

Your bundle can expose React SPA widgets embedded in the platform UI. Define an operation that returns HTML (a React app), and the UI renders it. The React app can in turn call back to POST /operations/{op} for any further interactions.

Example: Return a React SPA

async def my_dashboard(self, **kwargs) -> dict:
    """My Dashboard widget — loaded by UI when user clicks the button."""
    html = """<!DOCTYPE html><html><body>
      <div id="root"></div>
      <script>
        // Your bundled React app
        // Can POST back to /bundles/{tenant}/{project}/operations/my_api
      </script>
    </body></html>"""
    return {"html": html, "content_type": "text/html"}

Platform Built-in Operations

Deploying Your Bundle

Option A: With the KDCube Platform

1. 1

   Push your bundle to Git

   git push origin v1.0.0

2. 2

   Add to bundles.yaml

   - id: "my-bundle@1-0"
     repo: "git@github.com:org/my-bundle.git"
     ref: "v1.0.0"
     module: "my_bundle.entrypoint"

3. 3

   Inject secrets and apply

   kdcube-setup --secrets-set GIT_HTTP_TOKEN=ghp_...
   kdcube-setup --secrets-prompt  # for LLM keys

   The bundle config is applied immediately via Redis — no restart needed. Change the ref and re-run to switch bundle versions on the fly.

4. 4

   Set as default bundle via the Admin Dashboard

   Open the AI Bundle Dashboard (/api/integrations/bundles/{tenant}/{project}/operations/ai_bundle). Your registered bundle appears in the list. Set it as the default_bundle_id for the tenant/project. The change is applied immediately via Redis — no restart needed.

Option B: Standalone (Without Platform)

Bundles can run outside the platform. The SDK is a plain Python package — build your own FastAPI app that imports and invokes it directly. Or build a custom Docker image that runs just your bundle with its own server. The platform's value is in hosting, auth, SSE, storage, economics, and UI — none of that is required for the core agent logic.

Bundle Git Auth

Example Bundles

Documentation Reference

Coming Soon & Current Status

Here's the current state of platform capabilities and what's next on the roadmap: