Metadata-Version: 2.4
Name: im-sdk
Version: 1.1.0
Summary: CIU SDK — HTTP client and wire models for the Gateway
License: Apache-2.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: structlog>=25.5.0
Requires-Dist: uuid-utils>=0.9
Dynamic: license-file

# apps/core-sdk — `im-sdk`

Python SDK that agents import to talk to the **ciu-core-gateway** over HTTP. PyPI package `im-sdk`; import as `im_sdk`.

This folder is a **uv workspace member** declared at repo-root [pyproject.toml](../../pyproject.toml). Run all commands from the repo root, not from here.

## Layout

```
apps/core-sdk/
├── pyproject.toml          # name: im-sdk; depends on pydantic, httpx, structlog, uuid-utils
├── im_sdk/                # Source package — wire models, transport, clients
├── tests/                  # pytest suite covering models, client, LLM, transport, tracing
└── examples/               # SDK usage demos: agent-template/ (minimal traced agent), test-providers/ (provider smoke test)
```

## Quick example

```python
import asyncio
from im_sdk import ImCore

async def main():
    core = ImCore.from_env()  # AGENT_ID / AGENT_SECRET / WORKSPACE_ID / CIU_CHECKER_URL
    async with core:           # authorizes; the Portal manifest gates every call
        result = await core.llm.call(
            messages=[{"role": "user", "content": "hello"}],
            alias="gpt-mini",  # an `llm` alias granted to the agent in the Portal
        )
        print(result.text)

asyncio.run(main())
```

The SDK opens a session against the **Checker** (port `8766`), which validates the manifest and forwards to the **Gateway** (port `8765`).

## Local dev (uv workspace)

This section is for **developing the SDK itself**. Authoring an *agent* is a
different workflow: the `im-cli` CLI owns packaging (`im-cli push` zips the project and
the installer runs `uv sync --frozen`), so an agent author only runs `uv lock`
after changing dependencies — see [`examples/agent-template/`](examples/agent-template/README.md).

From the **repo root**:

```bash
# Install + sync the whole Python workspace
uv sync --all-packages

# Run SDK tests
make core-sdk-test
# or:
uv run --package im-sdk pytest apps/core-sdk/tests

# Lint
uv run ruff check apps/core-sdk
```

## Releases

The SDK ships to the **GitLab project's own** PyPI registry on a tag matching **`sdk-v<MAJOR>.<MINOR>.<PATCH>`**. The `sdk-` prefix is load-bearing: [`.gitlab-ci.yml`](../../.gitlab-ci.yml) gates the whole pipeline on `$CI_COMMIT_TAG =~ /^sdk-v\d+\.\d+\.\d+$/`, so a bare `v1.2.3` tag opens no pipeline and publishes **nothing, silently**. Prereleases are refused — the pattern has no `-rc` branch.

The version must already read the same in all three core packages (`im-sdk`, `ciu-core-gateway`, `ciu-checker`) — `build_tag_package` asserts tag == `project.version` for each and fails the release otherwise. Bump them in the feature commit, then cut the annotated tag **from the merge target**:

```bash
git switch develop && git pull --ff-only
git tag -a sdk-v<X.Y.Z> -m "Release sdk-v<X.Y.Z>" && git push origin sdk-v<X.Y.Z>
```

Releasing is four steps and no script: bump `project.version` in all three pyprojects, run `make version-manifest` (the tag pipeline refuses a tag naming a version the tree does not carry, #337), merge that MR, then tag the merge commit `sdk-v<X.Y.Z>`.

## See also

- [apps/core-sdk/AGENTS.md](AGENTS.md) — dev commands + conventions
- [apps/core-sdk/docs/api-reference.md](docs/api-reference.md) — agent-developer API reference (all public symbols, signatures, examples)
- [apps/core-gateway/](../core-gateway/) — host service the SDK talks to
- [apps/core-checker/](../core-checker/) — manifest checker reverse proxy
- Root [CODEBASE.md](../../CODEBASE.md), [STACK.md](../../STACK.md) — monorepo overview
- [.cursor/rules/ciu-core.mdc](../../.cursor/rules/ciu-core.mdc), [.cursor/LESSONS-ciu-core.md](../../.cursor/LESSONS-ciu-core.md) — agent context + accumulated lessons
- `docs/ciu-core/` — specs (manifest design, security manifest, llm-connector, portal-api, portal-manifest)
