ariana-dot-dev/kimi-box-plugin/box-sdk-python

Box Python SDK

Package: ascii-box-sdk (PyPI). For raw HTTP see the box-api skill; for shell integration the box-cli skill.

Configure

import os
from ascii_box_sdk import ApiClient, Configuration
from ascii_box_sdk.api.box_api import BoxApi
config = Configuration(
    host=os.getenv("BOX_BASE_URL", "https://ascii.dev/api/box/v1"),
    access_token=os.environ["BOX_API_KEY"],
)
with ApiClient(config) as client:
    box = BoxApi(client)

Request models live under ascii_box_sdk.models (snake_case attributes; JSON uses the API's camelCase).

Create → prompt → events → stop

from ascii_box_sdk import wait_until_ready, wait_for_prompt
from ascii_box_sdk.models.create_box_request import CreateBoxRequest
from ascii_box_sdk.models.prompt_request import PromptRequest
box_id = None
with ApiClient(config) as client:
    box = BoxApi(client)
    try:
        created = box.create(CreateBoxRequest(ttl_seconds=1800))
        box_id = created.box.id
        wait_until_ready(box, box_id)   # always wait before commands/prompts
        queued = box.prompt(box_id, PromptRequest(
            provider="codex",
            prompt="Inspect the repo and summarize the test command.",
        ))
        run = wait_for_prompt(box, box_id, queued.prompt_id)
        events = box.events(box_id, limit=50, type="prompt,response,git_checkpoint")
    finally:
        if box_id:
            box.stop(box_id)

Create options: ttl_seconds (None = no auto-stop), env (per-box vars, ≤100 / 64 KB), no_env=True (withhold all account secrets — required when the box belongs to one of your users; a fork of a no-env box is always no-env).

Methods (all on BoxApi, snake_case)

Account: me(), limits(), repos(sync, q, ...), select_repo(RepoSelectionRequest), api_keys(), secrets(), update_secrets(SecretsUpdateRequest) (full replacement — send everything that should remain). Lifecycle: boxes(state, limit, cursor), create(CreateBoxRequest), get(box_id), update(box_id, UpdateBoxRequest) (name, ttl_seconds, subdomain), stop(box_id), resume(box_id, ResumeRequest) (no_env), fork(box_id, ForkRequest) (env, no_env), remove(box_id). Work & access: prompt(box_id, PromptRequest), prompt_run_status(box_id, prompt_id), events(box_id, limit, cursor, type), read_file(box_id, path, encoding="utf8"), write_file(box_id, FileWriteRequest), command(box_id, CommandRequest) (command, cwd, timeout_seconds — also runs in-box tools like host/lux), artifact(box_id, path) → bytes, interrupt(box_id), desktop(box_id, vnc, theme, request_body) (VNC ungated: request_body={"publicAccess": True}; if provisioning true, poll again), ssh_key(box_id, SshKeyRequest). Snapshots: list_snapshots(), list_box_snapshots(box_id), get_latest_box_snapshot(box_id), get_snapshot_tree(snapshot_id), get_snapshot_file(snapshot_id, path), get_snapshot_download(snapshot_id) — snapshot reads work while the box is stopped.

Waiters & helpers

from ascii_box_sdk import (
    wait_until_ready, wait_until_idle, wait_for_desktop, wait_for_prompt,
    wait_for_prompt_done, stop_and_remove, read_text, write_text, exec_command,
)

Use wait_for_prompt/wait_for_prompt_done for completion — do not infer it from box.state plus event polling.

Streaming responses & tool calls

from ascii_box_sdk import stream_prompt
from ascii_box_sdk.models.prompt_request import PromptRequest
for event in stream_prompt(box, box_id, PromptRequest(provider="codex", prompt="Run pwd and ls, then summarize.")):
    if event.type != "response":
        continue
    data = event.data
    if isinstance(data, dict):
        if data.get("tools"):
            print("tools", data["tools"])
        if data.get("content"):
            print(data["content"], end="")

stream_events(box, box_id, type="prompt,response,git_checkpoint") gives a dashboard-style feed. Both long-poll the events cursor API — no SSE/WebSocket needed. Streaming partials set data.is_streaming.

Errors

Methods raise ApiException on non-2xx:

from ascii_box_sdk.exceptions import ApiException
try:
    box.get("bx_missing")
except ApiException as exc:
    print(exc.status, exc.reason, exc.body)   # body is the structured error envelope

Redact API keys, secrets, and desktop_url values from logs. Prompting without configured provider credentials → error code provider_not_configured.

Docs: https://docs.ascii.dev/box/sdks/python