ankka 0.4.0__tar.gz

ankka-0.4.0/.gitignore

@@ -0,0 +1,33 @@
+target/
+project/target/
+project/project/
+.bsp/
+.bloop/
+.metals/
+.idea/
+.vscode/
+*.log
+.DS_Store
+.env
+
+# Local-only Claude settings
+.claude/settings.local.json
+
+# Kubernetes: never commit cluster credentials or rendered secrets
+kubeconfig*
+.kube/
+*.secret.yaml
+*.key
+*.crt
+
+# Python (the SDK under sdks/python)
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+sdks/python/src/ankka/_proto/
+.pytest_cache/
+.mypy_cache/
+
+# Claude Code worktrees: other sessions' checkouts, never part of this one
+.claude/worktrees/

ankka-0.4.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: ankka
+Version: 0.4.0
+Summary: The ankka SDK for Python: components in Python, hosted by the ankka sidecar
+Project-URL: Homepage, https://docs.ankka.cloud/
+Project-URL: Documentation, https://docs.ankka.cloud/reference/python-sdk/
+Project-URL: Repository, https://github.com/thinkmorestupidless/ankka
+Project-URL: Changelog, https://github.com/thinkmorestupidless/ankka/releases
+Author: Trevor Burton-McCreadie
+License-Expression: Apache-2.0
+Keywords: agents,ankka,event-sourcing,pekko,serverless,workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: grpcio<2,>=1.84
+Requires-Dist: protobuf<8,>=6
+Provides-Extra: testkit
+Requires-Dist: httpx>=0.27; extra == 'testkit'
+Requires-Dist: testcontainers<5,>=4.15; extra == 'testkit'
+Description-Content-Type: text/markdown
+
+# ankka for Python
+
+Components in Python — event sourced and key value entities, views, consumers, workflows, timed actions,
+agents and HTTP endpoints — hosted by the ankka sidecar, the same runtime that hosts a Scala service.
+Your process decides what should happen; the sidecar owns sharding, the journal, projections, timers,
+HTTP, the agent loop and the model key.
+
+- [Your first service in Python](https://docs.ankka.cloud/get-started/first-service-python/)
+- [Services in other languages](https://docs.ankka.cloud/concepts/polyglot/) — how the sidecar model works
+- [Python SDK reference](https://docs.ankka.cloud/reference/python-sdk/) — the API, and developing this SDK
+- [Sidecar protocol](https://docs.ankka.cloud/reference/sidecar-protocol/)
+
+The same pages are in this repository under
+[`docs/`](https://github.com/thinkmorestupidless/ankka/tree/main/docs).
+
+```bash
+uv add "ankka==<the version of the platform you deploy to>"   # from PyPI, published with every release
+```
+
+Developing the SDK itself, from this directory:
+
+```bash
+uv sync && uv run python scripts/proto.py && uv run pytest -q && uv run mypy && uv run conformance
+```

ankka-0.4.0/README.md

@@ -0,0 +1,24 @@
+# ankka for Python
+
+Components in Python — event sourced and key value entities, views, consumers, workflows, timed actions,
+agents and HTTP endpoints — hosted by the ankka sidecar, the same runtime that hosts a Scala service.
+Your process decides what should happen; the sidecar owns sharding, the journal, projections, timers,
+HTTP, the agent loop and the model key.
+
+- [Your first service in Python](https://docs.ankka.cloud/get-started/first-service-python/)
+- [Services in other languages](https://docs.ankka.cloud/concepts/polyglot/) — how the sidecar model works
+- [Python SDK reference](https://docs.ankka.cloud/reference/python-sdk/) — the API, and developing this SDK
+- [Sidecar protocol](https://docs.ankka.cloud/reference/sidecar-protocol/)
+
+The same pages are in this repository under
+[`docs/`](https://github.com/thinkmorestupidless/ankka/tree/main/docs).
+
+```bash
+uv add "ankka==<the version of the platform you deploy to>"   # from PyPI, published with every release
+```
+
+Developing the SDK itself, from this directory:
+
+```bash
+uv sync && uv run python scripts/proto.py && uv run pytest -q && uv run mypy && uv run conformance
+```

ankka-0.4.0/examples/shopping_cart/Dockerfile

@@ -0,0 +1,11 @@
+# The developer's container: only their code and the SDK. The sidecar is the platform's.
+# Plain pip, so the build needs nothing beyond Docker Hub's python image.
+FROM python:3.12-slim
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY src ./src
+COPY proto ./proto
+RUN pip install --no-cache-dir . && rm -rf src proto
+COPY examples ./examples
+ENV ANKKA_PROCESS_PORT=9010
+CMD ["python", "-m", "examples.shopping_cart.main"]

ankka-0.4.0/examples/shopping_cart/__init__.py

@@ -0,0 +1,2 @@
+"""The shopping cart, ported: the same wire names, routes and JSON as the Scala sample, so the
+two share a journal."""

ankka-0.4.0/examples/shopping_cart/assistant.py

@@ -0,0 +1,49 @@
+"""An agent that answers questions about a cart. It declares its instructions, one tool and one
+guardrail; the sidecar runs the loop — the model, memory, compaction — and asks this process to run
+the tool and check the guardrail. No model key lives here."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ankka.agent import Agent, Guardrail, Tool, stream
+from ankka.effects.agent import AgentEffect
+from ankka.event_sourced_entity import command
+
+from examples.shopping_cart.domain import ShoppingCart
+
+
+@dataclass(frozen=True)
+class CartLookup:
+    cartId: str
+
+
+async def _lookup(agent: Agent, arguments: CartLookup) -> str:
+    assert agent.client is not None
+    cart = await agent.client.for_event_sourced_entity("shopping-cart", arguments.cartId).call("get-cart").invoke(reply=ShoppingCart)
+    if not cart.items:
+        return f"cart {arguments.cartId} is empty"
+    return ", ".join(f"{i.quantity} x {i.name}" for i in cart.items)
+
+
+class CartAssistant(Agent):
+    component_id = "assistant"
+    tools = {"lookup": Tool("Looks up what is in a cart by its id.", _lookup, CartLookup)}
+    guardrails = {"no-secrets": Guardrail(lambda stage, text: "a key leaked" if stage == "output" and "sk-" in text else None)}
+
+    def _describe(self, question: str) -> AgentEffect[str]:
+        return (
+            self.effects.system_message("You help shoppers with their carts. Use the lookup tool before answering about a cart.")
+            .user_message(question)
+            .tools("lookup")
+            .guardrails("no-secrets")
+            .then_reply()
+        )
+
+    @command("ask")
+    def ask(self, question: str) -> AgentEffect[str]:
+        return self._describe(question)
+
+    @stream("chat")
+    def chat(self, question: str) -> AgentEffect[str]:
+        return self._describe(question)

ankka-0.4.0/examples/shopping_cart/cart_rows.py

@@ -0,0 +1,51 @@
+"""A queryable projection of every cart: the entity answers by cart id, this answers the rest —
+which carts contain a product, which have been checked out, which are the largest."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+from ankka import json_codec
+from ankka.effects.view import ViewEffect
+from ankka.view import View
+
+from examples.shopping_cart.domain import CheckedOut, ItemAdded, ItemRemoved, ShoppingCartEvent
+from examples.shopping_cart.entity import ShoppingCartEntity
+
+
+@dataclass(frozen=True)
+class CartRow:
+    cartId: str
+    quantities: dict[str, int] = field(default_factory=dict)
+    checkedOut: bool = False
+
+    @property
+    def total_quantity(self) -> int:
+        return sum(self.quantities.values())
+
+
+class CartRows(View[ShoppingCartEvent, CartRow]):
+    component_id = "cart-rows"
+    source = ShoppingCartEntity
+    event_codec = ShoppingCartEntity.event_codec
+    row_codec = json_codec(CartRow, "cart-row")
+    queries = ("by-id", "all")
+
+    def on_change(self, event: ShoppingCartEvent) -> ViewEffect:
+        current = self.row or CartRow(self.metadata.subject or "")
+        match event:
+            case ItemAdded(item):
+                quantities = {**current.quantities, item.productId: current.quantities.get(item.productId, 0) + item.quantity}
+                return self.effects.update_row(replace(current, quantities=quantities))
+            case ItemRemoved(product_id):
+                return self.effects.update_row(replace(current, quantities={k: v for k, v in current.quantities.items() if k != product_id}))
+            case CheckedOut():
+                return self.effects.update_row(replace(current, checkedOut=True))
+        raise AssertionError(event)
+
+    def on_delete(self) -> ViewEffect:
+        """Checkout deletes the cart, but a checked-out cart is exactly what an order history
+        needs: the row outlives the entity that produced it."""
+        if self.row is None:
+            return self.effects.ignore()
+        return self.effects.update_row(replace(self.row, checkedOut=True))

ankka-0.4.0/examples/shopping_cart/checkout_log.py

@@ -0,0 +1,33 @@
+"""Where the notifier records checkouts: a key value entity per cart holding when it happened."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ankka import DONE, Done, json_codec
+from ankka.effects.key_value import KeyValueEffect, KeyValueReadOnlyEffect
+from ankka.event_sourced_entity import command, query
+from ankka.key_value_entity import KeyValueEntity
+
+
+@dataclass(frozen=True)
+class CheckoutRecord:
+    cartId: str
+    at: int = 0
+    notified: bool = False
+
+
+class CheckoutLog(KeyValueEntity[CheckoutRecord]):
+    component_id = "checkout-log"
+    state_codec = json_codec(CheckoutRecord, "checkout-record")
+
+    def empty_state(self) -> CheckoutRecord:
+        return CheckoutRecord(self.entity_id)
+
+    @command("record")
+    def record(self, at: int) -> KeyValueEffect[CheckoutRecord, Done]:
+        return self.effects.update_state(CheckoutRecord(self.entity_id, at, True)).then_reply(lambda _: DONE)
+
+    @query("get")
+    def get(self) -> KeyValueReadOnlyEffect[CheckoutRecord, CheckoutRecord]:
+        return self.effects.reply(self.state)

ankka-0.4.0/examples/shopping_cart/checkout_notifier.py

@@ -0,0 +1,29 @@
+"""Turns an internal event into an action elsewhere: the cart's own events are an implementation
+detail, and this consumer decides which are worth acting on. Here it records the checkout in
+the checkout log through the client — a consumer that publishes to a topic instead declares
+``produces_to`` and an ``out_codec``, and the sidecar needs a broker (``ANKKA_KAFKA_BOOTSTRAP_SERVERS``)."""
+
+from __future__ import annotations
+
+import time
+
+from ankka import Done
+from ankka.consumer import Consumer
+from ankka.effects.consumer import ConsumerEffect
+
+from examples.shopping_cart.domain import CheckedOut, ShoppingCartEvent
+from examples.shopping_cart.entity import ShoppingCartEntity
+
+
+class CheckoutNotifier(Consumer[ShoppingCartEvent, None]):
+    component_id = "checkout-notifier"
+    source = ShoppingCartEntity
+    message_codec = ShoppingCartEntity.event_codec
+
+    async def on_message(self, event: ShoppingCartEvent) -> ConsumerEffect:  # type: ignore[override]
+        if not isinstance(event, CheckedOut):
+            return self.effects.ignore()
+        cart_id = self.metadata.subject or ""
+        assert self.client is not None
+        await self.client.for_key_value_entity("checkout-log", cart_id).call("record").invoke(int(time.time() * 1000), reply=Done)
+        return self.effects.done()

ankka-0.4.0/examples/shopping_cart/checkout_workflow.py

@@ -0,0 +1,81 @@
+"""A checkout as a durable multi-step process: reserve the stock, charge the customer, and check
+the cart out — or compensate. The sidecar journals every transition and runs the steps; a step
+that throws is retried and failed over as declared in ``settings``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from datetime import timedelta
+
+from ankka import DONE, Done, ErrorCode, json_codec
+from ankka.client import Calls
+from ankka.effects.workflow import StepRef, WorkflowEffect, WorkflowReadOnlyEffect, WorkflowStepEffect
+from ankka.event_sourced_entity import command, query
+from ankka.workflow import Recovery, StepSettings, Workflow, WorkflowSettings, step
+
+from examples.shopping_cart.domain import ShoppingCart
+
+
+@dataclass(frozen=True)
+class Checkout:
+    cartId: str
+    status: str = "new"
+    reserved: int = 0
+    mode: str = "ok"
+
+
+class PaymentDeclined(Exception):
+    pass
+
+
+# docs:start workflow
+class CheckoutWorkflow(Workflow[Checkout]):
+    component_id = "checkout"
+    state_codec = json_codec(Checkout, "checkout")
+    settings = WorkflowSettings(
+        default_step_timeout=timedelta(seconds=10),
+        steps={"charge": StepSettings(recovery=Recovery(max_retries=1, failover_to="compensate"))},
+    )
+
+    def empty_state(self) -> Checkout:
+        return Checkout(self.entity_id)
+
+    @command("start")
+    def start(self, mode: str) -> WorkflowEffect[Checkout, Done]:
+        """``mode``: ``ok``, ``fail`` (the charge is declined) or ``pause`` (a pause before it)."""
+        if self.state.status != "new":
+            return self.effects.error(f"checkout is already {self.state.status}", ErrorCode.CONFLICT)
+        return self.effects.update_state(replace(self.state, status="reserving", mode=mode)).then_transition_to("reserve").then_reply(lambda _: DONE)
+
+    @query("status")
+    def status(self) -> WorkflowReadOnlyEffect[Checkout, Checkout]:
+        return self.effects.reply(self.state)
+
+    @step("reserve")
+    async def reserve(self) -> WorkflowStepEffect[Checkout]:
+        # A client call from a step: what the cart holds.
+        total = await self._cart().call("total-quantity").invoke(reply=int)
+        next_step = "wait" if self.state.mode == "pause" else "charge"
+        return self.step_effects.update_state(replace(self.state, status="reserved", reserved=total)).then_transition_to(next_step)
+
+    @step("wait")
+    def wait(self) -> WorkflowStepEffect[Checkout]:
+        return self.step_effects.update_state(replace(self.state, status="waiting")).then_pause(after=timedelta(milliseconds=1500), on_timeout=StepRef("charge"))
+
+    @step("charge")
+    async def charge(self) -> WorkflowStepEffect[Checkout]:
+        if self.state.mode == "fail":
+            raise PaymentDeclined("payment declined")
+        # Not idempotent — a retry after the cart was checked out is refused — which is why
+        # ``charge`` is allowed one retry and then fails over, and why compensation exists.
+        if self.state.reserved > 0:
+            await self._cart().call("checkout").invoke(reply=ShoppingCart)
+        return self.step_effects.update_state(replace(self.state, status="charged")).then_end()
+
+    @step("compensate")
+    def compensate(self) -> WorkflowStepEffect[Checkout]:
+        return self.step_effects.update_state(replace(self.state, status="compensated", reserved=0)).then_end()
+
+    def _cart(self) -> Calls:
+        return self.context.client.for_event_sourced_entity("shopping-cart", self.state.cartId)
+# docs:end workflow