From dd6365ae92721bbc9d7aefcc8bd307a98372d935 Mon Sep 17 00:00:00 2001 From: Eric Law <39393654+acn-ericlaw@users.noreply.github.com> Date: Tue, 1 Sep 2026 09:12:07 -0700 Subject: [PATCH 1/2] Doc: guide-first lookup rule for consumer AI agents Co-Authored-By: Claude Code --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ed99b47..9e7d726 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,3 +3,12 @@ **Consuming Mercury Composable for Python as a dependency?** Skip the memory protocol — it is for repository contributors. Start at [README.md](README.md) — the quick start, function contract, configuration, and wire-format guide for writing polyglot functions consistently. + +**Efficient lookup — start with the guide, not the source.** +`docs/llms.txt` maps every guide page in this repo. For Python wrapper questions (function +authoring, config, testing, joining a flow or graph), find the right page there first. +For Mercury engine questions (Event Script flows, Knowledge Graph, REST automation), use the +engine's ai-contract-provider guides or its `llms.txt`. A guide-first lookup costs 3–5× fewer +tokens than source discovery. When source reveals a genuine gap, raise an issue or PR against +github.com/Accenture/mercury-python (wrapper docs) or github.com/Accenture/mercury-composable +(engine guides). From 2f9e47c2d0c71340ce2e1b72dff82ba6e42ebcef Mon Sep 17 00:00:00 2001 From: Eric Law <39393654+acn-ericlaw@users.noreply.github.com> Date: Tue, 1 Sep 2026 09:14:12 -0700 Subject: [PATCH 2/2] Doc: add system/AGENTS.md consumer starting point Co-Authored-By: Claude Code --- AGENTS.md | 13 +----- memory/sessions/2026-09-01-161208.md | 12 ++++++ system/AGENTS.md | 60 ++++++++++++++++++++++++++++ 3 files changed, 74 insertions(+), 11 deletions(-) create mode 100644 memory/sessions/2026-09-01-161208.md create mode 100644 system/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 9e7d726..067564b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,14 +1,5 @@ **Contributing to this repository?** Read [memory/PROTOCOL.md](memory/PROTOCOL.md) and follow it. **Consuming Mercury Composable for Python as a dependency?** Skip the memory protocol — it is -for repository contributors. Start at [README.md](README.md) — the quick start, function -contract, configuration, and wire-format guide for writing polyglot functions consistently. - -**Efficient lookup — start with the guide, not the source.** -`docs/llms.txt` maps every guide page in this repo. For Python wrapper questions (function -authoring, config, testing, joining a flow or graph), find the right page there first. -For Mercury engine questions (Event Script flows, Knowledge Graph, REST automation), use the -engine's ai-contract-provider guides or its `llms.txt`. A guide-first lookup costs 3–5× fewer -tokens than source discovery. When source reveals a genuine gap, raise an issue or PR against -github.com/Accenture/mercury-python (wrapper docs) or github.com/Accenture/mercury-composable -(engine guides). +for repository contributors. Start at [system/AGENTS.md](system/AGENTS.md) — the consumer +starting point: guide index, key references, and efficient lookup strategy. diff --git a/memory/sessions/2026-09-01-161208.md b/memory/sessions/2026-09-01-161208.md new file mode 100644 index 0000000..e5634c0 --- /dev/null +++ b/memory/sessions/2026-09-01-161208.md @@ -0,0 +1,12 @@ +# Session (2026-09-01T16:12:08.000Z) + +**Agent:** Claude Code +**Lightweight:** doc-only changes, no memory-relevant events. + +Added `system/AGENTS.md` (consumer starting point — guide index, efficient lookup rule, +key references) and updated root `AGENTS.md` consumer path to point there. +Mirrors the `system/AGENTS.md` convention from mercury-composable and mercury (Rust). + +## Memory References + +(none) diff --git a/system/AGENTS.md b/system/AGENTS.md new file mode 100644 index 0000000..75521e8 --- /dev/null +++ b/system/AGENTS.md @@ -0,0 +1,60 @@ +# Mercury Composable for Python — consumer starting point + +> **Contributors working in this repository:** follow the root [AGENTS.md](../AGENTS.md) +> (the agent-memory protocol) first — this file does not replace it. This scoped guide +> serves AI tools that **consume the Python wrapper as a dependency** and need the fastest +> correct starting point. It lives at the same path as the engine repos' consumer guide +> (`system/AGENTS.md`), so one tool convention finds every Mercury repo. + +## What this package is + +`mercury-python` is a lightweight Event-over-HTTP function host: write decoupled functions +in Python and let Mercury Composable engines (Java, Rust) orchestrate them from Event Script +flows and MiniGraph knowledge graphs. Orchestration stays in the engines; this package +contributes functions plus the engines' operational conventions (configuration, logging, +trace, actuators). + +## Starting point for consumer AI tools + +The quickest path to a working function: + +1. **`docs/llms.txt`** — the machine-readable map of this documentation site. +2. **AI Agent Guide** (`docs/guides/ai-agent-guide.md`) — the complete authoring grammar + on one page: contract, registration, composition, config keys, error rules. +3. **Getting Started** (`docs/guides/getting-started.md`) — a running function in five + minutes, called from an engine flow. + +For Mercury engine questions (Event Script flows, Knowledge Graph models, REST automation, +Kafka integration), use the engine's `docs/llms.txt` or ai-contract-provider skill — this +wrapper's docs cover only the Python function surface. + +## What lives in this repo + +| Path | Role | +|------|------| +| `src/` | the `mercury` package — `Platform`, `PostOffice`, `EventEnvelope`, actuator routes | +| `examples/` | runnable reference functions | +| `docs/` | the MkDocs guide site source | +| `tests/` | unit and integration tests | + +## Key references (repo-relative) + +- `docs/llms.txt` — machine-readable documentation map; start here for keyword lookup +- `docs/guides/ai-agent-guide.md` — AI agent authoring grammar (the authoritative contract) +- `docs/guides/function-patterns.md` — (headers, body) contract, async, composition +- `docs/guides/join-event-script.md` — `yaml.event.over.http`, what the function sees +- `docs/guides/join-knowledge-graph.md` — `graph.task` to a Python target +- `docs/guides/configuration-reference.md` — every well-known config key +- `docs/guides/http-surface-reference.md` — `/api/event` protocol, actuator shapes + +## Efficient lookup + +**For "how do I write / configure X" questions, start with the guide — not the source.** +`docs/llms.txt` maps every guide page. Find the right page there first; read only the +relevant section. Fall back to source only when the guide is genuinely silent on the +specific behavior or you need to verify a subtle invariant. Guide-first costs 3–5× fewer +tokens than source discovery. + +When source reveals a genuine gap, raise an issue or PR against the upstream OSS project: +- **Wrapper docs:** github.com/Accenture/mercury-python +- **Engine guides:** github.com/Accenture/mercury-composable