lace-app-sdk

The lace-app-sdk

Apps import lace_app_sdk. Every public contract re-exports the actual platform code, so updates to the platform flow through without copying.

How it stays current

The SDK does not vendor the agent runtime, tools, persistence, routes, or pipelines. Every symbol re-exports the real lace.* implementation and is identical at runtime. The builder and the sidecar resolve the same symbol to the same code.

Do not import lace.apps.* or lace.agent.* directly. That internal surface can change without notice. lace_app_sdk is the stable boundary with its own versioning. A breaking change to a published symbol requires a major version bump and a deprecation window.

Installation options

Install	Depends on	What works
`pip install lace-app-sdk`	`pydantic>=2` only	Every `_contracts.*` type, the `lace-app` CLI (`--help`, `auth`, `create`, `clone`, `open`/`logs`/`status`/`releases`/`secrets`), and pure facades (`manifest`, `data` contracts, `tools` registry). No `lace` required — this is the distributable wheel built from `src/lace_app_sdk/pyproject.toml`.
`pip install lace-app-sdk[runtime]`	adds `lace` monorepo	+ `lace-app dev` (migration-apply), `lace-app test` proof harness, and any symbol that genuinely requires the runtime (`AppDataService`, agent/pipeline engines, blob store).

pythonhow the lazy binding works

import lace_app_sdk

print(lace_app_sdk.__version__)              # always works (no lace.*)
import lace_app_sdk.manifest               # always works (_contracts)
import lace_app_sdk.agents                 # always works (module import)
lace_app_sdk.agents.AgentDefinition  # touches runtime → ImportError with hint if lace.* missing

Each runtime-coupled facade (agents, data.AppDataService, pipelines, routes, etc.) resolves its lace.* symbol on first attribute access via _lazy_runtime_getattr / PEP-562 __getattr__. If lace is not installed, the error says install with pip install lace-app-sdk[runtime] or run inside the LACE monorepo — not a bare ModuleNotFoundError. The top-level import lace_app_sdk never triggers a lace.* import.

Module map

Module	What it re-exports	Needs runtime?
`lace_app_sdk.manifest`	`LaceAppManifest`, `AppRuntimeUiDeclaration`, `write_app_manifest`	No — pure `_contracts.manifest`
`lace_app_sdk.data`	`AppDataCollectionSchema`, `AppDataService`, `put_blob/get_blob`, `BlobStore`	Contracts: no. Service/blob: yes
`lace_app_sdk.tools`	`@tool`, `AppToolDescriptor`, `AppToolRegistry`	No — sidecar-local registry
`lace_app_sdk.agents`	`AgentDefinition`, `AppAgentProvider`, capabilities, `LoopGuardConfig`, `HookRegistry`, `GuardrailRegistry`	Yes — agent runtime
`lace_app_sdk.routes`	`AppRouteProvider`, `AppRouteContext`	Yes — FastAPI-coupled
`lace_app_sdk.pipelines`	`AppPipelineProvider`	Yes — orchestration
`lace_app_sdk.skills`	`AgentSkill`	Yes
`lace_app_sdk.memory`	`register_axis_type`, `register_formation_hook`	Yes
`lace_app_sdk.policy`	`AppPolicyProvider`	Yes
`lace_app_sdk.connectors`	Connector action/trigger contracts	Yes
`lace_app_sdk.migrations`	App collection evolution	Yes (platform lifecycle)
`lace_app_sdk.ui`	`AppUiDeclaration`	No — declaration only
`lace_app_sdk.testing`	Proof harness entrypoint	Yes
`lace_app_sdk.blob` / `cache` / `secrets` / `jobs`	Blob helpers, cache, `get_secret`, job handlers	Mixed — see each module's docstring

Versioning

Package version: lace_app_sdk.__version__ (today 0.1.0.dev0).
Compatible core range: lace_app_sdk.__lace_core_requires__ == ">=0,<1". Enforced lazily at first runtime touch via _compat.check_core_compatibility().
Top-level lifted symbols — LaceAppManifest, AppDataCollectionSchema, tool, AgentDefinition, get_secret, … — are available as lace_app_sdk.<symbol> for convenience.

The `_contracts` layer

lace_app_sdk/_contracts/ holds the canonical pure-Pydantic definitions for manifest, data, and routes with zero lace.* imports. lace.apps.manifest is a thin re-export shim over this layer so from lace.apps.manifest import LaceAppManifest keeps working. This is what makes the standalone wheel possible.

pythonimports that never fork

from lace_app_sdk.manifest import LaceAppManifest   # actually lace_app_sdk._contracts.manifest.LaceAppManifest
from lace_app_sdk.data import AppDataCollectionSchema          # pure-pydantic, no lace.*
from lace_app_sdk.agents import AgentDefinition                # lazy → lace.apps.agents when touched

# base install (pip install lace-app-sdk) → first two imports succeed, third defers
# runtime install (pip install lace-app-sdk[runtime]) → third resolves to live core code

The CLI is part of the SDK

The lace-app entry point ships with the SDK wheel ([project.scripts] in pyproject.toml). It is what you use to create, clone/dev, test, and publish apps. Full flag reference at CLI reference.

Next: manifest reference → data collections → full module reference.