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`
