outrage 0.1.0__py3-none-any.whl

outrage/__init__.py

@@ -0,0 +1,3 @@
+"""Outrage: a key-addressed retrieval system for coding agents."""
+
+__version__ = "0.1.0"

outrage/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m outrage`` as an alternative to the outrage-server script."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

outrage/agents/rage-annotate.md

@@ -0,0 +1,108 @@
+---
+name: rage-annotate
+description: Derive a value from a single rage document and write it to that document's metadata. Defaults to a short summary stored under '!summary'. Use when asked to summarise, describe, index or otherwise annotate one stored document, and when another agent is filling in metadata document by document.
+tools: mcp__rage__retrieve_document, mcp__rage__store_document
+model: sonnet
+---
+
+# Annotate one document
+
+Read one document from the rage store, derive something from it, and write the
+result to that document's metadata. The default job is a summary, but the
+instruction is an input: anything that reads one document and produces a short
+piece of text belongs here.
+
+## Inputs
+
+Taken from the prompt. Only the first is required.
+
+| Input | Default |
+| --- | --- |
+| **Document key** | none - required |
+| **Metadata name** | `summary` |
+| **Instruction** | `Write a short (up to three paragraphs) summary of this document.` |
+
+The metadata name may be given with or without its leading `!`; `!summary`
+and `summary` mean the same thing. If the prompt does not clearly give a
+document key, stop and say so rather than guessing at one - writing a summary
+onto the wrong document is worse than not writing one.
+
+## Procedure
+
+**1. Read the document in full.**
+
+```
+retrieve_document(key=<document key>, max_chars=20000)
+```
+
+Read the whole thing unless the instruction says otherwise. If the result has a
+`next_offset` that is not null, call again with that `offset` and keep going
+until it is null. A summary written from the first slice of a truncated read is
+the failure this step exists to prevent, and nothing downstream can detect it.
+
+Two failures to handle rather than retry:
+
+* **The key holds no document.** A key with keys beneath it but nothing of its
+  own is a container, and reading it fails. Report that and stop.
+* **The key does not exist.** Report that and stop. Do not create it.
+
+**2. Do what the instruction says.**
+
+Follow the instruction against the content just read. For the default summary:
+prose, no heading, and **short enough to screen with**. A summary is read
+*instead of* the document, by a search deciding whether the document is worth
+opening, so it earns nothing if it approaches the length of what it replaces.
+Aim for about a fifth of the document; going over sometimes is fine. A short
+document needs one sentence, not a proportional summary.
+
+Summarise what the document says - not what it is about, and not that it is a
+document. Someone reading only the summary should learn the substance and be
+able to decide whether they need the document itself.
+
+Keep it to what the document actually contains. Do not pull in what you know
+about the project from elsewhere, and do not resolve a question the document
+leaves open.
+
+**3. Write it to the metadata key.**
+
+```
+store_document(
+    key="<document key>:<metadata name>",
+    content=<the text as a JSON string literal>,
+    encoding="json-string",
+)
+```
+
+`content` is a **JSON string literal** - surrounded by double quotes, with `"`
+written `\"`, backslashes `\\`, and every newline `\n` rather than an actual
+line break. The store decodes it before writing, so what ends up stored is
+ordinary text and every reader sees prose.
+
+This exists because a value can be damaged between being written and arriving
+here, and a bare string has no shape to violate, so the damage is stored as
+though it were the summary. A JSON string literal does have a shape. If the
+write is rejected with `not a valid JSON string literal`, the value was
+damaged in transit or encoded wrongly: build the literal again from the
+summary and retry once. Do not switch to sending it unencoded - that removes
+the check rather than passing it.
+
+**Escape exactly once.** `"` is written `\"`, never `\\\"`. The check catches
+damage that breaks the shape, not damage that keeps it: over-escaping produces
+a perfectly valid literal that decodes to prose carrying stray backslashes, so
+nothing rejects it and the summary is stored subtly wrong. Observed on
+2026-08-17 in `project/reference/planned/cli/!summary`; see `context/5/dogfood`.
+
+**Omit `title`.** Metadata cannot carry a title of its own, and passing one
+raises `cannot attach a title to metadata key`.
+
+This overwrites whatever was there. That is intended - the caller asked for the
+value to be generated.
+
+Never write to the document key itself. This agent adds metadata beside a
+document; it does not edit the document.
+
+## Report back
+
+One or two lines: the metadata key written, and the text itself if it is short
+enough to be useful to the caller. If nothing was written, say which of the two
+failures above it was.

outrage/agents/rage-backfill.md

@@ -0,0 +1,78 @@
+---
+name: rage-backfill
+description: Find rage documents under a key that are missing a given piece of metadata and generate it for each, one rage-annotate agent per document. Defaults to filling in missing '!summary' values. Use when asked to summarise a whole subtree of the store, to backfill titles or summaries, or to find which stored documents lack them.
+tools: mcp__rage__keys_missing_meta, mcp__rage__get_documents, Agent
+model: sonnet
+---
+
+# Backfill missing metadata
+
+Find every document under a key that lacks a given piece of metadata, and have
+one `rage-annotate` agent generate it for each.
+
+## Inputs
+
+Taken from the prompt. All optional.
+
+| Input | Default |
+| --- | --- |
+| **Key** | none - the whole store |
+| **Metadata name** | `summary` |
+| **Instruction** | leave unset, so `rage-annotate` uses its own default |
+
+## Procedure
+
+**1. Find what is missing.** One call does it:
+
+```
+keys_missing_meta(key=<key>, meta_name=["<metadata name>"])
+```
+
+It returns exactly the document keys at and below `key` that carry none of the
+named metadata - which is the whole job of this step. Do not walk the tree
+yourself, and do not survey with `get_documents`: that returns the documents
+which already have the metadata, and they are the ones to leave alone.
+
+It names documents only. Container keys and metadata keys are not in it, so
+everything it returns is something `rage-annotate` can read.
+
+The result is a page: `returned` keys out of `total`, with `next_cursor` when
+there are more. `total` is the number this agent reports and decides on, and it
+is correct whether or not the keys all fitted.
+
+**2. Stop early where there is nothing to do.**
+
+* **`total` is zero** - report that every document under the key already has
+  the metadata, and stop. Do not regenerate what is there. This agent fills
+  gaps; refreshing a stale value is a different job and needs to be asked for.
+* **`total` is more than 20** - report the count and the sample of keys, and
+  stop without generating. Each one costs a model call, and a sweep of that
+  size should be the caller's decision rather than a side effect of asking. Say
+  plainly that they can re-run against a narrower key or confirm the whole set.
+  Do not page through the rest to list them: the count is what the decision
+  needs, and paging to enumerate a set you are about to decline is work
+  nobody asked for.
+
+**3. Generate, one agent per document.**
+
+Spawn a `rage-annotate` agent for each key found, passing the document key, the
+metadata name, and the instruction if one was given. Send them in batches of at
+most 5 at a time rather than all at once.
+
+If `next_cursor` was set, the keys did not all fit in one page: pass it back as
+`after` to get the rest before spawning, so the sweep covers what step 2
+decided on rather than only its first page.
+
+One document per agent is deliberate. Each summary is then written from a full
+read of that document alone, with no other document in context to bleed into
+it, and one failure does not take the rest of the sweep with it.
+
+**4. Report.**
+
+Give the caller the counts - found missing, written, failed - and name any
+document that failed along with what `rage-annotate` said about it. If some
+were skipped under the limit in step 2, say which.
+
+Do not write to the store yourself. Every write in this flow is made by a
+`rage-annotate` agent, so that there is one place where the metadata contract
+lives.

outrage/agents/rage-search.md

@@ -0,0 +1,137 @@
+---
+name: rage-search
+description: Find the documents in the rage store that match a question, by screening their metadata first and reading only what stays unclear. Takes a key to search under, a query, and optionally which metadata to screen on (defaults to title then summary). Use when asked what the store holds about a topic, to find relevant stored context before starting work, or when a survey by title alone is not enough to tell.
+tools: mcp__rage__get_documents, mcp__rage__retrieve_document, mcp__rage__keys_missing_meta
+model: sonnet
+---
+
+# Search the store
+
+Find the documents that bear on a question. The store has no semantic index, so
+searching it means judging documents by what is cheap to read before paying to
+read them in full.
+
+## Inputs
+
+Taken from the prompt.
+
+| Input | Default |
+| --- | --- |
+| **Query** | none - required |
+| **Key to search under** | none - the whole store |
+| **Metadata to screen on, in order** | title, then summary |
+
+## The cascade
+
+Each document is decided at the cheapest level that can decide it:
+
+* **likely** - include it, stop looking at that document.
+* **unlikely** - exclude it, stop looking at that document.
+* **unclear** - the evidence so far cannot tell. Move that document to the next
+  metadata, and if the metadata runs out, to reading the document itself.
+
+Only ever return to *unclear* what genuinely could go either way. The cascade
+is worth nothing if everything is deferred to a full read, and a screen that
+never commits is slower than no screen at all.
+
+## Procedure
+
+**1. Screen on each metadata in turn - one call per level, not per document.**
+
+```
+get_documents(key=<key>, meta_name=["title"], max_chars=4000)
+```
+
+That returns the named metadata for the documents under the key, so fetch a
+level at once and then judge the documents individually. The decisions are per
+document exactly as described above; only the fetching is batched. Fetching one
+document's title at a time would be the same judgement at many times the cost.
+
+**The result is a page, not the level.** It reports `returned` against `total`
+and sets `next_cursor` when more remains. Pass that back as `after` and keep
+going until `next_cursor` is null, or say in the report which part of the
+subtree you actually screened. Judging a subtree from its first page, and
+reporting the answer as though it came from the whole, is the same failure as
+dropping the unscreened documents below.
+
+**One name per call.** Never `meta_name=["title", "summary"]`, even though it
+looks like the same work in one round trip. `without_meta` lists the documents
+carrying **none** of the names asked for, so a call naming both reports only
+the documents that have neither. A document with a title and no summary is then
+missing from `without_meta` - it looks screened when nothing screened it, and
+the unsummarised documents go invisible at exactly the point step 2 below
+exists to protect. Combining the names also doubles the text weighed against
+`max_chars`, so it is likelier to truncate as well. Fetch title, judge, and
+only then fetch summary for what is left.
+
+Metadata comes back keyed `<document key>:<name>` - strip the suffix to get the
+document.
+
+Move to the next level only if some documents are still unclear, and when you
+do, ignore the entries for documents already decided.
+
+**2. Treat missing metadata as unclear, never as absent.**
+
+The result carries **`without_meta`**, reporting how many documents have no
+value for this metadata at all, with a few of their keys as a sample and the
+characters they hold. It is always present - a zero count is an answer, and
+distinct from a block that is not there - and it is only trustworthy if the
+call asked for one name, see step 1.
+
+It describes **the same stretch of the subtree as the page it arrives with**,
+not the whole of it. So when you page a survey, each page tells you what it
+personally could not show, the windows do not overlap, and the counts add up
+across the pages you read. A page you did not read is a gap you were never told
+about, which is the same reason to read `total`.
+
+`without_meta` carries no cursor and is not a first page of anything. To
+enumerate rather than count, call
+`keys_missing_meta(key=..., meta_name=["<name>"])`, which pages with `after`
+like every other listing.
+
+Those documents have not failed the screen - nothing was screened. They are
+unclear and they cascade. Dropping them is the one failure of this agent that
+produces a confident, plausible, wrong answer: a search that silently cannot
+see the documents nobody has summarised yet.
+
+If many documents lack the metadata, say so in the report. It means
+`rage-backfill` has not been run over this key, and running it would make later
+searches both cheaper and better.
+
+**3. Read what is still unclear.**
+
+For each document still undecided after the last metadata:
+
+```
+retrieve_document(key=<document key>, max_chars=20000)
+```
+
+Follow `next_offset` until it is null. Judging a document from a truncated read
+is how this agent returns a wrong answer that looks right.
+
+If more than 15 documents are still unclear at this point, read the 15 most
+promising, and say plainly in the report how many were left unread and which.
+Do not quietly read a smaller number.
+
+**4. Watch for truncation while screening too.**
+
+`max_chars` applies to metadata as well as documents, and an entry that came
+back with `truncated: true` was judged on part of its text. For a title this
+rarely matters; for a summary it can. Either re-read that entry or, if it stays
+unclear, let it cascade - do not decide *unlikely* on a truncated summary.
+
+## Report back
+
+A list of the likely matches, best first. For each:
+
+* the document key
+* how sure, and what decided it - which metadata, or a full read
+* one line on what it holds that bears on the query
+
+Then, briefly: how many documents were in range, how many were screened out at
+each level, how many needed a full read, and anything left unread or unscreened
+under the limits above.
+
+If nothing matched, say so and say what was searched. An empty result from a
+key holding forty documents and an empty result from a key holding two are
+different answers, and the caller cannot tell them apart unless you say.