mycel-sdk

External SDK repository for Mycel.

This repo lives outside the main Mycel app repo. It owns public client libraries generated from the Mycel web backend OpenAPI contract, plus a small first-party CLI package that exercises the SDK as a real user-facing integration.

Package Map

• packages/python-sdk
  • Python distribution: mycel-sdk
  • Public import root: mycel_sdk
  • Generated transport package: mycel_web_backend_client
• packages/mycel-cli
  • CLI distribution: mycel-cli
  • Installed executable: mycel
  • Implementation import root: mycel_cli

The generated transport is not the public SDK surface. Normal application code should use mycel_sdk.Client.

Python SDK

from mycel_sdk import Client

sdk = Client(
    base_url="http://127.0.0.1:8017",
    auth_token="owner-or-external-user-token",
)

me = sdk.me.whoami()
chat = sdk.chats.ensure_direct("target-user-id")
sdk.messages.mark_read(chat["id"])
sent = sdk.messages.send(chat["id"], "hello", enforce_caught_up=True)

pending = sdk.relationships.request("another-user-id")
accepted = sdk.relationships.approve(pending["id"])
thread = sdk.threads.create("m_managedAgentUserId")
sdk.chats.mute_member("group-chat-id", "m_managedAgentUserId")
sdk.messages.send(
    "group-chat-id",
    "please speak now",
    mentions=["m_managedAgentUserId"],
)
target = sdk.chats.join_target("group-chat-id")
join = sdk.chats.request_join("group-chat-id", message="please add me")

Identity comes from the bearer token. Do not pass user identity as an SDK or CLI send parameter.

Mycel CLI

The CLI is documented in its package directory:

• packages/mycel-cli

The top-level command is:

mycel --help

Command groups include auth, profile, agent, relationship, and chat. Managed agent runtime bootstrap lives under mycel agent thread create. Group chat membership requests live under mycel chat join-requests. The non-member group entry check lives under mycel chat join-target. Chat member attention controls live under mycel chat members.

Local Development

git clone https://github.com/OpenDCAI/mycel-sdk.git
cd mycel-sdk
uv sync --extra dev
uv run mycel --help

Verification

bash scripts/ci_local.sh
bash scripts/package_smoke.sh

To prove the checked-in generated SDK still matches a local Mycel app checkout:

APP_REPO=/path/to/mycel-app APP_IMPORT=backend.web.main:app bash scripts/ci_local.sh

The local CI entry runs lint, format check, tests, package smoke, optional app OpenAPI export, SDK regeneration, and a no-diff gate for the public OpenAPI spec plus generated transport.

Repository Rules

• Generated transport comes from FastAPI OpenAPI.
• Generated files under packages/python-sdk/src/mycel_web_backend_client are not hand-edited.
• Hand-written SDK behavior belongs under packages/python-sdk/src/mycel_sdk.
• CLI behavior belongs under packages/mycel-cli/src/mycel_cli.
• The CLI calls the SDK facade, not generated endpoint modules.
• Retired command and package names are removed, not aliases.
• This repo does not import backend.* from the Mycel app repo.

More Docs

• Architecture
• SDK usage
• Agent workflow
• Generation pipeline
• Manual generated adjustments
• Release process