Write decoupled functions in Python and let Mercury Composable engines (Java, and the official Rust port) orchestrate them from Event Script flows and MiniGraph knowledge graphs — with no orchestration code in Python at all.
This package is a deliberately lightweight wrapper of the Event-over-HTTP protocol:
- an Event API host (
POST /api/event) that dispatches incoming event envelopes to your registered functions, - a thin client (
PostOffice) to call functions on peer applications the same way, - the standard event envelope wire format codec (language-neutral MsgPack), and
- a primitive in-process event bus — the single dispatch pipeline: one FIFO mailbox
per route consumed by
instancesworker tasks, and - the minimalist utilities shared with the engines for consistency: configuration management, logging in the engines' presentation format, and distributed-trace context, and
- the OpenTelemetry forwarder (opt-in,
otel.forwarding=true): the host's trace spans exported over OTLP/HTTP to Dynatrace, Splunk or a collector — no SDK, no new dependency.
Orchestration deliberately stays in the engines. Functions written here are addressed by
route name through the engines' declarative yaml.event.over.http map, so a flow or a
graph task calls a Python function exactly as if it were local.
Documentation: https://accenture.github.io/mercury-python/ — including the AI Agent Guide for deterministic function generation.
Status: v4.12.30 is on PyPI —
pip install mercury-composable. This repository was repurposed in August 2026 for the polyglot initiative. The legacy Mercury language-pack implementation remains in tagged releases.
# app.py
from mercury_composable import AppException, Body, platform, preload
@preload(route="hello.python", instances=10)
def handle_event(headers: dict[str, str], body: Body):
if not isinstance(body, dict) or "text" not in body:
raise AppException(400, "missing 'text'")
return {"text": str(body["text"]).upper(), "language": "python"}
if __name__ == "__main__":
platform.run() # port from rest.server.port (default 8085)Run it:
pip install mercury-composable
mercury-serve app.py -Drest.server.port=8086Call it from a Mercury engine application with two configuration entries and no code —
application.properties:
yaml.event.over.http=classpath:/event-over-http.yamlevent-over-http.yaml:
event.http:
- route: 'hello.python'
target: 'http://127.0.0.1:8086/api/event'Any Event Script task or MiniGraph graph.task node that names the route hello.python
now executes the Python function, with trace context carried end to end.
A handler receives the same two-part input as an engine TypedLambdaFunction —
(headers: dict[str, str], body: Body) — Body is any MsgPack value — and returns the reply body (or an EventEnvelope for full
control of status and reply headers). Both async def and plain def handlers are
first-class, because Python has two library ecosystems and a polyglot function must be
able to wrap either:
- plain
def— for the synchronous world:requests(one of the most popular HTTP clients), NumPy/pandas and most ML inference stacks, database drivers. These handlers run in a thread-pool executor, so a blocking call can never stall the event loop that hosts every other function. This is the Python analog of the Java engine's virtual threads: write sequential blocking-style code and the platform makes it safe. async def— for asyncio-native I/O and for composing sibling functions withawait po.request(...).
The style is detected automatically (no flag to set), and trace context, instances,
envelopes and telemetry behave identically in both. Rule of thumb: wrapping a blocking
library → plain def; composing functions or async I/O → async def.
- Raise
AppException(status, message)for intentional errors — it becomes the portable error contract on the wire (envelope status + message), handled by the calling flow's exception handler or the graph'serror.*contract. get_trace()exposestrace_id/trace_path/cid;annotate_trace(k, v)sends an annotation back on the reply envelope.- Outside a hosted function (batch jobs, tests),
trace_context(trace_id, trace_path)establishes the context yourPostOfficecalls inherit — the noderunWithTracetwin. - Route aliases:
routetakes one name or a comma-separated list (@preload(route="hello.declarative, hello.world")), the engines'@PreLoadsemantics — every name is the same function with the sameinstancesand visibility, and a handler reads the name it was called as fromget_trace().route. - Functions must be stateless; anything you must keep belongs to the caller's flow model or state machine.
PostOffice without an endpoint delivers through this application's own event bus —
the engines' semantics for an in-app po call:
private=Truemeans exactly what it means in the engines: callable in-app only. Local calls reach private and public routes alike; the HTTP host keeps answering 403 for private targets from the wire.instancesis faithful: each route has one FIFO mailbox consumed by that many worker tasks. RPC waits are bounded bytimeout_ms(the standard 408 envelope on breach), and a queued call whose caller already timed out is skipped, never wastefully executed.- Sync handlers compose too:
po.request_sync(...)/po.send_sync(...)run the same call on the host loop while blocking only the handler's own worker thread — the trace chain rides across the bridge unbroken. Calling the sync bridge from async code is refused with a teaching error (await po.request(...)is the async way), and using it outside a hosted function tells you to useasyncio.run(po.request(...))instead. - There is no spill tier and no queue cap by design: back-pressure belongs to the tier that owns recovery — the engines' flows and graphs. A leaf host fails fast by deadline instead of hoarding work.
Local eventing is for simple leaf-side composition. Workflow processing belongs in Event Script and Knowledge Graph on the engines — that boundary is the architecture.
The same conventions as the engines, so a polyglot installation stays uniform:
| Key | Meaning | Default |
|---|---|---|
application.name |
application identity in logs | application |
rest.server.port |
Event API port | 8085 |
log.format |
text, json (pretty-printed) or compact (single-line JSONL) |
text |
log.level |
log level (LOG_LEVEL env var wins) |
INFO |
static.html.folder |
the folder of static web content the host serves (HTML, CSS, JS, images), relative to the application file | resources/public |
Configuration lives in the resources folder next to the application file, mirroring the
engines' classpath resources: resources/application.yml (or .yaml / .properties) beside
the file mercury-serve is given, or beside the script python app.py ran — never the working
directory, so the configuration does not depend on where the app is launched from — or an
explicit --config path; see
examples/demo-app/resources/application.yml for a worked
sample. Values support ${ENV_VAR:default} substitution. Runtime parameter overrides use the
same -D syntax as the Java engine and the Rust port — checked first on every read, their values
resolved with the same substitution, so -Dkey='${ENV_VAR}' keeps a credential out of the process
list (AppConfig.set(key, value) does the same programmatically, the f:setConfig analog):
mercury-serve app.py -Drest.server.port=8086 -Dlog.format=jsonLog lines follow the Java reference engine's pattern for one-aggregation consistency:
2026-08-22 10:15:30.123 INFO my_app:42 - Loaded PUBLIC hello.python, instances=10
The host serves the engines' operational endpoints on the same port as /api/event, so
Kubernetes probes and dashboards treat a Python app exactly like a Java or Rust engine app:
| Endpoint | Purpose |
|---|---|
GET / |
the static folder's index.html, else a minimal index page linking the endpoints below |
GET /info |
app identity, runtime, origin id, start time, uptime |
GET /info/routes |
registered routes split by visibility, with instance counts |
GET /env |
selected environment variables and configuration parameters |
GET /health |
dependency health checks — UP (HTTP 200) or DOWN (HTTP 400) |
GET /livenessprobe |
OK while the last health outcome was good, else HTTP 400 |
Configuration keys carry the engines' names: info.app.version, info.app.description,
show.env.variables and show.application.properties (opt-in lists — secrets are never
dumped wholesale), and mandatory.health.dependencies / optional.health.dependencies
(routes of health check functions; optional ones never change the overall status). A
health check function is a normal registered function — usually private — speaking the
engines' interface contract, called through the event bus:
@preload("demo.health", private=True)
async def health(headers: dict[str, str], _body: Body) -> Body:
if headers.get("type") == "info":
return {"service": "demo.service", "href": "http://127.0.0.1"}
return "demo.service is running fine" # a non-200 reply marks it downJSON responses are pretty-printed — the engines' default-serializer presentation — and
unknown paths answer the engines' error shape
({"status": 404, "message": "Resource not found", "type": "error"}).
Kubernetes wiring: point livenessProbe at /livenessprobe and readinessProbe at
/health.
The host serves the files of static.html.folder — the Java engine's key, with the Rust engine's
location as its default, resources/public next to the application file — for any GET or HEAD
that no host path, extension route or function claims, so an application can ship a web front-end
beside its functions the way the engines' Playground does. A folder is served as its index.html,
so resources/public/index.html replaces the landing page at /. The content type follows the
engines' table by extension (text/javascript, text/css, image/svg+xml, fonts and images;
application/octet-stream otherwise); every file carries an ETag and answers If-None-Match with
304, and HTML is served Cache-Control: no-cache, so a redeployed page is revalidated while hashed
assets stay cached. A hidden entry, a .. segment, a symbolic link that leaves the folder or
anything that is not a regular file is not found, in the engines' error shape. A relative value of
the key is under the application file's folder, never the working directory; file: prefixes an
absolute path as in the Java engine; an empty value turns the service off.
The codec implements the
Event Envelope Wire Format
(standard format) and is verified against the golden conformance vectors shared by the
Java and Rust engines (tests/vectors/vectors.json). The classic compact format is
detected and rejected with a teaching error — engines default to the standard format for
Event over HTTP.
Serialization notes: integers and floats follow MsgPack's natural widths (the same
long/integer care as the engines applies); timestamps travel as ISO-8601 UTC strings with
millisecond precision; binary payloads use MsgPack bin.
This package intentionally contains no orchestration: no flows, no graphs, no persistence, no pub/sub broadcast — those live in the engines. What it does carry is deliberately minimal: functions, a primitive in-process event bus (route mailboxes + workers, RPC and drop-n-forget — nothing more), and the minimalist foundation utilities, keeping Python fast to prototype with while the composable core guarantees the architecture.
A function always runs in this process, never in a subprocess or an embedded interpreter.
The one subprocess the pack may start is an MCP server reached over stdio: the pack runs it
as a child process and talks to it over its standard input and output. That is why the MCP
clients of the engines' agent loop (RFC-0011) live in the language packs: no engine starts a
child process. The MCP binding in extensions/mcp-binding/ is that client: one composable route per
allowlisted remote tool, over stdio or streamable HTTP, on the official MCP SDK.
The LLM helper in extensions/llm-helper/ is an application on this package, not part of it.
Its llm.chat is configurable: a stateless chat, or one turn of a multi-turn tool-use loop whose
transcript lives in the store the helper is configured with. The built-in agent tools in
extensions/agent-tools/ are the essential tools such a loop names in its catalog - files inside one
workspace, the web inside an allowlist of sites, a clock - each a composable function whose sandbox is
deployment configuration, never an argument of a call.
The ask-a-person main flow in extensions/ask-person/ carries such a loop's wait for a person to the
installation's channels and brings the decision back through a resume link, knowing no channel and keeping
no store; the agent-question app, a store-and-forward channel for an occasionally connected device, is a
separate application on the same package.
uv venv .venv && uv pip install -e '.[dev]' # environment (uv-managed python)
.venv/bin/pytest -q # tests
uvx ruff check . # lint (config in pyproject.toml)
uvx basedpyright # type check (config in pyproject.toml)PyCharm: use interpreter type uv pointing at the project .venv, and set
Settings → Tools → Python Integrated Tools → Package requirements file to
pyproject.toml so the requirements inspection reads [project.dependencies].
Apache 2.0 — see LICENSE.txt.