swisper-agent-sdk 0.1.0a1__tar.gz

swisper_agent_sdk-0.1.0a1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__
+app.egg-info
+*.pyc
+.mypy_cache
+.coverage
+htmlcov
+.cache
+.venv

swisper_agent_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.5
+Name: swisper-agent-sdk
+Version: 0.1.0a1
+Summary: The published contract a partner builds a Swisper domain agent against
+Project-URL: Homepage, https://github.com/fintama/helvetiq
+Project-URL: Repository, https://github.com/fintama/helvetiq/tree/main/apps/backend/packages/swisper-agent-sdk
+License: MIT
+Keywords: a2a,agent,domain-agent,sdk,swisper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jsonpath-ng>=1.7
+Requires-Dist: langchain-core>=0.1
+Requires-Dist: langgraph>=0.2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# swisper-agent-sdk
+
+Build a Swisper domain agent.
+
+This package is self-contained. You do not need the Swisper backend, a database,
+or network access to build an agent and test it.
+
+## Install
+
+Requires **Python 3.11 or newer**.
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install swisper-agent-sdk
+```
+
+Use the virtual environment's interpreter for everything below. Typing `python3`
+rather than `./.venv/bin/python` is the most common way to get a
+`ModuleNotFoundError` that looks like a broken package and is not.
+
+> **Five declared dependencies pull in more than five packages.** This package
+> declares `pydantic`, `langgraph`, `jsonpath-ng`, `pyyaml` and `langchain-core` —
+> `langgraph` alone brings its own dependency tree with it (`langsmith`, `httpx`,
+> `orjson`, `ormsgpack`, `zstandard` and more). Measured in a clean install: **36
+> packages**, not five. None of that is a defect — every one of them is something
+> `langgraph` genuinely needs — but a partner watching 36 packages scroll by after
+> being told about five deserves to have been told first.
+
+### From a directory, instead
+
+Handed the package as a tarball or a source checkout rather than installing from
+PyPI? Point `pip` at the directory instead of the package name — everything else
+on this page works exactly the same either way:
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install -e ./swisper-agent-sdk
+```
+
+## Your first agent
+
+This is `swisper_agent_sdk/examples/twelve_line_agent.py`, complete and
+unabridged. It ships inside the package itself, so installing it is the only step
+— there is nothing separate to fetch:
+
+```python
+from swisper_agent_sdk import Agent, Delegation, Reply
+
+agent = Agent(
+    name="echo_agent",
+    description="Repeats the task back. The smallest thing that is still an agent.",
+)
+
+
+@agent.handler
+async def handle(d: Delegation) -> Reply:
+    if not d.task:
+        return Reply.ask("What would you like me to do?")
+    return Reply(text=f"You asked me to: {d.task}")
+```
+
+Run it — the same command whether you installed from PyPI or from a directory:
+
+```console
+$ ./.venv/bin/python -m swisper_agent_sdk.examples.twelve_line_agent
+You asked me to: book a train to Bern
+```
+
+`d.task` is what the user asked for. Returning a `Reply` answers them;
+returning `Reply.ask(...)` puts a question to them and pauses the turn.
+
+## Running a turn yourself
+
+`harness` runs a real turn against your agent with **no core, no database and
+no network**:
+
+```python
+import asyncio
+from swisper_agent_sdk import harness
+from my_agent import agent
+
+result = asyncio.run(harness.turn(agent, "book a train to Bern"))
+print(result.text)
+```
+
+### Check your install
+
+Needs the directory install above — `tests/` ships in a source checkout, not in
+the plain PyPI wheel:
+
+```console
+$ cd swisper-agent-sdk
+$ ../.venv/bin/pip install -e ".[dev]"
+$ ../.venv/bin/python -m pytest
+```
+
+That runs a handful of smoke tests: the package imports, importing it leaves your
+logging alone, an agent answers a turn offline, and every bundled example runs and
+prints something. If those pass, the SDK works on your machine.
+
+> **Run `pytest` from inside this directory.** The package's own
+> `asyncio_mode = "auto"` setting lives in its `pyproject.toml`, and pytest only
+> picks it up when invoked from here. Run it from the parent directory and every
+> `async def` test fails — **including correct ones** — which looks like a broken
+> SDK and is not.
+
+`[dev]` is what installs `pytest` and `pytest-asyncio`. The base install
+deliberately does not: it is the runtime, not the toolchain.
+
+### Writing your own tests
+
+`turn()` returns a `TurnResult` with `.text`, `.status`, `.resume_with`, `.cards`,
+`.said`, and two helpers for assertions — `.said_something_about(...)` and
+`.asked_for(...)`:
+
+```python
+async def test_it_answers():
+    r = await harness.turn(agent, "weather in Bern tomorrow")
+    assert r.said_something_about("Bern")
+
+
+async def test_it_can_ask_a_question():
+    r = await harness.turn(agent, "book me a train")
+    assert r.asked_for("departure time")
+    r = await harness.answer(r, "09:00")     # resumes the paused turn
+```
+
+`harness.answer(...)` resumes a turn your agent paused with `Reply.ask(...)`.
+Inside the handler, `d.answer` is what the user replied and `d.resumed` is
+`True`.
+
+> **What a green harness run does and does not prove.** The harness fakes core,
+> the capability endpoint and the token. A green harness run proves your agent's
+> logic, not that the capability works against a live core. Those are different
+> claims and only the first one is tested here.
+
+## Saying things, and sending cards
+
+Two ways to put something in front of the user besides your final answer.
+
+**`await d.say("…")`** narrates a deterministic moment — typically just before a slow
+call, where waiting for the model to decide to mention it is the wrong behaviour:
+
+```python
+await d.say("Checking which trains actually run at that hour…")
+```
+
+**`await d.card("swi-transport", payload)`** emits a card. **The types your agent may
+emit are declared on the agent**, and an undeclared type raises
+`UndeclaredCardTypeError` — never a silent drop:
+
+```python
+agent = Agent(name="…", description="…", cards=["swi-transport"])
+
+await d.card("swi-transport", {"from": "Zurich", "to": "Bern"})   # fine
+await d.card("swi-invented", {...})                               # UndeclaredCardTypeError
+```
+
+The declared list is also what the prompt tells the model about, so it cannot invent a
+card type that has no renderer. Both are visible in tests as `result.said` and
+`result.cards`.
+
+## A fuller example
+
+`swisper_agent_sdk/examples/meal_planning_agent.py` is the one to read once the
+twelve-line agent makes sense. It is a working agent that recalls what it knows
+about you, asks a question when it does not know enough, resumes on your answer,
+and emits a card:
+
+```console
+$ ./.venv/bin/python -m swisper_agent_sdk.examples.meal_planning_agent
+[turn 1] status=waiting_for_input text="I don't have any dietary restrictions or allergies on file for you — could you tell me what I should plan around?"
+[turn 2] status=complete text="Here's a plan built around: I'm vegetarian and allergic to peanuts.."
+cards emitted: ['meal_plan']
+```
+
+It also shows how to reach data you are entitled to. Declare what you need on the
+agent and read it from the delegation:
+
+```python
+agent = Agent(..., inputs=("fact_lookup_service",))
+
+# in the handler:
+facts = await d.fact_lookup_service.get_by_type("ALLERGY")
+```
+
+**You only receive what you declare.** Anything you did not ask for is absent from
+your delegation, not present-and-empty.
+
+> 🔴 **`fact_lookup_service` works in-process and is withheld over the wire.** It is a
+> live service object, so it cannot be serialised to a remotely deployed agent — core
+> drops it from the envelope unconditionally. **The example above runs green under the
+> harness and returns nothing once your agent is deployed remotely, with no error.**
+>
+> This is stated here because it is the one place where following our own documentation
+> produces a silent failure. Facts are meant to reach a remote agent **pre-loaded onto
+> the envelope**, declared in the agent's contract — **that path is seamed but not yet
+> wired, so a remote agent currently receives no pre-loaded facts.** If you are building
+> for remote deployment, do not design around `fact_lookup_service` yet; talk to us.
+
+## Two ways to write an agent, one runtime
+
+`@agent.handler` is not a simplified mode you outgrow. **A handler is compiled
+into a one-node graph**, so it runs through exactly the same machinery as an
+agent you author as a graph yourself:
+
+```python
+agent = Agent(name="…", description="…", graph=my_compiled_graph)
+```
+
+Start with a handler. Move to `graph=` when you need more than one node. You are
+not choosing a path you have to undo later.
+
+## Telling the model how to behave
+
+> 🔴 **No planner ships in this package.** `instructions=`, `routing=`,
+> `narration_style=`, `tool_guidance=`, `prompt=` and `tools=` are stored on the
+> `Agent` and are **not read when your agent runs**. Nothing here calls a model.
+>
+> To use a composed prompt today, call **`agent.compose_prompt(...)` yourself** and
+> drive your own model with it — see
+> [`examples/bring_your_own_model_agent.py`](src/swisper_agent_sdk/examples/bring_your_own_model_agent.py).
+> A handler-mode agent decides everything in Python.
+>
+> **Everything in this section describes what `compose_prompt()` returns, not what
+> the runtime does with it.**
+
+Most agents need one thing — `instructions=`:
+
+```python
+agent = Agent(
+    name="weather_agent",
+    description="Answers weather and forecast questions.",
+    instructions="""
+    You answer questions about weather and forecasts.
+    Prefer official meteorological sources over aggregators.
+    Never speculate beyond seven days — say you don't know instead.
+    """,
+)
+```
+
+**Your `instructions` reach the model verbatim.** We never rewrite them, and they
+are not a template: braces inside them are literal text, so you cannot
+accidentally interpolate one of our internal variables.
+
+The SDK composes the rest of the planner prompt around them — the planning loop,
+how to ask a question and resume, how to narrate, and a context block carrying
+the user's language, locale, timezone, today's date and their temporal context.
+
+**That context block is why this wrapper exists.** Omit the language instruction
+and you answer a German user in English. Omit the locale rules and dates come out
+American. Omit temporal context and "tomorrow" is the wrong day. None of these
+fail a test you would think to write, and all of them reach a user.
+
+If you want to replace one composed section rather than all of it, pass
+`narration_style=`, `tool_guidance=` or `routing=`. If you want full control,
+pass `prompt=` — and `swisper_agent_sdk.prompts.scaffolding()` is importable, so
+you can still assemble the parts you did not want to write yourself.
+
+📖 **[`PROMPTING.md`](PROMPTING.md)** has the full map of what gets composed, plus
+two rules that are not general prompting advice — they are things we got wrong in
+production, in ways that reached users. Read it before you write your second
+agent.
+
+## What this package deliberately does not give you
+
+Said up front, because discovering it by hitting a wall is worse:
+
+- **No `swisper.*` imports.** The SDK never reaches into the Swisper backend, and
+  a build check enforces that on both `src/` and `examples/`. If something you
+  need is missing here, that is our gap to close — tell us rather than working
+  around it.
+- **No database access.** Your agent never opens a database connection. Data you
+  are entitled to arrives through a capability call that core authorises for that
+  turn.
+- **Five declared dependencies**, deliberately: `pydantic`, `langgraph`,
+  `jsonpath-ng`, `pyyaml` and `langchain-core`. A test asserts that every import
+  is declared and every declaration is imported — not a count — so a new one
+  cannot arrive as a side effect of a convenient import, undeclared. (See the
+  install-time note above: `langgraph` alone brings a much larger dependency
+  tree with it — the count above is what *we* declare, not what actually
+  installs.)
+- **The SDK does not configure logging.** Importing it leaves your root logger
+  untouched. Call `swisper_agent_sdk.correlation.configure_logging()` yourself if
+  you want ours.

swisper_agent_sdk-0.1.0a1/PROMPTING.md

@@ -0,0 +1,211 @@
+# Prompting a Swisper agent
+
+> 🔴 **Read this first: no planner ships in this package.**
+>
+> `instructions=`, `routing=`, `narration_style=`, `tool_guidance=`, `prompt=` and
+> `tools=` are stored on the `Agent` and are **not read when your agent runs**.
+> Nothing in this package calls a model.
+>
+> **`compose_prompt()` genuinely works** — it returns the assembled prompt with your
+> `instructions` verbatim inside it. But *you* call it, *you* supply the model, and
+> *you* drive the loop. See
+> [`examples/bring_your_own_model_agent.py`](src/swisper_agent_sdk/examples/bring_your_own_model_agent.py).
+>
+> **So read every present-tense sentence below as describing what
+> `compose_prompt()` returns**, not what the runtime does with it. The rules are
+> real and worth following — they are what we learned building agents on this
+> prompt — but the composition is yours to invoke.
+
+Two rules we paid to learn, a map of the prompt the SDK builds for you, and one
+thing your tests cannot tell you.
+
+These are not general prompting advice — there is plenty of that elsewhere. Each
+rule here is something we got wrong first, in production, in a way that reached
+users.
+
+---
+
+## Rule 1 — "when to call this tool" belongs in the tool, not the prompt
+
+Put the criteria for calling a tool **in that tool's own description**. Keep the
+planner prompt for **cross-tool sequencing only** — what has to happen before
+what.
+
+```python
+# Good: the criterion travels with the tool.
+def get_forecast(city: str, days: int = 3) -> dict:
+    """Return the weather forecast for a city.
+
+    Call this when the user asks about future conditions. For what the weather
+    is doing right now, call get_current instead — this one is modelled and
+    coarse for today.
+    """
+```
+
+```
+# Bad: the same criterion in your `instructions=`.
+Use get_forecast when the user asks about future weather, and get_current
+when they ask about now.
+```
+
+**Why.** The second version is correct on the day you write it and rots on its
+own. When someone changes `get_forecast`, they change the function and its
+docstring — they do not go looking through a prompt for a sentence about it.
+The rule and the thing it describes drift apart silently, and the prompt wins,
+because that is what the model reads.
+
+Written in the description, the criterion is changed by the same edit that
+changes the behaviour. That is the whole argument: **put the rule where the next
+person editing the code will already be standing.**
+
+The SDK derives your `## Your tools` block from the registered functions'
+signatures and full docstrings, so anything you write there reaches the model.
+
+---
+
+## Rule 2 — write a concept and a test question, never a keyword list
+
+When you need the model to classify something, describe the **idea** and give it
+a question it can ask itself. Do not enumerate the words.
+
+```
+# Good: a concept plus a test the model can apply.
+Some facts are sensitive. The test: would the person be embarrassed if this
+appeared on a shared screen without warning? Health, finances, relationships
+and legal matters usually pass that test; a favourite coffee order does not.
+```
+
+```
+# Bad: a keyword table.
+Treat as sensitive if the message contains: diagnosis, illness, therapy,
+salary, debt, divorce, lawyer, ...
+```
+
+**Why.** Keyword lists fail on the two things that are guaranteed to happen.
+
+**They fail on other languages.** Swisper answers in the user's language. A list
+written in English does not fire on *Diagnose*, *Schulden* or *scheiden* — and
+the failure is silent, because a classifier that never fires looks exactly like a
+classifier with nothing to find.
+
+**They fail on typos.** `divorce` and `divorec` are the same disclosure to a
+human and different strings to a matcher. Real messages contain typos at a rate
+that makes this routine, not an edge case.
+
+A concept generalises to both for free. Keep examples — they are useful — but
+write them as *illustrations of the idea*, never as the set to be matched.
+
+---
+
+## What the SDK composes around your `instructions`
+
+At level 1 you write `instructions=` and the SDK assembles this:
+
+```
+[SYSTEM]
+  ├─ planner scaffolding      the iterative loop, batching
+  ├─ HITL rules               how to ask, how to resume, how to escape
+  ├─ card instructions        when to emit; only the types you declared
+  ├─ memory guidance          when recall is worth calling
+  │
+  ├─ ## Your domain      ←    your `instructions`, VERBATIM
+  ├─ ## Your tools       ←    derived from your registered functions
+  ├─ ## Context          ←    language · locale · timezone · date · temporal
+  │
+  └─ narration instructions   ALWAYS LAST — see below
+```
+
+**Your `instructions` are interpolated verbatim and never rewritten.** They are
+not a template: braces inside them are literal, so `{{ user_id }}` in your text
+reaches the model as those characters and cannot pull in one of our variables.
+
+**At level 2** you replace one named block and leave the rest composed:
+`narration_style=` replaces the narration instructions, `tool_guidance=` replaces
+the content under `## Your tools`, `routing=` replaces the HITL rules.
+
+**At level 3** you pass `prompt=` and own the whole thing. If you want some of
+the scaffolding back, `swisper_agent_sdk.prompts.scaffolding()` is importable and
+returns the blocks individually.
+
+### Narration is appended last, and that is deliberate
+
+The narration block is always the final thing in the assembled prompt, at every
+level. **Placement is load-bearing.** A tone instruction sitting thousands of
+characters before the end does not land; the same words at the end do. If you
+override it with `narration_style=`, your text takes that position.
+
+⚠️ **The default narration examples are travel-flavoured** — trains, stations,
+fares. They are there as *mechanism*: positive examples shape the model's output
+far more reliably than instructions about what not to do. If you are building a
+weather or finance agent, the shape still transfers, but consider passing
+`narration_style=` with three examples from your own domain. Keep three, and keep
+them concrete.
+
+---
+
+## What a green test run does not tell you
+
+> **The harness fakes core, the capability endpoint and the token. A green
+> harness run proves your agent's logic, not that the capability works against a
+> live core.**
+
+Those are different claims and only the first one is tested offline.
+
+This is not a defect in the harness — faking the capability endpoint is exactly
+what lets your tests run with no core, no database and no network, which is worth
+far more than the certainty you give up. But it means a passing suite is evidence
+about **your** code, not about the integration.
+
+The failure it protects you from: your tests are green, you run against a real
+core, `recall` returns nothing, and you spend an afternoon debugging your own
+agent. It is not your agent. Check the integration separately, and treat the
+first live run as its own test.
+
+---
+
+## `inputs=` is two mechanisms wearing one name
+
+You declare what your agent receives with `inputs=(...)`. **What that declaration does
+depends on where your agent runs, and the two behaviours are not the same:**
+
+| | in-process | deployed remotely |
+|---|---|---|
+| `inputs=` | an **enforced allowlist** — you get what you declared, and nothing else | **no such concept exists on the wire path** |
+| `fact_lookup_service` | reaches your handler | **withheld unconditionally** — it is a live object and cannot serialise |
+
+**The consequence is the one worth remembering: a handler that reads
+`d.fact_lookup_service` passes every offline test and returns nothing in production.**
+The harness runs the in-process path, so it cannot show you this. Nothing raises.
+
+**And the contract file cannot tell the two apart.** `agent.contract.yaml` describes an
+agent without knowing where it will run, so a declaration that is enforcement in one
+deployment is decoration in the other.
+
+Facts are meant to reach a remote agent **pre-loaded onto the envelope**, with the types
+declared in its contract rather than fetched live. **That seam exists and is not yet
+wired: no agent declares a pre-loaded type today, so a remote agent receives none.**
+Stated in the present tense on purpose — it is a real limitation now, not a promise.
+
+**The general lesson, which outlives this particular field:** when the same name means
+different things on two paths, the one your tests exercise is the one you will believe.
+Ask which path a green run actually walked.
+
+---
+
+## Context you get for free, and why it matters
+
+The `## Context` block carries the user's language, locale, timezone, today's
+date and their temporal context. You do not have to ask for any of it.
+
+This exists because every one of these has shipped as a real defect:
+
+| omitted | what the user got |
+|---|---|
+| language instruction | a German user answered in English |
+| locale formatting | `03/04` meaning April 3rd to a Swiss reader |
+| temporal context | "tomorrow" resolved to the wrong day |
+
+**None of them fail a test you would think to write.** All of them reach a user,
+and all of them get reported to us as Swisper bugs. That is why this block is
+composed rather than left to you — not because you would get it wrong, but
+because you would have to know it was there to get it right.