https://github.com/opendcai/mycel-sdk
https://github.com/opendcai/mycel-sdk
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/opendcai/mycel-sdk
- Owner: OpenDCAI
- License: mit
- Created: 2026-04-23T16:01:34.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T12:11:19.000Z (about 2 months ago)
- Last Synced: 2026-04-25T12:25:15.816Z (about 2 months ago)
- Language: Python
- Size: 351 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# mycel-sdk
External SDK repository for Mycel.
This repo owns public client libraries generated from the Mycel web backend
OpenAPI contract, plus the first-party `cel` CLI. The CLI exists to dogfood the
SDK through real user-facing communication loops.
[](https://github.com/OpenDCAI/mycel-sdk/actions/workflows/ci.yml)
## 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: `cel`
- Implementation import root: `mycel_cli`
The generated transport is not the public SDK surface. Application code should
use `mycel_sdk.Client`.
## Python SDK
```python
from mycel_sdk import Client
sdk = Client(
base_url="http://127.0.0.1:8017",
auth_token="owner-or-external-agent-token",
)
me = sdk.me.whoami()
chat = sdk.chats.ensure_direct("target-user-id")
sdk.messages.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"])
notifications = sdk.notifications.drain()
```
Identity comes from the bearer token. Do not pass sender identity as an SDK or
CLI parameter.
## CLI
The CLI package is documented in [packages/mycel-cli](packages/mycel-cli).
PyPI is the intended public install path. Tag releases publish GitHub release
assets and then publish the same built distributions to PyPI with the
repository secret `PYPI_API_TOKEN`.
```bash
cel --help
```
Public command groups are intentionally small:
- `login` and `logout` manage the human owner login.
- `agent` manages local external agent identities owned by that human.
- `contact` wraps user-level relationship requests.
- `send-message` writes durable Mycel messages to explicit chat/user targets.
- `read-message` reads durable Mycel messages and owns read-cursor behavior.
- `group` manages local multi-agent orchestration groups.
- `self` manages the local background service and inbox inspection.
- `codex` and `claude` launch native agent runtimes with Mycel identity env.
Local background service lifecycle is scoped under `cel self start/status/stop/reset`;
group defaults are scoped under `cel group config ...`. Provider hook plumbing
stays internal; there is no public top-level `cel hooks` command.
Local identity is stored in global `~/.mycel` and injected through
`MYCEL_LOCAL_ID`, `MYCEL_HOME`, and `MYCEL_PROVIDER` when an agent is launched.
Use `cel codex --mycel-status` or `cel claude --mycel-status` for a read-only
local check of identity, hook state, native provider availability, and provider
capabilities.
## Local Development
```bash
git clone https://github.com/OpenDCAI/mycel-sdk.git
cd mycel-sdk
uv sync --extra dev
uv run cel --help
```
## Verification
```bash
bash scripts/ci_local.sh
bash scripts/package_smoke.sh
```
To prove the checked-in generated SDK still matches a local Mycel app checkout:
```bash
APP_REPO=/path/to/mycel-app APP_IMPORT=backend.web.main:app bash scripts/ci_local.sh
```
## 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 names are removed, not aliased.
- This repo does not import `backend.*` from the Mycel app repo.
## More Docs
- [Architecture](docs/architecture.md)
- [SDK usage](docs/sdk.md)
- [Generation pipeline](docs/generation.md)
- [Manual generated adjustments](docs/generated-adjustments.md)
- [Keep divergence ledger](docs/keep-divergence.md)
- [Release process](docs/releasing.md)