cube-agent-harness 0.1.0__tar.gz

cube_agent_harness-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.venv/
+venv/
+env/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.tsbuildinfo
+.coverage
+htmlcov/
+
+build/
+dist/
+*.egg-info/
+
+.idea/
+.vscode/
+.DS_Store
+
+.claude/
+cube-dev/
+cube-root/
+test-results/
+apps/playground/test-results/
+.env
+.env.*
+!.env.template
+
+apps/playground/node_modules/
+apps/playground/.next/
+apps/playground/out/
+apps/playground/.env.local
+.worktrees/
+.superpowers/
+.tmp/
+deploy/local/sandbox-tools/node_modules/
+/apps/playground/docs/

cube_agent_harness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 psh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cube_agent_harness-0.1.0/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: cube-agent-harness
+Version: 0.1.0
+Summary: Open-source Python SDK for embeddable, plugin-extensible agents
+Project-URL: Homepage, https://github.com/mindshake-ai/cube
+Author: psh
+License: MIT License
+        
+        Copyright (c) 2026 psh
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,llm,plugins,sdk,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.12
+Requires-Dist: jsonref>=1.1.0
+Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic>=2.12.0
+Provides-Extra: all
+Requires-Dist: aiosqlite<1.0,>=0.21; extra == 'all'
+Requires-Dist: asyncmy<1.0,>=0.2.10; extra == 'all'
+Requires-Dist: litellm>=1.80.0; extra == 'all'
+Requires-Dist: mcp>=1.27.1; extra == 'all'
+Requires-Dist: pymupdf<2,>=1.26.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0.0; extra == 'all'
+Requires-Dist: redis<7.0,>=5.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]<2.2,>=2.0.39; extra == 'all'
+Requires-Dist: sqlmodel>=0.0.38; extra == 'all'
+Provides-Extra: cluster
+Requires-Dist: aiosqlite<1.0,>=0.21; extra == 'cluster'
+Requires-Dist: asyncmy<1.0,>=0.2.10; extra == 'cluster'
+Requires-Dist: pyyaml>=6.0.0; extra == 'cluster'
+Requires-Dist: redis<7.0,>=5.0; extra == 'cluster'
+Requires-Dist: sqlalchemy[asyncio]<2.2,>=2.0.39; extra == 'cluster'
+Requires-Dist: sqlmodel>=0.0.38; extra == 'cluster'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.80.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.27.1; extra == 'mcp'
+Provides-Extra: media
+Requires-Dist: pymupdf<2,>=1.26.0; extra == 'media'
+Provides-Extra: platform
+Requires-Dist: aiosqlite<1.0,>=0.21; extra == 'platform'
+Requires-Dist: pyyaml>=6.0.0; extra == 'platform'
+Requires-Dist: sqlalchemy[asyncio]<2.2,>=2.0.39; extra == 'platform'
+Requires-Dist: sqlmodel>=0.0.38; extra == 'platform'
+Description-Content-Type: text/markdown
+
+# Cube
+
+Cube is an open-source Python agent harness for building embeddable,
+tool-using, plugin-extensible agents. It provides a lightweight runtime kernel,
+an optional local-first application host for durable sessions and workspaces,
+and an optional distributed runtime layer for backend/worker deployments.
+
+## Public Surfaces
+
+- `cube.core`: platform-free harness kernel for agent runs, messages, tools,
+  hooks, LLM clients, MCP adapters, events, cancellation, and runtime state.
+- `cube.platform`: Cube's local-first application platform, including the plugin
+  SPI/host, agency member projections, channel, durable session, workspace,
+  database, and runtime contracts.
+- `cube.cluster`: distributed runtime coordination for backend/worker
+  deployments using MySQL, Redis, and a shared POSIX workspace.
+- `cube.plugins`: official concrete capability plugins for tools, hooks,
+  channel types, chat, task/workflow, and sub-agents.
+- `apps/cli`: independent official command-line application, distributed as
+  `cube-cli` and installed with the `cube` command.
+- `apps/playground`: official full-stack reference application, split into an
+  independent FastAPI backend and a Next.js frontend. Neither is part of the
+  `cube` wheel.
+
+Most developers should extend Cube through plugins. Advanced users can embed
+`cube.platform.CubeLocalApp` for the batteries-included local host, or use
+`cube.core` directly when they only need the harness kernel.
+
+## Install And Run
+
+```bash
+pip install cube-cli
+cube --help
+cube --root-dir ./cube-data init
+cube --root-dir ./cube-data db init
+cube --root-dir ./cube-data user use alice --name "Alice"
+```
+
+The base install is intentionally lightweight:
+
+```bash
+pip install cube-agent-harness
+```
+
+It provides `cube.core` plus lightweight plugin model contracts under
+`cube.platform.plugin`. Install optional
+adapters only when you need them:
+
+```bash
+pip install cube-agent-harness[llm]           # LiteLLM clients, router, model catalog
+pip install cube-agent-harness[mcp]           # MCP transport clients
+pip install cube-agent-harness[platform]      # local-first platform and SQLite
+pip install cube-agent-harness[cluster]       # distributed runtime with MySQL/Redis
+pip install cube-agent-harness[all]           # every built-in SDK capability extra
+```
+
+The default local database path is:
+
+```text
+<root_dir>/cube.sqlite3
+```
+
+## Layout
+
+```text
+cube/
+├── core/              # framework kernel; must not import platform/plugins
+│   ├── runtime/       # AgentRuntime, agent loop, run context, events
+│   ├── tool/          # Tool protocol, ToolRuntime, ToolTask lifecycle
+│   ├── hook/          # hook types, dispatcher, reducers, HookRegistry
+│   ├── llm/           # LLM client contracts and LiteLLM adapters
+│   ├── mcp/           # MCP adapter/client support
+│   └── common/        # ids, time helpers, EventBus, CancellationToken
+├── platform/
+│   ├── host/          # CubeLocalApp, PlatformServices, PlatformRuntime, health
+│   ├── assembly/      # manifest-driven plugin/table runtime assembly
+│   ├── command/       # transport-neutral session command contracts
+│   ├── event/         # live session event stream contracts
+│   ├── agency/        # tenant container and member projections
+│   ├── channel/       # project/room container and session definitions
+│   ├── session/       # durable transcript/session container
+│   ├── notification/  # central durable human inbox
+│   ├── agent/         # default Agent worker implementation
+│   ├── plugin/        # plugin SPI, discovery, resolver, assembly, registry
+│   ├── workspace/     # local file workspace layout
+│   └── database/      # SQLModel/SQLite platform persistence
+├── cluster/           # distributed Gateway/Worker runtime coordination
+└── plugins/
+    ├── tools/         # official filesystem/chat/background tools
+    ├── hooks/         # official concrete hooks
+    ├── channels/
+    │   ├── chat/      # dm and group_chat channel types
+    │   └── project/   # project channel type and project query service
+    ├── sessions/
+    │   ├── chat/      # chat session capability
+    │   └── task/      # multi-phase task and workflow capability
+    └── subagent/      # complete sub-agent capability and tool-owned session
+
+apps/
+├── cli/               # official cube-cli terminal application
+└── playground/        # official full-stack reference app
+    ├── backend/       # project-owned FastAPI/auth/realtime composition
+    └── frontend/      # Next.js playground UI
+```
+
+## Architecture
+
+`cube.core` is the agent harness kernel. It has no database, session, channel,
+web framework, CLI, agency, user, plugin loading, or provider-SDK dependency.
+Importing `cube`, `cube.core`, `cube.core.llm`, or
+`cube.platform.plugin.PluginSpec` does
+not load optional adapters such as LiteLLM, FastAPI, SQLModel, MCP, or Typer.
+
+`cube.platform` assembles the harness into a durable local application. It does
+not own a global account table, credentials, passwords, or authentication.
+Human identity inside Cube is an agency-scoped member projection stored with
+the agency; embedding applications own accounts and map authenticated users to
+those projections.
+Long-lived, human-editable configuration lives in file workspaces under
+`<root_dir>/`. Runtime transcript, run state, task state, background tool
+state, metrics, and small app records live in SQLite.
+
+`cube.platform.plugin` owns the plugin SPI, discovery, selection, dependency
+resolution, transactional registration, and frozen capability registry.
+`cube.plugins` contains Cube's official implementations. Official and user
+plugins use the same `PluginSpec` model and `cube.plugins` entry-point group to
+contribute tools, hooks, hook events, session kinds, channel types, and the
+SubAgent provider. Runtime table registration remains a separate
+`tables.toml` / `TableSpec` path.
+Session-specific message and event types are declared by the session class.
+
+Loading and runtime ownership follow parallel boundaries:
+
+```text
+PluginSpec -> PluginManager -> PluginRegistry
+TableSpec  -> TableManager  -> TableRegistry
+```
+
+The plugin and table managers load declarations independently.
+`RuntimeAssembly` validates and freezes both registries, `PlatformServices`
+owns that immutable assembly, and `PlatformRuntime` consumes the durable
+service root rather than loading capabilities itself.
+
+`apps/cli` and project backends such as `apps/playground/backend` are
+application-owned compositions. They use public `cube.platform` composition
+helpers, while each application owns the default
+`plugins.toml` and `tables.toml` it writes.
+
+`cube.cluster` is the optional distributed runtime layer. Backend applications
+compose `PlatformServices` with `ClusterGateway` for command dispatch and live
+event subscription; worker processes run `ClusterWorker`, which owns
+`PlatformRuntime` and executes sessions. Distributed mode uses MySQL for Cube
+durable data, Redis for coordination, and a shared POSIX `root_dir` such as
+NAS. It does not provide a `CubeApp` facade or a local fallback.
+
+## Plugin Development
+
+External plugins expose a `PluginSpec` through the `cube.plugins` entry point
+group:
+
+```python
+from cube.platform.plugin import PluginSpec
+
+
+def register(ctx):
+    ctx.tools("finance_controls", my_tool)
+
+
+plugin = PluginSpec(
+    name="my.company.finance",
+    version="0.1.0",
+    requires_tables=("my.company.finance",),
+    register=register,
+)
+```
+
+```toml
+[project.entry-points."cube.plugins"]
+"my.company.finance" = "my_company_finance.plugin:plugin"
+```
+
+Plugins with persistence export an independent `TableSpec` and list its logical
+name in `requires_tables`. The host must still enable the table module in
+`tables.toml`; runtime composition reports a missing requirement before database
+initialization and never auto-loads plugin tables.
+
+Plugin and table loading is manifest-driven. Run the owning host's initializer
+(`cube init` for the CLI or `playground-backend init` for the Playground), or
+write `plugins.toml` / `tables.toml` explicitly before composing the runtime.
+
+`SessionContribution.required_tools` and `required_hooks` are session kind
+invariants. They describe capabilities the kind needs to run and are separate
+from `[assembly].default_tools`, which are optional agent tools filtered by
+agent tool-use policy. Default and required hook groups remain distinct during
+capability-name assembly, then runtime materialization combines their handlers
+into one prepared `HookRuntime`; sessions and agents consume that runtime rather
+than assembling hook extension registries themselves.
+
+`cube.core` exposes a small stable convenience API. Import provider-specific
+clients and lower-level runtime events from their package-local modules, for
+example `cube.core.llm.LiteLLMClient` or `cube.core.runtime.AgentStartEvent`.
+
+## Development
+
+For the fastest full-stack distributed Playground loop on macOS, install `uv`
+and Node.js 20.11 or newer, place the supplied deployment environment at the
+repository-root `.env`, then run:
+
+```bash
+make doctor
+make local-start
+make local-status
+make local-logs
+# Open http://localhost:3000
+make local-restart
+make local-shutdown
+```
+
+`local-start` runs separate ClusterWorker and distributed Playground backend
+processes plus the Next.js development server. It installs the pinned local SRT
+and ripgrep packages inside the repository, preserves existing runtime
+manifests, initializes/validates the MySQL schema, and waits for worker and HTTP
+readiness. Use `ENV_FILE=config/alice.env` for a non-default environment file.
+See [`deploy/README.md`](deploy/README.md) for prerequisites, per-developer
+cluster isolation, troubleshooting, Docker image validation, and Make variable
+overrides.
+
+Package and test development commands:
+
+```bash
+uv sync --all-packages --all-extras --dev
+uv run --all-extras pytest tests -q
+uv run --package cube-cli pytest apps/cli/tests -q
+uv run --package cube-playground-backend pytest apps/playground/backend/tests -q
+uv run --all-extras python -m compileall cube tests
+uv run --package cube-cli cube --help
+uv build --package cube
+uv build --package cube-cli
+npm --prefix apps/playground/frontend run typecheck
+npm --prefix apps/playground/frontend run build
+```
+
+Core boundary check:
+
+```bash
+rg -n "^\s*(from|import) cube\.(platform|plugins)" cube/core --glob '*.py'
+```
+
+See also:
+
+- `docs/README.md`
+- `docs/api-stability.md`
+- `docs/embedding.md`
+- `docs/cluster-runtime.md`
+- `cube/core/README.md`
+- `cube/platform/README.md`
+- `cube/plugins/README.md`
+- `apps/cli/README.md`
+- `apps/playground/README.md`
+- `deploy/README.md`

cube_agent_harness-0.1.0/README.md

@@ -0,0 +1,260 @@
+# Cube
+
+Cube is an open-source Python agent harness for building embeddable,
+tool-using, plugin-extensible agents. It provides a lightweight runtime kernel,
+an optional local-first application host for durable sessions and workspaces,
+and an optional distributed runtime layer for backend/worker deployments.
+
+## Public Surfaces
+
+- `cube.core`: platform-free harness kernel for agent runs, messages, tools,
+  hooks, LLM clients, MCP adapters, events, cancellation, and runtime state.
+- `cube.platform`: Cube's local-first application platform, including the plugin
+  SPI/host, agency member projections, channel, durable session, workspace,
+  database, and runtime contracts.
+- `cube.cluster`: distributed runtime coordination for backend/worker
+  deployments using MySQL, Redis, and a shared POSIX workspace.
+- `cube.plugins`: official concrete capability plugins for tools, hooks,
+  channel types, chat, task/workflow, and sub-agents.
+- `apps/cli`: independent official command-line application, distributed as
+  `cube-cli` and installed with the `cube` command.
+- `apps/playground`: official full-stack reference application, split into an
+  independent FastAPI backend and a Next.js frontend. Neither is part of the
+  `cube` wheel.
+
+Most developers should extend Cube through plugins. Advanced users can embed
+`cube.platform.CubeLocalApp` for the batteries-included local host, or use
+`cube.core` directly when they only need the harness kernel.
+
+## Install And Run
+
+```bash
+pip install cube-cli
+cube --help
+cube --root-dir ./cube-data init
+cube --root-dir ./cube-data db init
+cube --root-dir ./cube-data user use alice --name "Alice"
+```
+
+The base install is intentionally lightweight:
+
+```bash
+pip install cube-agent-harness
+```
+
+It provides `cube.core` plus lightweight plugin model contracts under
+`cube.platform.plugin`. Install optional
+adapters only when you need them:
+
+```bash
+pip install cube-agent-harness[llm]           # LiteLLM clients, router, model catalog
+pip install cube-agent-harness[mcp]           # MCP transport clients
+pip install cube-agent-harness[platform]      # local-first platform and SQLite
+pip install cube-agent-harness[cluster]       # distributed runtime with MySQL/Redis
+pip install cube-agent-harness[all]           # every built-in SDK capability extra
+```
+
+The default local database path is:
+
+```text
+<root_dir>/cube.sqlite3
+```
+
+## Layout
+
+```text
+cube/
+├── core/              # framework kernel; must not import platform/plugins
+│   ├── runtime/       # AgentRuntime, agent loop, run context, events
+│   ├── tool/          # Tool protocol, ToolRuntime, ToolTask lifecycle
+│   ├── hook/          # hook types, dispatcher, reducers, HookRegistry
+│   ├── llm/           # LLM client contracts and LiteLLM adapters
+│   ├── mcp/           # MCP adapter/client support
+│   └── common/        # ids, time helpers, EventBus, CancellationToken
+├── platform/
+│   ├── host/          # CubeLocalApp, PlatformServices, PlatformRuntime, health
+│   ├── assembly/      # manifest-driven plugin/table runtime assembly
+│   ├── command/       # transport-neutral session command contracts
+│   ├── event/         # live session event stream contracts
+│   ├── agency/        # tenant container and member projections
+│   ├── channel/       # project/room container and session definitions
+│   ├── session/       # durable transcript/session container
+│   ├── notification/  # central durable human inbox
+│   ├── agent/         # default Agent worker implementation
+│   ├── plugin/        # plugin SPI, discovery, resolver, assembly, registry
+│   ├── workspace/     # local file workspace layout
+│   └── database/      # SQLModel/SQLite platform persistence
+├── cluster/           # distributed Gateway/Worker runtime coordination
+└── plugins/
+    ├── tools/         # official filesystem/chat/background tools
+    ├── hooks/         # official concrete hooks
+    ├── channels/
+    │   ├── chat/      # dm and group_chat channel types
+    │   └── project/   # project channel type and project query service
+    ├── sessions/
+    │   ├── chat/      # chat session capability
+    │   └── task/      # multi-phase task and workflow capability
+    └── subagent/      # complete sub-agent capability and tool-owned session
+
+apps/
+├── cli/               # official cube-cli terminal application
+└── playground/        # official full-stack reference app
+    ├── backend/       # project-owned FastAPI/auth/realtime composition
+    └── frontend/      # Next.js playground UI
+```
+
+## Architecture
+
+`cube.core` is the agent harness kernel. It has no database, session, channel,
+web framework, CLI, agency, user, plugin loading, or provider-SDK dependency.
+Importing `cube`, `cube.core`, `cube.core.llm`, or
+`cube.platform.plugin.PluginSpec` does
+not load optional adapters such as LiteLLM, FastAPI, SQLModel, MCP, or Typer.
+
+`cube.platform` assembles the harness into a durable local application. It does
+not own a global account table, credentials, passwords, or authentication.
+Human identity inside Cube is an agency-scoped member projection stored with
+the agency; embedding applications own accounts and map authenticated users to
+those projections.
+Long-lived, human-editable configuration lives in file workspaces under
+`<root_dir>/`. Runtime transcript, run state, task state, background tool
+state, metrics, and small app records live in SQLite.
+
+`cube.platform.plugin` owns the plugin SPI, discovery, selection, dependency
+resolution, transactional registration, and frozen capability registry.
+`cube.plugins` contains Cube's official implementations. Official and user
+plugins use the same `PluginSpec` model and `cube.plugins` entry-point group to
+contribute tools, hooks, hook events, session kinds, channel types, and the
+SubAgent provider. Runtime table registration remains a separate
+`tables.toml` / `TableSpec` path.
+Session-specific message and event types are declared by the session class.
+
+Loading and runtime ownership follow parallel boundaries:
+
+```text
+PluginSpec -> PluginManager -> PluginRegistry
+TableSpec  -> TableManager  -> TableRegistry
+```
+
+The plugin and table managers load declarations independently.
+`RuntimeAssembly` validates and freezes both registries, `PlatformServices`
+owns that immutable assembly, and `PlatformRuntime` consumes the durable
+service root rather than loading capabilities itself.
+
+`apps/cli` and project backends such as `apps/playground/backend` are
+application-owned compositions. They use public `cube.platform` composition
+helpers, while each application owns the default
+`plugins.toml` and `tables.toml` it writes.
+
+`cube.cluster` is the optional distributed runtime layer. Backend applications
+compose `PlatformServices` with `ClusterGateway` for command dispatch and live
+event subscription; worker processes run `ClusterWorker`, which owns
+`PlatformRuntime` and executes sessions. Distributed mode uses MySQL for Cube
+durable data, Redis for coordination, and a shared POSIX `root_dir` such as
+NAS. It does not provide a `CubeApp` facade or a local fallback.
+
+## Plugin Development
+
+External plugins expose a `PluginSpec` through the `cube.plugins` entry point
+group:
+
+```python
+from cube.platform.plugin import PluginSpec
+
+
+def register(ctx):
+    ctx.tools("finance_controls", my_tool)
+
+
+plugin = PluginSpec(
+    name="my.company.finance",
+    version="0.1.0",
+    requires_tables=("my.company.finance",),
+    register=register,
+)
+```
+
+```toml
+[project.entry-points."cube.plugins"]
+"my.company.finance" = "my_company_finance.plugin:plugin"
+```
+
+Plugins with persistence export an independent `TableSpec` and list its logical
+name in `requires_tables`. The host must still enable the table module in
+`tables.toml`; runtime composition reports a missing requirement before database
+initialization and never auto-loads plugin tables.
+
+Plugin and table loading is manifest-driven. Run the owning host's initializer
+(`cube init` for the CLI or `playground-backend init` for the Playground), or
+write `plugins.toml` / `tables.toml` explicitly before composing the runtime.
+
+`SessionContribution.required_tools` and `required_hooks` are session kind
+invariants. They describe capabilities the kind needs to run and are separate
+from `[assembly].default_tools`, which are optional agent tools filtered by
+agent tool-use policy. Default and required hook groups remain distinct during
+capability-name assembly, then runtime materialization combines their handlers
+into one prepared `HookRuntime`; sessions and agents consume that runtime rather
+than assembling hook extension registries themselves.
+
+`cube.core` exposes a small stable convenience API. Import provider-specific
+clients and lower-level runtime events from their package-local modules, for
+example `cube.core.llm.LiteLLMClient` or `cube.core.runtime.AgentStartEvent`.
+
+## Development
+
+For the fastest full-stack distributed Playground loop on macOS, install `uv`
+and Node.js 20.11 or newer, place the supplied deployment environment at the
+repository-root `.env`, then run:
+
+```bash
+make doctor
+make local-start
+make local-status
+make local-logs
+# Open http://localhost:3000
+make local-restart
+make local-shutdown
+```
+
+`local-start` runs separate ClusterWorker and distributed Playground backend
+processes plus the Next.js development server. It installs the pinned local SRT
+and ripgrep packages inside the repository, preserves existing runtime
+manifests, initializes/validates the MySQL schema, and waits for worker and HTTP
+readiness. Use `ENV_FILE=config/alice.env` for a non-default environment file.
+See [`deploy/README.md`](deploy/README.md) for prerequisites, per-developer
+cluster isolation, troubleshooting, Docker image validation, and Make variable
+overrides.
+
+Package and test development commands:
+
+```bash
+uv sync --all-packages --all-extras --dev
+uv run --all-extras pytest tests -q
+uv run --package cube-cli pytest apps/cli/tests -q
+uv run --package cube-playground-backend pytest apps/playground/backend/tests -q
+uv run --all-extras python -m compileall cube tests
+uv run --package cube-cli cube --help
+uv build --package cube
+uv build --package cube-cli
+npm --prefix apps/playground/frontend run typecheck
+npm --prefix apps/playground/frontend run build
+```
+
+Core boundary check:
+
+```bash
+rg -n "^\s*(from|import) cube\.(platform|plugins)" cube/core --glob '*.py'
+```
+
+See also:
+
+- `docs/README.md`
+- `docs/api-stability.md`
+- `docs/embedding.md`
+- `docs/cluster-runtime.md`
+- `cube/core/README.md`
+- `cube/platform/README.md`
+- `cube/plugins/README.md`
+- `apps/cli/README.md`
+- `apps/playground/README.md`
+- `deploy/README.md`