esoul 0.1.0__tar.gz

esoul-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/

esoul-0.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-17
+
+### Added
+- **`client.agents`** — SDK-driven agent_builder invocation. Primary
+  surface `agents.invoke(workspace_id, agent, input=..., images=...)`
+  where `agent` is a nodeId (uuid) or instanceName (case-insensitive).
+  Convenience layer `agents.invoke_pin(pinned_agent_id, ...)` for
+  cross-workspace pins on the caller's own account. Polling handle
+  with `wait(timeout, on_question, on_approval)` (exponential backoff
+  2s → 10s, callbacks dedup'd by questionId / summary). `agents.get`,
+  `agents.list`, `handle.cancel`.
+- **`client.questions`** — workspace HIL queue. Programs can ask
+  questions via `questions.ask(workspace_id, "...", default_on_timeout=)`
+  which blocks until a human answers via the workspace's header drawer.
+  Also `ask_async`, `wait_for_answer`, `list`, `get`, `answer`, `cancel`.
+- Async parity for both resources: `AsyncAgentsResource`,
+  `AsyncInvocationHandle`, `AsyncQuestionsResource`.
+- New typed dataclasses: `InvocationStatus`, `InvocationResult`,
+  `Question`, `Answer`.
+- New typed exceptions: `InvocationTimeout`, `InvocationError`,
+  `QuestionTimeout`, `QuestionAlreadyResolved`. Mapped from server
+  error codes `agent_not_found`, `agent_ambiguous`, `agent_invalid_type`,
+  `invocation_*`, `pinned_agent_*`, `question_*`.
+- Initial sync `Esoul` and async `AsyncEsoul` clients.
+- Credential auto-detection: explicit kwarg → `ESOUL_TOKEN` env →
+  `/var/run/esoul/token` (sandbox) → `~/.config/esoul/credentials` (PAT).
+- Low-level dispatch surface: `dispatch_event`, `dispatch_batch`,
+  `read_state`, `describe`, `refresh_token`.
+- Drive proxy resource: `drive.list_folder`, `drive.read_file`,
+  `drive.upload_file`.
+- Typed exception hierarchy mapped from server `error.code`:
+  `AuthError`, `WorkspaceAccessDenied`, `AppNotFoundError`,
+  `EventNotRegistered`, `IdempotencyConflict`, `RateLimitError`,
+  `DriveNotConnected`, `APIError`.
+- Auto-generated `Idempotency-Key` (UUID v4 per call), reused across
+  retries; caller can override via `idempotency_key=` kwarg.
+- Retry-on-5xx + network-error policy with exponential backoff + jitter.
+  4xx errors don't retry. 429 respects `Retry-After`.
+- Background token-refresh for sandbox JWTs (60s before expiry). PAT
+  tokens don't refresh.
+- `py.typed` marker for PEP 561 / mypy compatibility.
+
+### Not yet shipped
+- Per-app typed resources (`spreadsheet`, `notes`, etc.) — landing as
+  codegen pipeline ships, one app at a time.
+- Batch context manager (`with client.batch():`) for client-side id
+  pre-generation in multi-event flows.
+- Per-event return shapes (depends on server adding `returnShape` to
+  event definitions).

esoul-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ExternalSoul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

esoul-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: esoul
+Version: 0.1.0
+Summary: Python SDK for the ExternalSoul platform — programmatic workspace mutation, event-sourced, audit-logged.
+Project-URL: Homepage, https://github.com/vyomkeshj/esoul-python
+Project-URL: Documentation, https://externalsoul.com/sdk-docs/llm-reference.md
+Project-URL: Repository, https://github.com/vyomkeshj/esoul-python
+Project-URL: Changelog, https://github.com/vyomkeshj/esoul-python/blob/main/CHANGELOG.md
+Author-email: ExternalSoul <hey@vyomkeshj.com>
+License: MIT License
+        
+        Copyright (c) 2026 ExternalSoul
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: automation,esoul,event-sourcing,externalsoul,kinetic,workspace
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; 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'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# esoul — Python SDK for ExternalSoul
+
+`esoul` is the official Python SDK for the **ExternalSoul** platform. It lets
+scripts mutate workspace state from anywhere Python runs — inside the
+platform's E2B sandboxes, on a data scientist's laptop, in a Colab notebook,
+in CI, in a scheduled cron job.
+
+```bash
+pip install esoul
+```
+
+```python
+import esoul
+
+client = esoul.Esoul()                       # auto-detects credentials
+state = client.describe()                    # what workspaces + apps + events are available
+print(state.session.workspace_ids)
+
+# Low-level dispatch
+result = client.dispatch_event(
+    app_id="app_abc123",
+    event_name="spreadsheet_add_row",
+    event_data={"cells": {"name": "Alice", "email": "a@example.com"}},
+)
+print(result.event_id, result.sequence_num)
+```
+
+## Why an SDK?
+
+ExternalSoul workspaces are **event-sourced** — every state mutation is a
+typed event on a per-workspace timeline, scrubbable and forkable. The UI,
+agents, and now scripts all dispatch through the **same** reducers; events
+are the source of truth, audit logging is automatic.
+
+The SDK is the platform's universal binding for **scripted workspace
+operations**. Common use cases:
+
+- Bulk-import 1000 rows into a spreadsheet (one event, not 1000 LLM tool calls)
+- Run an OpenCV pipeline over Drive images and write masks back
+- Programmatic kanban / contacts load from a CSV
+- Notebook-as-workspace-builder
+- Any agent or human writing Python to mutate app state
+
+## Authentication
+
+`esoul.Esoul()` auto-detects credentials in this order:
+
+1. Explicit `token=` kwarg
+2. `ESOUL_TOKEN` environment variable
+3. `/var/run/esoul/token` (the file mode 0600 token written by every E2B
+   sandbox at boot — `Esoul()` inside a sandbox Just Works)
+4. `~/.config/esoul/credentials` (TOML file with a `[default]` section
+   containing `token = "esoul_pat_..."`)
+
+For off-platform use (laptop, CI), create a **Personal Access Token** in
+workspace settings → "Access Tokens", pick the workspaces it can mutate,
+copy the token (shown once), and either:
+
+```bash
+# Export inline:
+export ESOUL_TOKEN="esoul_pat_..."
+
+# Or write to ~/.config/esoul/credentials:
+mkdir -p ~/.config/esoul
+cat > ~/.config/esoul/credentials <<EOF
+[default]
+token = "esoul_pat_..."
+EOF
+chmod 600 ~/.config/esoul/credentials
+```
+
+## Workspace isolation
+
+A given credential is scoped to one or more specific workspaces. Cross-
+workspace dispatch is **structurally impossible** — not a permission check
+in your script, an architectural invariant of the server.
+
+## Idempotency
+
+Every write is automatically idempotent. The SDK generates a UUID per call
+and reuses it across retries; the server caches the response under
+`(session, key)` for 24h. Same key + same body → identical cached response,
+not a duplicate event. You can override the key for application-level retry
+control:
+
+```python
+client.dispatch_event(
+    app_id=...,
+    event_name=...,
+    event_data=...,
+    idempotency_key="my-task-2026-05-15",  # caller-controlled
+)
+```
+
+## Async client
+
+The async client mirrors the sync API exactly:
+
+```python
+import asyncio
+import esoul
+
+async def main():
+    async with esoul.AsyncEsoul() as client:
+        result = await client.dispatch_event(
+            app_id=..., event_name=..., event_data=...,
+        )
+
+asyncio.run(main())
+```
+
+## Typed errors
+
+Failures surface as Python exception classes mapped from the server's
+`error.code`. You can catch the kind you care about, and `EsoulError`
+catches everything:
+
+```python
+import esoul
+
+try:
+    client.dispatch_event(...)
+except esoul.WorkspaceAccessDenied as e:
+    print(f"This token cannot reach workspace {e.details['workspaceId']}")
+except esoul.IdempotencyConflict as e:
+    print("Same key was used with a different request body")
+except esoul.RateLimitError as e:
+    time.sleep(e.retry_after_seconds or 1)
+except esoul.AuthError:
+    print("Token expired or revoked — get a new one")
+except esoul.EsoulError as e:
+    print(f"{e.code}: {e.message}")
+```
+
+## Status
+
+**v0.1 — alpha.** Wire surface is stable; per-app typed resources are
+codegen'd and shipping incrementally. The low-level `dispatch_event` /
+`dispatch_batch` / `read_state` paths are production-ready.
+
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
+
+## License
+
+MIT.

esoul-0.1.0/README.md

@@ -0,0 +1,145 @@
+# esoul — Python SDK for ExternalSoul
+
+`esoul` is the official Python SDK for the **ExternalSoul** platform. It lets
+scripts mutate workspace state from anywhere Python runs — inside the
+platform's E2B sandboxes, on a data scientist's laptop, in a Colab notebook,
+in CI, in a scheduled cron job.
+
+```bash
+pip install esoul
+```
+
+```python
+import esoul
+
+client = esoul.Esoul()                       # auto-detects credentials
+state = client.describe()                    # what workspaces + apps + events are available
+print(state.session.workspace_ids)
+
+# Low-level dispatch
+result = client.dispatch_event(
+    app_id="app_abc123",
+    event_name="spreadsheet_add_row",
+    event_data={"cells": {"name": "Alice", "email": "a@example.com"}},
+)
+print(result.event_id, result.sequence_num)
+```
+
+## Why an SDK?
+
+ExternalSoul workspaces are **event-sourced** — every state mutation is a
+typed event on a per-workspace timeline, scrubbable and forkable. The UI,
+agents, and now scripts all dispatch through the **same** reducers; events
+are the source of truth, audit logging is automatic.
+
+The SDK is the platform's universal binding for **scripted workspace
+operations**. Common use cases:
+
+- Bulk-import 1000 rows into a spreadsheet (one event, not 1000 LLM tool calls)
+- Run an OpenCV pipeline over Drive images and write masks back
+- Programmatic kanban / contacts load from a CSV
+- Notebook-as-workspace-builder
+- Any agent or human writing Python to mutate app state
+
+## Authentication
+
+`esoul.Esoul()` auto-detects credentials in this order:
+
+1. Explicit `token=` kwarg
+2. `ESOUL_TOKEN` environment variable
+3. `/var/run/esoul/token` (the file mode 0600 token written by every E2B
+   sandbox at boot — `Esoul()` inside a sandbox Just Works)
+4. `~/.config/esoul/credentials` (TOML file with a `[default]` section
+   containing `token = "esoul_pat_..."`)
+
+For off-platform use (laptop, CI), create a **Personal Access Token** in
+workspace settings → "Access Tokens", pick the workspaces it can mutate,
+copy the token (shown once), and either:
+
+```bash
+# Export inline:
+export ESOUL_TOKEN="esoul_pat_..."
+
+# Or write to ~/.config/esoul/credentials:
+mkdir -p ~/.config/esoul
+cat > ~/.config/esoul/credentials <<EOF
+[default]
+token = "esoul_pat_..."
+EOF
+chmod 600 ~/.config/esoul/credentials
+```
+
+## Workspace isolation
+
+A given credential is scoped to one or more specific workspaces. Cross-
+workspace dispatch is **structurally impossible** — not a permission check
+in your script, an architectural invariant of the server.
+
+## Idempotency
+
+Every write is automatically idempotent. The SDK generates a UUID per call
+and reuses it across retries; the server caches the response under
+`(session, key)` for 24h. Same key + same body → identical cached response,
+not a duplicate event. You can override the key for application-level retry
+control:
+
+```python
+client.dispatch_event(
+    app_id=...,
+    event_name=...,
+    event_data=...,
+    idempotency_key="my-task-2026-05-15",  # caller-controlled
+)
+```
+
+## Async client
+
+The async client mirrors the sync API exactly:
+
+```python
+import asyncio
+import esoul
+
+async def main():
+    async with esoul.AsyncEsoul() as client:
+        result = await client.dispatch_event(
+            app_id=..., event_name=..., event_data=...,
+        )
+
+asyncio.run(main())
+```
+
+## Typed errors
+
+Failures surface as Python exception classes mapped from the server's
+`error.code`. You can catch the kind you care about, and `EsoulError`
+catches everything:
+
+```python
+import esoul
+
+try:
+    client.dispatch_event(...)
+except esoul.WorkspaceAccessDenied as e:
+    print(f"This token cannot reach workspace {e.details['workspaceId']}")
+except esoul.IdempotencyConflict as e:
+    print("Same key was used with a different request body")
+except esoul.RateLimitError as e:
+    time.sleep(e.retry_after_seconds or 1)
+except esoul.AuthError:
+    print("Token expired or revoked — get a new one")
+except esoul.EsoulError as e:
+    print(f"{e.code}: {e.message}")
+```
+
+## Status
+
+**v0.1 — alpha.** Wire surface is stable; per-app typed resources are
+codegen'd and shipping incrementally. The low-level `dispatch_event` /
+`dispatch_batch` / `read_state` paths are production-ready.
+
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
+
+## License
+
+MIT.

esoul-0.1.0/pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "esoul"
+dynamic = ["version"]
+description = "Python SDK for the ExternalSoul platform — programmatic workspace mutation, event-sourced, audit-logged."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+    { name = "ExternalSoul", email = "hey@vyomkeshj.com" },
+]
+keywords = ["externalsoul", "esoul", "kinetic", "workspace", "automation", "event-sourcing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    # httpx 0.27 added Timeout + connection-pool improvements we rely on;
+    # earlier versions work but we don't test against them.
+    "httpx>=0.27,<1.0",
+    # pydantic v2 for typed response models. v1 had a different validation
+    # API; the codegen pipeline targets v2 exclusively.
+    "pydantic>=2.0,<3.0",
+    # typing_extensions for TypeAlias / Self on Python 3.9-3.10.
+    "typing_extensions>=4.7; python_version<'3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/vyomkeshj/esoul-python"
+Documentation = "https://externalsoul.com/sdk-docs/llm-reference.md"
+Repository = "https://github.com/vyomkeshj/esoul-python"
+Changelog = "https://github.com/vyomkeshj/esoul-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.10",
+    "ruff>=0.6",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",  # httpx mocking
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[tool.hatch.version]
+path = "src/esoul/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/esoul"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/esoul",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]
+
+# ─── mypy ────────────────────────────────────────────────────────────────
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+# The generated resources/types modules will land here after codegen.
+# Their typing is stricter than mypy's defaults expect.
+files = ["src/esoul"]
+
+[[tool.mypy.overrides]]
+module = "esoul.resources.*"
+# Codegen-emitted modules carry a `# mypy: file generated` marker; we keep
+# strict mode but allow ignore-comments to pile up around generated bits.
+strict = true
+
+# ─── ruff ────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade (modernise type hints etc.)
+    "RUF", # ruff-specific
+]
+ignore = [
+    "E501",  # line length — formatter handles it
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]  # asserts in tests are fine
+
+# ─── pytest ──────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

esoul-0.1.0/src/esoul/__init__.py

@@ -0,0 +1,79 @@
+"""esoul — Python SDK for the ExternalSoul platform.
+
+See README.md for usage. The top-level surface:
+
+  esoul.Esoul          — sync client
+  esoul.AsyncEsoul     — async client
+  esoul.Credentials    — credential dataclass (typically accessed via client.credentials)
+  esoul.<Exception>    — typed errors; see exceptions module docstring for the full hierarchy
+
+Per-app typed resources (spreadsheet, slideshow, notes, …) ship via the
+codegen pipeline and attach to the client as new attributes; they're
+non-breaking additions.
+"""
+
+from __future__ import annotations
+
+from ._async_client import AsyncEsoul
+from ._auth import Credentials
+from ._client import Esoul
+from ._version import __version__
+from .exceptions import (
+    APIError,
+    AuthError,
+    DriveError,
+    DriveNotConnected,
+    EsoulError,
+    IdempotencyConflict,
+    InvalidRequest,
+    MissingCredentialsError,
+    NotFoundError,
+    RateLimitError,
+    TransportError,
+    WorkspaceAccessDenied,
+)
+from .resources.agents import (
+    InvocationError,
+    InvocationHandle,
+    InvocationResult,
+    InvocationStatus,
+    InvocationTimeout,
+)
+from .resources.questions import (
+    Answer,
+    Question,
+    QuestionAlreadyResolved,
+    QuestionTimeout,
+)
+
+__all__ = [
+    # version
+    "__version__",
+    # clients
+    "Esoul",
+    "AsyncEsoul",
+    "Credentials",
+    # exceptions (re-exported at top-level for ergonomic `except esoul.AuthError`)
+    "EsoulError",
+    "MissingCredentialsError",
+    "TransportError",
+    "APIError",
+    "AuthError",
+    "WorkspaceAccessDenied",
+    "NotFoundError",
+    "InvalidRequest",
+    "IdempotencyConflict",
+    "RateLimitError",
+    "DriveNotConnected",
+    "DriveError",
+    # Stage 12 — agent invocation + workspace HIL queue
+    "InvocationStatus",
+    "InvocationResult",
+    "InvocationHandle",
+    "InvocationTimeout",
+    "InvocationError",
+    "Question",
+    "Answer",
+    "QuestionTimeout",
+    "QuestionAlreadyResolved",
+]