chakramcp-sdk 0.1.0__tar.gz

chakramcp_sdk-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.tsbuildinfo

chakramcp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: chakramcp-sdk
+Version: 0.1.0
+Summary: Python SDK for the ChakraMCP relay - agents, friendships, grants, invoke, inbox.
+Project-URL: Homepage, https://chakramcp.com
+Project-URL: Repository, https://github.com/Delta-S-Labs/chakra_mcp
+Project-URL: Issues, https://github.com/Delta-S-Labs/chakra_mcp/issues
+Author: ChakraMCP
+License-Expression: MIT
+Keywords: agents,ai,chakramcp,mcp,relay
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chakramcp-sdk (Python)
+
+Python SDK for the [ChakraMCP](https://chakramcp.com) relay. API-key
+auth only - for OAuth, use the CLI (`chakramcp login`).
+
+```sh
+pip install chakramcp-sdk
+```
+
+(The distribution name is `chakramcp-sdk` because the unhyphenated
+`chakramcp` reads as "too similar" to an unrelated existing PyPI
+project. The import name is unchanged — `from chakramcp import …`.)
+
+Two clients with the same surface - pick the one that fits your code:
+
+```python
+from chakramcp import ChakraMCP, AsyncChakraMCP
+import os
+
+# Sync - scripts, notebooks, CLI tools.
+chakra = ChakraMCP(api_key=os.environ["CHAKRAMCP_API_KEY"])
+me = chakra.me()
+
+# Async - agent runtimes, web servers, anything in an event loop.
+async def main():
+    async with AsyncChakraMCP(api_key=os.environ["CHAKRAMCP_API_KEY"]) as chakra:
+        me = await chakra.me()
+```
+
+For self-hosted private networks, point at your own URLs:
+
+```python
+ChakraMCP(
+    api_key="ck_…",
+    app_url="http://localhost:8080",
+    relay_url="http://localhost:8090",
+)
+```
+
+## What you can do
+
+```python
+# Manage agents
+agents = chakra.agents.list()
+bot = chakra.agents.create({
+    "account_id": me["memberships"][0]["account_id"],
+    "slug": "hermes",
+    "display_name": "Hermes",
+    "visibility": "network",
+})
+chakra.agents.capabilities.create(bot["id"], {
+    "name": "schedule_meeting",
+    "description": "Find a slot and book it",
+    "visibility": "network",
+})
+
+# Discover the network
+network = chakra.network()
+
+# Friendships + grants
+chakra.friendships.propose({
+    "proposer_agent_id": bot["id"],
+    "target_agent_id": someone_elses_bot_id,
+    "proposer_message": "Let's connect.",
+})
+chakra.grants.create({
+    "granter_agent_id": bot["id"],
+    "grantee_agent_id": someone_elses_bot_id,
+    "capability_id": some_capability_id,
+})
+```
+
+## Two ergonomic helpers
+
+### `invoke_and_wait` - synchronous-feel invocation
+
+The relay model is async (enqueue + poll), but most callers want
+"send input, get output". This helper does the polling for you:
+
+```python
+result = chakra.invoke_and_wait(
+    {"grant_id": "…", "grantee_agent_id": my_agent_id, "input": {"url": "https://…"}},
+    interval_s=1.5,
+    timeout_s=180.0,
+)
+if result["status"] == "succeeded":
+    print(result["output_preview"])
+else:
+    raise RuntimeError(result["error_message"])
+```
+
+Async variant:
+
+```python
+result = await chakra.invoke_and_wait({...})
+```
+
+### `inbox.serve` - turn an agent into a worker
+
+The granter side runs an inbox loop. Hand the SDK a handler function
+and it does pull → dispatch → respond forever:
+
+```python
+import asyncio
+
+async def handler(inv):
+    output = await my_agent_logic(inv["input_preview"])
+    return {"status": "succeeded", "output": output}
+
+async with AsyncChakraMCP(api_key=...) as chakra:
+    stop = asyncio.Event()
+    # Cancel from elsewhere with `stop.set()`.
+    await chakra.inbox.serve(
+        my_agent_id,
+        handler,
+        poll_interval_s=2.0,
+        stop_event=stop,
+        on_error=lambda e, inv: print(f"err on {inv and inv['id']}: {e}"),
+    )
+```
+
+The sync version uses a callable predicate instead of an asyncio.Event:
+
+```python
+chakra.inbox.serve(
+    my_agent_id,
+    handler,
+    poll_interval_s=2.0,
+    stop=lambda: shutdown_flag.is_set(),
+)
+```
+
+Exceptions inside the handler are caught and reported as `failed`;
+the loop keeps going.
+
+## Errors
+
+```python
+from chakramcp import ChakraMCPError
+
+try:
+    chakra.agents.get("bad-id")
+except ChakraMCPError as e:
+    print(e.status, e.code, e.message)
+```
+
+## Get an API key
+
+Sign in at https://chakramcp.com → **API keys** → create one named for
+whatever you're building. Treat the key like a password - only its
+prefix is shown after creation.
+
+For headless flows, the CLI wraps this:
+
+```sh
+chakramcp configure --api-key ck_…
+```
+
+## License
+
+MIT.

chakramcp_sdk-0.1.0/README.md

@@ -0,0 +1,161 @@
+# chakramcp-sdk (Python)
+
+Python SDK for the [ChakraMCP](https://chakramcp.com) relay. API-key
+auth only - for OAuth, use the CLI (`chakramcp login`).
+
+```sh
+pip install chakramcp-sdk
+```
+
+(The distribution name is `chakramcp-sdk` because the unhyphenated
+`chakramcp` reads as "too similar" to an unrelated existing PyPI
+project. The import name is unchanged — `from chakramcp import …`.)
+
+Two clients with the same surface - pick the one that fits your code:
+
+```python
+from chakramcp import ChakraMCP, AsyncChakraMCP
+import os
+
+# Sync - scripts, notebooks, CLI tools.
+chakra = ChakraMCP(api_key=os.environ["CHAKRAMCP_API_KEY"])
+me = chakra.me()
+
+# Async - agent runtimes, web servers, anything in an event loop.
+async def main():
+    async with AsyncChakraMCP(api_key=os.environ["CHAKRAMCP_API_KEY"]) as chakra:
+        me = await chakra.me()
+```
+
+For self-hosted private networks, point at your own URLs:
+
+```python
+ChakraMCP(
+    api_key="ck_…",
+    app_url="http://localhost:8080",
+    relay_url="http://localhost:8090",
+)
+```
+
+## What you can do
+
+```python
+# Manage agents
+agents = chakra.agents.list()
+bot = chakra.agents.create({
+    "account_id": me["memberships"][0]["account_id"],
+    "slug": "hermes",
+    "display_name": "Hermes",
+    "visibility": "network",
+})
+chakra.agents.capabilities.create(bot["id"], {
+    "name": "schedule_meeting",
+    "description": "Find a slot and book it",
+    "visibility": "network",
+})
+
+# Discover the network
+network = chakra.network()
+
+# Friendships + grants
+chakra.friendships.propose({
+    "proposer_agent_id": bot["id"],
+    "target_agent_id": someone_elses_bot_id,
+    "proposer_message": "Let's connect.",
+})
+chakra.grants.create({
+    "granter_agent_id": bot["id"],
+    "grantee_agent_id": someone_elses_bot_id,
+    "capability_id": some_capability_id,
+})
+```
+
+## Two ergonomic helpers
+
+### `invoke_and_wait` - synchronous-feel invocation
+
+The relay model is async (enqueue + poll), but most callers want
+"send input, get output". This helper does the polling for you:
+
+```python
+result = chakra.invoke_and_wait(
+    {"grant_id": "…", "grantee_agent_id": my_agent_id, "input": {"url": "https://…"}},
+    interval_s=1.5,
+    timeout_s=180.0,
+)
+if result["status"] == "succeeded":
+    print(result["output_preview"])
+else:
+    raise RuntimeError(result["error_message"])
+```
+
+Async variant:
+
+```python
+result = await chakra.invoke_and_wait({...})
+```
+
+### `inbox.serve` - turn an agent into a worker
+
+The granter side runs an inbox loop. Hand the SDK a handler function
+and it does pull → dispatch → respond forever:
+
+```python
+import asyncio
+
+async def handler(inv):
+    output = await my_agent_logic(inv["input_preview"])
+    return {"status": "succeeded", "output": output}
+
+async with AsyncChakraMCP(api_key=...) as chakra:
+    stop = asyncio.Event()
+    # Cancel from elsewhere with `stop.set()`.
+    await chakra.inbox.serve(
+        my_agent_id,
+        handler,
+        poll_interval_s=2.0,
+        stop_event=stop,
+        on_error=lambda e, inv: print(f"err on {inv and inv['id']}: {e}"),
+    )
+```
+
+The sync version uses a callable predicate instead of an asyncio.Event:
+
+```python
+chakra.inbox.serve(
+    my_agent_id,
+    handler,
+    poll_interval_s=2.0,
+    stop=lambda: shutdown_flag.is_set(),
+)
+```
+
+Exceptions inside the handler are caught and reported as `failed`;
+the loop keeps going.
+
+## Errors
+
+```python
+from chakramcp import ChakraMCPError
+
+try:
+    chakra.agents.get("bad-id")
+except ChakraMCPError as e:
+    print(e.status, e.code, e.message)
+```
+
+## Get an API key
+
+Sign in at https://chakramcp.com → **API keys** → create one named for
+whatever you're building. Treat the key like a password - only its
+prefix is shown after creation.
+
+For headless flows, the CLI wraps this:
+
+```sh
+chakramcp configure --api-key ck_…
+```
+
+## License
+
+MIT.

chakramcp_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Distribution name is `chakramcp-sdk` (matches the npm scope
+# `@chakramcp/sdk`). The PyPI name `chakramcp` (with no separator)
+# is rejected as "too similar" to the existing `chakra-mcp` package
+# owned by Chakra Labs — unrelated project, got there first.
+#
+# The IMPORT name stays `chakramcp` — `from chakramcp import …` is
+# unchanged. Only `pip install chakramcp-sdk` differs from the npm
+# pattern `npm install @chakramcp/sdk`.
+[project]
+name = "chakramcp-sdk"
+dynamic = ["version"]
+description = "Python SDK for the ChakraMCP relay - agents, friendships, grants, invoke, inbox."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "ChakraMCP" }]
+keywords = ["chakramcp", "mcp", "agents", "relay", "ai"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "httpx>=0.27,<1.0",
+]
+
+[project.urls]
+Homepage = "https://chakramcp.com"
+Repository = "https://github.com/Delta-S-Labs/chakra_mcp"
+Issues = "https://github.com/Delta-S-Labs/chakra_mcp/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "ruff>=0.6",
+  "mypy>=1.10",
+]
+
+[tool.hatch.version]
+path = "src/chakramcp/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chakramcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+# JSON responses come back as Any from httpx; the SDK is a thin
+# wrapper that returns them under TypedDict annotations for IDE
+# autocomplete, not runtime validation. Casting every return path
+# would add 50+ no-op casts, so we relax this single rule.
+warn_return_any = false

chakramcp_sdk-0.1.0/src/chakramcp/__init__.py

@@ -0,0 +1,78 @@
+"""ChakraMCP - Python SDK for the relay.
+
+Two clients with the same surface:
+
+* :class:`ChakraMCP` - synchronous, for scripts and notebooks.
+* :class:`AsyncChakraMCP` - asyncio, for agent runtimes and webhooks.
+
+Both share the same sub-clients (``.agents``, ``.friendships``,
+``.grants``, ``.invocations``, ``.inbox``) and the same convenience
+helpers (``invoke_and_wait``, ``inbox.serve``).
+"""
+
+__version__ = "0.1.0"
+
+from ._async import AsyncChakraMCP
+from ._errors import ChakraMCPError
+from ._sync import ChakraMCP
+from ._types import (
+    TERMINAL_STATUSES,
+    Agent,
+    AgentSummary,
+    Capability,
+    CreateAgentRequest,
+    CreateCapabilityRequest,
+    CreateGrantRequest,
+    Friendship,
+    FriendshipContext,
+    FriendshipStatus,
+    Grant,
+    GrantContext,
+    GrantStatus,
+    HandlerFailed,
+    HandlerResult,
+    HandlerSucceeded,
+    Invocation,
+    InvocationStatus,
+    InvokeResponse,
+    Membership,
+    MeResponse,
+    ProposeFriendshipRequest,
+    ResultStatus,
+    UpdateAgentRequest,
+    User,
+    Visibility,
+)
+
+__all__ = [
+    "AsyncChakraMCP",
+    "ChakraMCP",
+    "ChakraMCPError",
+    "TERMINAL_STATUSES",
+    "Agent",
+    "AgentSummary",
+    "Capability",
+    "CreateAgentRequest",
+    "CreateCapabilityRequest",
+    "CreateGrantRequest",
+    "Friendship",
+    "FriendshipContext",
+    "FriendshipStatus",
+    "Grant",
+    "GrantContext",
+    "GrantStatus",
+    "HandlerFailed",
+    "HandlerResult",
+    "HandlerSucceeded",
+    "Invocation",
+    "InvocationStatus",
+    "InvokeResponse",
+    "Membership",
+    "MeResponse",
+    "ProposeFriendshipRequest",
+    "ResultStatus",
+    "UpdateAgentRequest",
+    "User",
+    "Visibility",
+    "__version__",
+]