{ "source": "https://gitlab.com/ahkamboh/stepmold", "commit": "46f9985f8dc4aae7f92881aa2750a3e57f3d920a", "files": { "LICENSE": "MIT License\n\nCopyright (c) 2026 Ali Hamza Kamboh\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n", "examples/content_moderation/evalset.jsonl": "{\"name\": \"benign thank-you post\", \"input\": {\"post\": \"Thanks for the write-up, the regex section finally made it click for me.\", \"context\": \"reply in a beginner programming forum\"}, \"expect\": {\"decision\": \"allow\", \"policy_category\": \"none\", \"severity\": \"none\", \"confidence\": \"high\", \"needs_human\": false}, \"end\": \"allowed\"}\n{\"name\": \"ordinary support question\", \"input\": {\"post\": \"Does the API rate limit reset hourly or daily? The docs say both in different places.\", \"context\": \"new thread in a developer support forum\"}, \"expect\": {\"decision\": \"allow\", \"policy_category\": \"none\", \"severity\": \"none\", \"confidence\": \"high\", \"needs_human\": false}, \"end\": \"allowed\"}\n{\"name\": \"targeted harassment of one user\", \"input\": {\"post\": \"You are pathetic and everyone here knows it. Nobody wants you in this community, so crawl back under your rock.\", \"context\": \"reply aimed at one named user in a hobby forum\"}, \"expect\": {\"decision\": \"block\", \"policy_category\": \"harassment\", \"severity\": \"high\", \"confidence\": \"high\", \"needs_human\": true}, \"end\": \"blocked\"}\n{\"name\": \"hate speech against a national group\", \"input\": {\"post\": \"People from that country should not be allowed to post here, they ruin everything they touch.\", \"context\": \"top-level post in a general discussion forum\"}, \"expect\": {\"decision\": \"block\", \"policy_category\": \"hate_speech\", \"severity\": \"high\", \"confidence\": \"high\", \"needs_human\": true}, \"end\": \"blocked\"}\n{\"name\": \"credible violent threat\", \"input\": {\"post\": \"I know where you work. I will be waiting in the parking lot on Friday.\", \"context\": \"reply to a user after an argument about a refund\"}, \"expect\": {\"decision\": \"block\", \"policy_category\": \"violent_threat\", \"severity\": \"high\", \"confidence\": \"high\", \"needs_human\": true}, \"end\": \"blocked\"}\n{\"name\": \"self-harm goes to a human, never a block\", \"input\": {\"post\": \"I do not see the point of any of it anymore. I have been thinking about ending things.\", \"context\": \"top-level post in a mental health support community\"}, \"expect\": {\"decision\": \"review\", \"policy_category\": \"self_harm\", \"severity\": \"high\", \"confidence\": \"high\", \"needs_human\": true}, \"end\": \"review_queue\"}\n{\"name\": \"investment scam\", \"input\": {\"post\": \"GUARANTEED 300 percent returns every month. DM me for the private signals group, only 5 spots left.\", \"context\": \"top-level post in an investing forum, account created today\"}, \"expect\": {\"decision\": \"block\", \"policy_category\": \"spam_scam\", \"severity\": \"moderate\", \"confidence\": \"high\", \"needs_human\": true}, \"end\": \"blocked\"}\n{\"name\": \"counter-speech quoting a slur is not the slur\", \"input\": {\"post\": \"Someone just replied to me telling me to go back to my own country. That is exactly the kind of thing this sub says it removes.\", \"context\": \"reply in a moderation meta thread, the poster is reporting what was said to them\"}, \"expect\": {\"decision\": \"allow\", \"policy_category\": \"hate_speech\", \"severity\": \"none\", \"confidence\": \"high\", \"needs_human\": false}, \"end\": \"allowed\"}\n{\"name\": \"unsourced health claim, low confidence\", \"input\": {\"post\": \"The new vaccine batch was quietly recalled last week. My cousin works at the plant.\", \"context\": \"top-level post in a local news forum, no source linked\"}, \"expect\": {\"decision\": \"review\", \"policy_category\": \"misinformation\", \"severity\": \"moderate\", \"confidence\": \"low\", \"needs_human\": true}, \"end\": \"review_queue\"}\n{\"name\": \"sexual content allowed by the community it was posted in\", \"input\": {\"post\": \"Late night thread: post your hookup stories, text only, no images.\", \"context\": \"age-gated adults-only community whose rules permit explicit text\"}, \"expect\": {\"decision\": \"allow\", \"policy_category\": \"sexual_content\", \"severity\": \"low\", \"confidence\": \"high\", \"needs_human\": false}, \"end\": \"allowed\"}\n{\"name\": \"inconsistent decision is diverted, not obeyed\", \"input\": {\"post\": \"Everyone in that building deserves what is coming to them.\", \"context\": \"reply in a film discussion thread; no building and no person is named\"}, \"expect\": {\"decision\": \"review\", \"policy_category\": \"violent_threat\", \"severity\": \"moderate\", \"confidence\": \"low\", \"needs_human\": true, \"review_note\": \"No target and no building are named and the thread is about a film, so a human should read the surrounding replies before acting.\"}, \"end\": \"human_review\"}\n{\"name\": \"not enough context to judge\", \"input\": {\"post\": \"he said the thing about that group again\", \"context\": \"reply in a long thread; the post being referred to is not included\"}, \"expect\": {\"decision\": \"review\", \"policy_category\": \"none\", \"severity\": \"none\", \"confidence\": \"low\", \"needs_human\": true}, \"end\": \"review_queue\"}\n{\"name\": \"clean screen, but the confirm step is unsure\", \"input\": {\"post\": \"DM me and I will send you the file directly.\", \"context\": \"reply in a software support thread, with no link and no attachment\"}, \"expect\": {\"decision\": \"review\", \"policy_category\": \"none\", \"severity\": \"none\", \"confidence\": \"low\", \"needs_human\": true}, \"end\": \"review_queue\"}\n", "examples/content_moderation/fakes/script.json": "{\n \"screen step\": [\n \"{\\\"signal\\\": \\\"clean\\\"}\",\n \"{\\\"signal\\\": \\\"clean\\\"}\",\n \"{\\\"signal\\\": \\\"severe\\\"}\",\n \"{\\\"signal\\\": \\\"severe\\\"}\",\n \"{\\\"signal\\\": \\\"severe\\\"}\",\n \"{\\\"signal\\\": \\\"severe\\\"}\",\n \"{\\\"signal\\\": \\\"severe\\\"}\",\n \"{\\\"signal\\\": \\\"suspect\\\"}\",\n \"{\\\"signal\\\": \\\"suspect\\\"}\",\n \"{\\\"signal\\\": \\\"suspect\\\"}\",\n \"{\\\"signal\\\": \\\"suspect\\\"}\",\n \"{\\\"signal\\\": \\\"suspect\\\"}\",\n \"{\\\"signal\\\": \\\"clean\\\"}\"\n ],\n \"clear-post step\": [\n \"{\\\"decision\\\": \\\"allow\\\", \\\"policy_category\\\": \\\"none\\\", \\\"severity\\\": \\\"none\\\", \\\"confidence\\\": \\\"high\\\", \\\"needs_human\\\": false}\",\n \"{\\\"decision\\\": \\\"allow\\\", \\\"policy_category\\\": \\\"none\\\", \\\"severity\\\": \\\"none\\\", \\\"confidence\\\": \\\"high\\\", \\\"needs_human\\\": false}\",\n \"{\\\"decision\\\": \\\"review\\\", \\\"policy_category\\\": \\\"none\\\", \\\"severity\\\": \\\"none\\\", \\\"confidence\\\": \\\"low\\\", \\\"needs_human\\\": true}\"\n ],\n \"classify step\": [\n \"{\\\"policy_category\\\": \\\"harassment\\\", \\\"quoted_or_counter_speech\\\": false}\",\n \"{\\\"policy_category\\\": \\\"hate_speech\\\", \\\"quoted_or_counter_speech\\\": false}\",\n \"{\\\"policy_category\\\": \\\"violent_threat\\\", \\\"quoted_or_counter_speech\\\": false}\",\n \"{\\\"policy_category\\\": \\\"self_harm\\\", \\\"quoted_or_counter_speech\\\": false}\",\n \"{\\\"policy_category\\\": \\\"spam_scam\\\", \\\"quoted_or_counter_speech\\\": false}\",\n \"{\\\"policy_category\\\": \\\"hate_speech\\\", \\\"quoted_or_counter_speech\\\": true}\",\n \"{\\\"policy_category\\\": \\\"misinformation\\\", \\\"quoted_or_counter_speech\\\": false}\",\n \"{\\\"policy_category\\\": \\\"sexual_content\\\", \\\"quoted_or_counter_speech\\\": false}\",\n \"{\\\"policy_category\\\": \\\"violent_threat\\\", \\\"quoted_or_counter_speech\\\": false}\",\n \"{\\\"policy_category\\\": \\\"none\\\", \\\"quoted_or_counter_speech\\\": false}\"\n ],\n \"assess reasoning step\": [\n \"One named person is the target and the whole post is contempt aimed at them. The poster is saying it, not reporting it. Nothing here is ambiguous.\",\n \"The attack is on a group defined by where they were born, and the poster is arguing for their exclusion. This is authored, not quoted.\",\n \"It names a place and a day and is aimed at one person after a fight. That specificity is what makes a threat credible rather than venting.\",\n \"The poster is describing their own state in a community meant for exactly this. Removing it silently would cut off the person who needs reaching.\",\n \"Guaranteed returns, a private group and urgency are the standard shape of this. Nobody is harmed physically, but money is the point of it.\",\n \"The hateful line is quoted, and it is quoted in order to object to it. The poster is the target here, not the author.\",\n \"It could be true and it could be invented, and nothing here settles it. A recall claim spreads fast either way.\",\n \"The community is age-gated and its rules allow this, and the post asks for text rather than images. The venue is what settles it.\",\n \"Nothing is named, and the thread is about a film, so this may be a line from one. It may also not be.\",\n \"The post refers to something that was not shown to me. I cannot rate what I cannot read.\"\n ],\n \"assess step\": [\n \"{\\\"severity\\\": \\\"high\\\", \\\"confidence\\\": \\\"high\\\", \\\"rationale\\\": \\\"Sustained personal contempt aimed at one named member with no other purpose.\\\"}\",\n \"{\\\"severity\\\": \\\"high\\\", \\\"confidence\\\": \\\"high\\\", \\\"rationale\\\": \\\"Calls for exclusion of a group based on national origin, in the poster's own words.\\\"}\",\n \"{\\\"severity\\\": \\\"high\\\", \\\"confidence\\\": \\\"high\\\", \\\"rationale\\\": \\\"Names a place and a time and is directed at one person after a dispute.\\\"}\",\n \"{\\\"severity\\\": \\\"high\\\", \\\"confidence\\\": \\\"high\\\", \\\"rationale\\\": \\\"The poster describes their own suicidal thinking in a support community.\\\"}\",\n \"{\\\"severity\\\": \\\"moderate\\\", \\\"confidence\\\": \\\"high\\\", \\\"rationale\\\": \\\"Guaranteed returns plus a private group plus false scarcity is a standard financial scam.\\\"}\",\n \"{\\\"severity\\\": \\\"none\\\", \\\"confidence\\\": \\\"high\\\", \\\"rationale\\\": \\\"The poster is quoting abuse aimed at them in order to report it.\\\"}\",\n \"{\\\"severity\\\": \\\"moderate\\\", \\\"confidence\\\": \\\"low\\\", \\\"rationale\\\": \\\"An unsourced recall claim that may be true; nothing in the post allows a check.\\\"}\",\n \"{\\\"severity\\\": \\\"low\\\", \\\"confidence\\\": \\\"high\\\", \\\"rationale\\\": \\\"Adult text in an age-gated community whose own rules permit it.\\\"}\",\n \"{\\\"severity\\\": \\\"moderate\\\", \\\"confidence\\\": \\\"low\\\", \\\"rationale\\\": \\\"Menacing wording with no named target, in a thread where it may be a quotation.\\\"}\",\n \"{\\\"severity\\\": \\\"none\\\", \\\"confidence\\\": \\\"low\\\", \\\"rationale\\\": \\\"The post refers to content that was not provided, so nothing can be rated.\\\"}\"\n ],\n \"decide step\": [\n \"{\\\"decision\\\": \\\"block\\\", \\\"needs_human\\\": true}\",\n \"{\\\"decision\\\": \\\"block\\\", \\\"needs_human\\\": true}\",\n \"{\\\"decision\\\": \\\"block\\\", \\\"needs_human\\\": true}\",\n \"{\\\"decision\\\": \\\"review\\\", \\\"needs_human\\\": true}\",\n \"{\\\"decision\\\": \\\"block\\\", \\\"needs_human\\\": true}\",\n \"{\\\"decision\\\": \\\"allow\\\", \\\"needs_human\\\": false}\",\n \"{\\\"decision\\\": \\\"review\\\", \\\"needs_human\\\": true}\",\n \"{\\\"decision\\\": \\\"allow\\\", \\\"needs_human\\\": false}\",\n \"{\\\"decision\\\": \\\"review\\\", \\\"needs_human\\\": false}\",\n \"{\\\"decision\\\": \\\"review\\\", \\\"needs_human\\\": true}\"\n ],\n \"forced-review step\": [\n \"{\\\"decision\\\": \\\"review\\\", \\\"needs_human\\\": true, \\\"review_note\\\": \\\"No target and no building are named and the thread is about a film, so a human should read the surrounding replies before acting.\\\"}\"\n ]\n}\n", "examples/content_moderation/grammars/assess.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"severity\": {\"type\": \"string\", \"enum\": [\"none\", \"low\", \"moderate\", \"high\"]},\n \"confidence\": {\n \"type\": \"string\",\n \"description\": \"how sure you are of the severity, given how much context you were given\",\n \"enum\": [\"low\", \"medium\", \"high\"]\n },\n \"rationale\": {\"type\": \"string\"}\n },\n \"required\": [\"severity\", \"confidence\", \"rationale\"],\n \"additionalProperties\": false\n}\n", "examples/content_moderation/grammars/classify.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"policy_category\": {\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"harassment\",\n \"hate_speech\",\n \"violent_threat\",\n \"self_harm\",\n \"sexual_content\",\n \"spam_scam\",\n \"misinformation\"\n ]\n },\n \"quoted_or_counter_speech\": {\n \"type\": \"boolean\",\n \"description\": \"true when the poster is quoting, reporting or objecting to the content rather than authoring it\"\n }\n },\n \"required\": [\"policy_category\", \"quoted_or_counter_speech\"],\n \"additionalProperties\": false\n}\n", "examples/content_moderation/grammars/clear_post.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"decision\": {\n \"type\": \"string\",\n \"description\": \"This node cannot block. Unsure is 'review', never 'allow'.\",\n \"enum\": [\"allow\", \"review\"]\n },\n \"policy_category\": {\"type\": \"string\", \"enum\": [\"none\"]},\n \"severity\": {\"type\": \"string\", \"enum\": [\"none\"]},\n \"confidence\": {\"type\": \"string\", \"enum\": [\"low\", \"medium\", \"high\"]},\n \"needs_human\": {\"type\": \"boolean\"}\n },\n \"required\": [\"decision\", \"policy_category\", \"severity\", \"confidence\", \"needs_human\"],\n \"additionalProperties\": false\n}\n", "examples/content_moderation/grammars/decide.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"decision\": {\"type\": \"string\", \"enum\": [\"allow\", \"review\", \"block\"]},\n \"needs_human\": {\"type\": \"boolean\"}\n },\n \"required\": [\"decision\", \"needs_human\"],\n \"additionalProperties\": false\n}\n", "examples/content_moderation/grammars/force_review.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"decision\": {\n \"type\": \"string\",\n \"description\": \"One legal value. This node exists because something upstream could not be trusted, so it is not offered a choice.\",\n \"enum\": [\"review\"]\n },\n \"needs_human\": {\"type\": \"boolean\", \"enum\": [true]},\n \"review_note\": {\n \"type\": \"string\",\n \"description\": \"one short sentence a human moderator can act on\"\n }\n },\n \"required\": [\"decision\", \"needs_human\", \"review_note\"],\n \"additionalProperties\": false\n}\n", "examples/content_moderation/grammars/screen.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"signal\": {\n \"type\": \"string\",\n \"description\": \"clean = nothing a policy touches; suspect = worth a closer look; severe = looks like a serious violation\",\n \"enum\": [\"clean\", \"suspect\", \"severe\"]\n }\n },\n \"required\": [\"signal\"],\n \"additionalProperties\": false\n}\n", "examples/content_moderation/graph.yaml": "# screen ─┬─(signal: clean)─> clear_post ─┐\n# │ ├─> gate ─┬─(block)──> blocked\n# └──────────────────> classify │ ├─(review)─> review_queue\n# | │ └──────────> allowed\n# v │\n# assess ─> decide ────┘\n#\n# decide --assert fails--> force_review --> human_review\n# gate --assert fails--> force_review --> human_review\n#\n# Two locks, and neither one can open. `decide` may not commit a `block` that\n# names no policy category (verify-before-commit, so the bad record never\n# reaches state). `gate` then re-reads committed state and refuses any decision\n# other than `allow` that is not flagged for a human. Both failures divert to\n# `force_review`, whose grammar has exactly one legal decision, so the failure\n# mode of this pack is \"a human looks at it\", never \"it went out\".\n\nmax_steps: 12\n\nnodes:\n\n screen:\n description: One cheap look — is there anything here a policy could touch?\n type: generate\n max_tokens: 24\n\n clear_post:\n description: >-\n The confirm step for posts the screen found nothing in. It is a second\n look, not a rubber stamp: its grammar can say `review`, and it cannot say\n `block`, so the fast path can slow down but can never punish.\n type: generate\n max_tokens: 64\n\n classify:\n description: Name the policy area the post implicates, and whether it is quoted.\n type: generate\n max_tokens: 48\n\n assess:\n description: >-\n How bad is it, actually, given the context. This is the only node in the\n pack holding a judgement rather than a lookup — the same words are a\n violation from an author and a report from a bystander, and severity\n turns on which one this is. So it reasons into a scratchpad first and\n emits under its grammar second, and the scratchpad is thrown away.\n type: generate\n two_stage: true\n think_max_tokens: 160\n max_tokens: 128\n\n decide:\n description: Turn category plus severity plus confidence into one decision.\n type: generate\n max_tokens: 32\n # Model output is never trusted to police itself. A block is the one\n # decision that silences a person, so it must name the policy it is\n # enforcing. Checked before the commit, so a block with no category never\n # enters state, never reaches the output, and never conditions a retry.\n assert: decision != \"block\" or policy_category != \"none\"\n on_fail: force_review\n\n gate:\n description: >-\n The deterministic second lock, read from committed state. Anything that\n is not a plain allow must be flagged for a human; a model that decided\n `review` and then cleared the human flag is diverted, not obeyed.\n type: assert\n expr: needs_human == (decision != \"allow\")\n on_fail: force_review\n\n force_review:\n description: >-\n Where every doubt in this pack lands. Its grammar permits one decision\n and one value for the human flag, so the escalation cannot be talked out\n of by the model that caused it. It declares no `on_fail` on purpose: if\n even this record cannot be produced, the run stops with an error rather\n than returning a decision nobody verified.\n type: generate\n max_tokens: 96\n assert: decision == \"review\" and needs_human == true\n\n blocked:\n type: end\n output: [decision, policy_category, severity, confidence, needs_human, rationale]\n\n review_queue:\n type: end\n output: [decision, policy_category, severity, confidence, needs_human, rationale]\n\n allowed:\n type: end\n output: [decision, policy_category, severity, confidence, needs_human]\n\n human_review:\n type: end\n output: [decision, policy_category, confidence, needs_human, review_note]\n\nedges:\n\n - from: screen\n to: clear_post\n when: {signal: clean}\n\n - from: screen\n to: classify\n\n - from: clear_post\n to: gate\n\n - from: classify\n to: assess\n\n - from: assess\n to: decide\n\n - from: decide\n to: gate\n\n - from: gate\n to: blocked\n when: {decision: block}\n\n - from: gate\n to: review_queue\n when: {decision: review}\n\n - from: gate\n to: allowed\n\n - from: force_review\n to: human_review\n", "examples/content_moderation/manifest.yaml": "name: content_moderation\nversion: 1\nentry: screen\nmodel: fake:fakes/script.json\ndescription: >-\n Moderate a user post against a policy: screen, classify the policy area,\n assess severity in context, decide allow/review/block, then pass a\n deterministic gate before any of it is trusted.\n\n The pack is built to fail safe rather than fail open. Every route out of a\n doubt ends at a human, never at `allow`: `decide` may not commit a `block`\n that names no policy category, the `gate` node refuses any non-allow decision\n that is not flagged for a human, and both failures land on `force_review`,\n whose grammar admits no decision except `review`.\n\n The model below is a scripted stand-in, so the evalset scores offline with no\n GPU and no network. It replays the thirteen evalset cases in order and does\n not read the post, so a `stepmold run` of anything other than the first case will\n answer the first case. Point --model at a real backend to moderate real posts.\n", "examples/content_moderation/prompts/assess.think.txt": "You are the assess reasoning step of a content-moderation workflow.\n\nIn two or three sentences, weigh how serious this post really is. Consider who\nis targeted, whether the poster is saying it or reporting it, and what the\ncommunity it was posted in allows. Say plainly if you were not given enough to\ntell. Do not decide anything yet and do not answer in JSON.\n\nPolicy area: {policy_category}\nQuoting or objecting rather than saying it: {quoted_or_counter_speech}\nContext: {context}\nPost: {post}\n", "examples/content_moderation/prompts/assess.txt": "You are the assess step of a content-moderation workflow.\n\nRate this post.\n\n severity - none, low, moderate, or high\n confidence - low, medium, or high, based on how much context you were given\n rationale - one sentence, plain, no more than 25 words\n\nSomeone quoting or objecting to bad content is not committing the violation.\nIf the post refers to something you were not shown, your confidence is low.\n\nPolicy area: {policy_category}\nQuoting or objecting rather than saying it: {quoted_or_counter_speech}\nContext: {context}\nPost: {post}\n", "examples/content_moderation/prompts/classify.txt": "You are the classify step of a content-moderation workflow.\n\nName the one policy area this post is about. Do not judge how bad it is yet.\n\n harassment - insults, pile-ons, telling one person to go away\n hate_speech - attacks on people for who they are\n violent_threat - threats of physical harm\n self_harm - the poster talking about hurting or killing themselves\n sexual_content - sexual material\n spam_scam - money offers, fake returns, promotion, phishing\n misinformation - false claims about health, elections, or events\n none - no policy area fits, or you cannot tell\n\nAlso say whether the poster is quoting, reporting, or objecting to the content\nrather than saying it themselves. That is quoted_or_counter_speech.\n\nThe screen rated this post: {signal}\n\nContext: {context}\nPost: {post}\n", "examples/content_moderation/prompts/clear_post.txt": "You are the clear-post step of a content-moderation workflow.\n\nThe screen found nothing in this post. Take one more look and confirm.\n\n decision - allow if it is plainly fine, review if anything gives you pause\n confidence - how sure you are: low, medium, or high\n needs_human - true when decision is review, false when decision is allow\n\nYou cannot block here. If you think this post needs blocking, answer review.\n\nContext: {context}\nPost: {post}\n", "examples/content_moderation/prompts/decide.txt": "You are the decide step of a content-moderation workflow.\n\nTurn the ratings below into one decision.\n\n block - a real violation you are sure about, and the policy area is not none\n review - anything you are not sure about, and anything about self-harm\n allow - the post is fine as posted\n\n needs_human - true unless the decision is allow\n\nLow confidence is never a block. When you cannot decide, answer review.\n\nPolicy area: {policy_category}\nSeverity: {severity}\nConfidence: {confidence}\nReason: {rationale}\nPost: {post}\n", "examples/content_moderation/prompts/force_review.txt": "You are the forced-review step of a content-moderation workflow.\n\nA check upstream did not pass, so this post is going to a human. The decision\nis already review and a human is already needed; you are only writing the note.\n\n review_note - one short sentence telling the moderator what to look at\n\nPolicy area: {policy_category}\nContext: {context}\nPost: {post}\n", "examples/content_moderation/prompts/screen.txt": "You are the screen step of a content-moderation workflow.\n\nGive the post one quick look and say how much attention it needs:\n clean - ordinary post, nothing a policy would touch\n suspect - might touch a policy, or you cannot tell from what you were given\n severe - clearly looks like a serious violation\n\nIf you are unsure, answer suspect. Never answer clean just because the post is short.\n\nContext: {context}\nPost: {post}\n", "examples/incident_triage/evalset.jsonl": "{\"name\": \"INC-1042 paged\", \"input\": {\"alert_id\": \"INC-1042\", \"service\": \"checkout-api\", \"severity_raw\": \"SEV1\", \"message\": \"Checkout is returning 500 for all customers since 14:02\", \"error_text\": \"upstream payments-gw timed out after 30s\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"dependency_timeout\", \"confidence\": \"high\", \"severity\": \"p0\", \"blast_radius\": \"all_customers\", \"owner_team\": \"payments\", \"page_now\": true}, \"end\": \"paged\"}\n{\"name\": \"INC-1043 paged\", \"input\": {\"alert_id\": \"INC-1043\", \"service\": \"auth-gateway\", \"severity_raw\": \"critical\", \"message\": \"SSO login failing for every tenant after the 09:40 config push\", \"error_text\": \"OIDC discovery endpoint returned 404\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"config_error\", \"confidence\": \"high\", \"severity\": \"p0\", \"blast_radius\": \"all_customers\", \"owner_team\": \"identity\", \"page_now\": true}, \"end\": \"paged\"}\n{\"name\": \"INC-1044 tracked\", \"input\": {\"alert_id\": \"INC-1044\", \"service\": \"edge-router\", \"severity_raw\": \"warning\", \"message\": \"p99 latency at 1.8s in eu-west, one region degraded\", \"error_text\": \"connection pool exhausted\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"resource_exhaustion\", \"confidence\": \"medium\", \"severity\": \"p1\", \"blast_radius\": \"many_customers\", \"owner_team\": \"platform\", \"page_now\": false}, \"end\": \"tracked\"}\n{\"name\": \"INC-1045 tracked\", \"input\": {\"alert_id\": \"INC-1045\", \"service\": \"ledger-worker\", \"severity_raw\": \"sev-2\", \"message\": \"Ledger reconciliation is 40 minutes behind\", \"error_text\": \"queue backlog at 120k messages\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"resource_exhaustion\", \"confidence\": \"high\", \"severity\": \"p1\", \"blast_radius\": \"internal_only\", \"owner_team\": \"payments\", \"page_now\": false}, \"end\": \"tracked\"}\n{\"name\": \"INC-1046 queued\", \"input\": {\"alert_id\": \"INC-1046\", \"service\": \"etl-nightly\", \"severity_raw\": \"info\", \"message\": \"Nightly ETL finished 20 minutes late\", \"error_text\": \"\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"unknown\", \"confidence\": \"low\", \"severity\": \"p3\", \"blast_radius\": \"internal_only\", \"owner_team\": \"data-eng\", \"page_now\": false}, \"end\": \"queued\"}\n{\"name\": \"INC-1047 queued\", \"input\": {\"alert_id\": \"INC-1047\", \"service\": \"legacy-fax-bridge\", \"severity_raw\": \"notice\", \"message\": \"Fax delivery receipts are delayed on the legacy bridge\", \"error_text\": \"\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"unknown\", \"confidence\": \"low\", \"severity\": \"p3\", \"blast_radius\": \"internal_only\", \"owner_team\": \"unknown\", \"page_now\": false}, \"end\": \"queued\"}\n{\"name\": \"INC-1048 tracked\", \"input\": {\"alert_id\": \"INC-1048\", \"service\": \"checkout-api\", \"severity_raw\": \"P1\", \"message\": \"One merchant cannot complete checkout, card declined in a loop\", \"error_text\": \"3DS callback rejected by issuer\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"upstream_provider\", \"confidence\": \"medium\", \"severity\": \"p2\", \"blast_radius\": \"single_customer\", \"owner_team\": \"payments\", \"page_now\": false}, \"end\": \"tracked\"}\n{\"name\": \"INC-1049 tracked\", \"input\": {\"alert_id\": \"INC-1049\", \"service\": \"warehouse-sync\", \"severity_raw\": \"urgent!!!\", \"message\": \"Row counts mismatch after the backfill and the revenue table is wrong\", \"error_text\": \"duplicate primary keys in staging\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"data_corruption\", \"confidence\": \"high\", \"severity\": \"p1\", \"blast_radius\": \"internal_only\", \"owner_team\": \"data-eng\", \"page_now\": false}, \"end\": \"tracked\"}\n{\"name\": \"INC-1050 paged\", \"input\": {\"alert_id\": \"INC-1050\", \"service\": \"edge-router\", \"severity_raw\": \"page\", \"message\": \"All regions returning 502 since the 09:15 deploy\", \"error_text\": \"new build panics on startup\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"deploy_regression\", \"confidence\": \"high\", \"severity\": \"p0\", \"blast_radius\": \"all_customers\", \"owner_team\": \"platform\", \"page_now\": true}, \"end\": \"paged\"}\n{\"name\": \"INC-1051 tracked\", \"input\": {\"alert_id\": \"INC-1051\", \"service\": \"sso-bridge\", \"severity_raw\": \"\", \"message\": \"Password reset emails delayed by about 15 minutes\", \"error_text\": \"smtp provider is queueing\"}, \"expect\": {\"alert_status\": \"actionable\", \"cause_category\": \"upstream_provider\", \"confidence\": \"medium\", \"severity\": \"p2\", \"blast_radius\": \"many_customers\", \"owner_team\": \"identity\", \"page_now\": false}, \"end\": \"tracked\"}\n{\"name\": \"INC-1052 dropped\", \"input\": {\"alert_id\": \"INC-1052\", \"service\": \"checkout-api\", \"severity_raw\": \"critical\", \"message\": \"\", \"error_text\": \"\"}, \"expect\": {\"alert_status\": \"malformed\", \"defect\": \"no_message\"}, \"end\": \"dropped\"}\n{\"name\": \"INC-1053 dropped\", \"input\": {\"alert_id\": \"INC-1053\", \"service\": \"\", \"severity_raw\": \"sev1\", \"message\": \"something broke, please look\", \"error_text\": \"\"}, \"expect\": {\"alert_status\": \"malformed\", \"defect\": \"missing_service\"}, \"end\": \"dropped\"}\n{\"name\": \"INC-1054 dropped\", \"input\": {\"alert_id\": \"INC-1054\", \"service\": \"monitoring-canary\", \"severity_raw\": \"critical\", \"message\": \"This is a test alert, please ignore. Synthetic canary firing.\", \"error_text\": \"\"}, \"expect\": {\"alert_status\": \"malformed\", \"defect\": \"not_an_alert\"}, \"end\": \"dropped\"}\n", "examples/incident_triage/fakes/script.json": "{\n \"Task: intake check\\nAlert: INC-1042\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1042\": \"{\\\"cause_category\\\": \\\"dependency_timeout\\\", \\\"confidence\\\": \\\"high\\\"}\",\n \"Task: severity notes\\nAlert: INC-1042\": \"Every customer trying to pay is failing right now, so this is as wide as it gets. Money is being lost each minute. The vendor said SEV1 and for once that matches.\",\n \"Task: severity call\\nAlert: INC-1042\": \"{\\\"severity\\\": \\\"p0\\\", \\\"blast_radius\\\": \\\"all_customers\\\", \\\"reason\\\": \\\"Checkout is down for every customer and payments are failing.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1042\": \"{\\\"owner_team\\\": \\\"payments\\\", \\\"page_now\\\": true, \\\"summary\\\": \\\"Checkout returning 500 for all customers after payments-gw timeouts.\\\"}\",\n \"Task: intake check\\nAlert: INC-1043\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1043\": \"{\\\"cause_category\\\": \\\"config_error\\\", \\\"confidence\\\": \\\"high\\\"}\",\n \"Task: severity notes\\nAlert: INC-1043\": \"Nobody can log in at any tenant, so all customers are blocked out of the product. No money moves but the whole thing is unusable. A config push right before it started is the obvious trigger.\",\n \"Task: severity call\\nAlert: INC-1043\": \"{\\\"severity\\\": \\\"p0\\\", \\\"blast_radius\\\": \\\"all_customers\\\", \\\"reason\\\": \\\"No tenant can log in at all since the config push.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1043\": \"{\\\"owner_team\\\": \\\"identity\\\", \\\"page_now\\\": true, \\\"summary\\\": \\\"SSO login broken for every tenant after a bad OIDC config push.\\\"}\",\n \"Task: intake check\\nAlert: INC-1044\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1044\": \"{\\\"cause_category\\\": \\\"resource_exhaustion\\\", \\\"confidence\\\": \\\"medium\\\"}\",\n \"Task: severity notes\\nAlert: INC-1044\": \"One region is slow, not down, so many customers see a worse product but can still use it. No money or data at risk. The vendor called it a warning, which understates a whole region.\",\n \"Task: severity call\\nAlert: INC-1044\": \"{\\\"severity\\\": \\\"p1\\\", \\\"blast_radius\\\": \\\"many_customers\\\", \\\"reason\\\": \\\"A whole region is degraded for customers, though still serving.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1044\": \"{\\\"owner_team\\\": \\\"platform\\\", \\\"page_now\\\": false, \\\"summary\\\": \\\"eu-west latency at 1.8s from an exhausted edge-router connection pool.\\\"}\",\n \"Task: intake check\\nAlert: INC-1045\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1045\": \"{\\\"cause_category\\\": \\\"resource_exhaustion\\\", \\\"confidence\\\": \\\"high\\\"}\",\n \"Task: severity notes\\nAlert: INC-1045\": \"Customers see nothing yet, but the ledger is drifting from reality and that is money data. Only staff are affected today. The backlog is growing, so it will not fix itself.\",\n \"Task: severity call\\nAlert: INC-1045\": \"{\\\"severity\\\": \\\"p1\\\", \\\"blast_radius\\\": \\\"internal_only\\\", \\\"reason\\\": \\\"Financial data is drifting behind and the backlog keeps growing.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1045\": \"{\\\"owner_team\\\": \\\"payments\\\", \\\"page_now\\\": false, \\\"summary\\\": \\\"Ledger reconciliation 40 minutes behind on a 120k message backlog.\\\"}\",\n \"Task: intake check\\nAlert: INC-1046\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1046\": \"{\\\"cause_category\\\": \\\"unknown\\\", \\\"confidence\\\": \\\"low\\\"}\",\n \"Task: severity notes\\nAlert: INC-1046\": \"The job finished, just late, and there is no error text to say why. No customer sees this and nothing is blocked. The vendor said info and that looks right.\",\n \"Task: severity call\\nAlert: INC-1046\": \"{\\\"severity\\\": \\\"p3\\\", \\\"blast_radius\\\": \\\"internal_only\\\", \\\"reason\\\": \\\"The job completed, only late, with no customer impact.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1046\": \"{\\\"owner_team\\\": \\\"data-eng\\\", \\\"page_now\\\": false, \\\"summary\\\": \\\"Nightly ETL completed twenty minutes later than usual.\\\"}\",\n \"Task: intake check\\nAlert: INC-1047\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1047\": \"{\\\"cause_category\\\": \\\"unknown\\\", \\\"confidence\\\": \\\"low\\\"}\",\n \"Task: severity notes\\nAlert: INC-1047\": \"Receipts are late on a legacy path that only staff read. No error text, no deadline, nobody blocked. This can wait for working hours.\",\n \"Task: severity call\\nAlert: INC-1047\": \"{\\\"severity\\\": \\\"p3\\\", \\\"blast_radius\\\": \\\"internal_only\\\", \\\"reason\\\": \\\"Delayed receipts on a legacy internal path with no deadline.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1047\": \"{\\\"owner_team\\\": \\\"unknown\\\", \\\"page_now\\\": false, \\\"summary\\\": \\\"Fax delivery receipts delayed on the legacy bridge.\\\"}\",\n \"Task: intake check\\nAlert: INC-1048\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1048\": \"{\\\"cause_category\\\": \\\"upstream_provider\\\", \\\"confidence\\\": \\\"medium\\\"}\",\n \"Task: severity notes\\nAlert: INC-1048\": \"This is one merchant, not the platform, and the rejection comes from their issuer rather than from us. Real money is not moving for them, but everyone else is fine. The vendor's P1 is too high for a single account.\",\n \"Task: severity call\\nAlert: INC-1048\": \"{\\\"severity\\\": \\\"p2\\\", \\\"blast_radius\\\": \\\"single_customer\\\", \\\"reason\\\": \\\"A single merchant is blocked by an issuer-side 3DS rejection.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1048\": \"{\\\"owner_team\\\": \\\"payments\\\", \\\"page_now\\\": false, \\\"summary\\\": \\\"One merchant stuck in a decline loop after issuer rejects 3DS callback.\\\"}\",\n \"Task: intake check\\nAlert: INC-1049\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1049\": \"{\\\"cause_category\\\": \\\"data_corruption\\\", \\\"confidence\\\": \\\"high\\\"}\",\n \"Task: severity notes\\nAlert: INC-1049\": \"The revenue table is wrong, which is data we report on, so this is worse than it looks. Only staff touch it today, no customer is blocked. Shouting in the severity field does not make it customer-facing.\",\n \"Task: severity call\\nAlert: INC-1049\": \"{\\\"severity\\\": \\\"p1\\\", \\\"blast_radius\\\": \\\"internal_only\\\", \\\"reason\\\": \\\"Revenue data is corrupted by duplicate keys from the backfill.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1049\": \"{\\\"owner_team\\\": \\\"data-eng\\\", \\\"page_now\\\": false, \\\"summary\\\": \\\"Backfill duplicated primary keys and left the revenue table wrong.\\\"}\",\n \"Task: intake check\\nAlert: INC-1050\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1050\": \"{\\\"cause_category\\\": \\\"deploy_regression\\\", \\\"confidence\\\": \\\"high\\\"}\",\n \"Task: severity notes\\nAlert: INC-1050\": \"Every region is returning errors, so every customer is down. It began at a deploy and the new build will not even start. This is a total outage.\",\n \"Task: severity call\\nAlert: INC-1050\": \"{\\\"severity\\\": \\\"p0\\\", \\\"blast_radius\\\": \\\"all_customers\\\", \\\"reason\\\": \\\"Every region is down since the deploy and the build will not start.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1050\": \"{\\\"owner_team\\\": \\\"platform\\\", \\\"page_now\\\": true, \\\"summary\\\": \\\"All regions returning 502 after the 09:15 deploy panics on startup.\\\"}\",\n \"Task: intake check\\nAlert: INC-1051\": \"{\\\"alert_status\\\": \\\"actionable\\\", \\\"defect\\\": \\\"none\\\"}\",\n \"Task: cause category\\nAlert: INC-1051\": \"{\\\"cause_category\\\": \\\"upstream_provider\\\", \\\"confidence\\\": \\\"medium\\\"}\",\n \"Task: severity notes\\nAlert: INC-1051\": \"Anyone resetting a password waits, which is many customers but not all of them, and the mail does arrive. The queueing is at the mail provider, not with us. No severity was supplied at all, so the message has to carry the call.\",\n \"Task: severity call\\nAlert: INC-1051\": \"{\\\"severity\\\": \\\"p2\\\", \\\"blast_radius\\\": \\\"many_customers\\\", \\\"reason\\\": \\\"Resets are slow but still arriving, and the delay is at the provider.\\\"}\",\n \"Task: route and summarise\\nAlert: INC-1051\": \"{\\\"owner_team\\\": \\\"identity\\\", \\\"page_now\\\": false, \\\"summary\\\": \\\"Password reset emails delayed about fifteen minutes by the smtp provider.\\\"}\",\n \"Task: intake check\\nAlert: INC-1052\": \"{\\\"alert_status\\\": \\\"malformed\\\", \\\"defect\\\": \\\"no_message\\\"}\",\n \"Task: intake check\\nAlert: INC-1053\": \"{\\\"alert_status\\\": \\\"malformed\\\", \\\"defect\\\": \\\"missing_service\\\"}\",\n \"Task: intake check\\nAlert: INC-1054\": \"{\\\"alert_status\\\": \\\"malformed\\\", \\\"defect\\\": \\\"not_an_alert\\\"}\"\n}\n", "examples/incident_triage/grammars/cause.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"cause_category\": {\n \"type\": \"string\",\n \"enum\": [\n \"dependency_timeout\",\n \"deploy_regression\",\n \"resource_exhaustion\",\n \"config_error\",\n \"upstream_provider\",\n \"data_corruption\",\n \"unknown\"\n ]\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\"high\", \"medium\", \"low\"]\n }\n },\n \"required\": [\"cause_category\", \"confidence\"],\n \"additionalProperties\": false\n}\n", "examples/incident_triage/grammars/intake.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"alert_status\": {\n \"type\": \"string\",\n \"enum\": [\"actionable\", \"malformed\"]\n },\n \"defect\": {\n \"type\": \"string\",\n \"enum\": [\"none\", \"no_message\", \"missing_service\", \"not_an_alert\"]\n }\n },\n \"required\": [\"alert_status\", \"defect\"],\n \"additionalProperties\": false\n}\n", "examples/incident_triage/grammars/route.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"owner_team\": {\n \"type\": \"string\",\n \"enum\": [\"payments\", \"platform\", \"identity\", \"data-eng\", \"unknown\"]\n },\n \"page_now\": {\"type\": \"boolean\"},\n \"summary\": {\"type\": \"string\"}\n },\n \"required\": [\"owner_team\", \"page_now\", \"summary\"],\n \"additionalProperties\": false\n}\n", "examples/incident_triage/grammars/severity.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"severity\": {\n \"type\": \"string\",\n \"enum\": [\"p0\", \"p1\", \"p2\", \"p3\"]\n },\n \"blast_radius\": {\n \"type\": \"string\",\n \"enum\": [\"all_customers\", \"many_customers\", \"single_customer\", \"internal_only\"]\n },\n \"reason\": {\"type\": \"string\"}\n },\n \"required\": [\"severity\", \"blast_radius\", \"reason\"],\n \"additionalProperties\": false\n}\n", "examples/incident_triage/graph.yaml": "# intake -> cause -> severity -> route -> (paged | queued | tracked)\n# \\-> dropped (nothing triageable in the payload)\n#\n# Each node has one narrow job and one grammar. No node ever chooses what happens\n# next: the two `when` edges below are the whole routing policy, written as data.\n\nmax_steps: 12\n\nnodes:\n intake:\n type: generate\n description: Is this payload an incident we can triage at all?\n max_tokens: 48\n # A malformed verdict must name the defect and an actionable one must not, so\n # the pair can never disagree. Checked before anything is committed.\n assert: (alert_status == \"actionable\" and defect == \"none\") or (alert_status == \"malformed\" and defect != \"none\")\n on_fail: unreadable\n\n cause:\n type: generate\n description: One suspected cause category, from the fixed list.\n max_tokens: 64\n\n severity:\n type: generate\n description: Normalise the vendor severity string against the real blast radius.\n # The one node with a judgement call in it. The raw severity is vendor text\n # (\"SEV1\", \"page\", \"urgent!!!\", or missing entirely) and it routinely disagrees\n # with the impact in the message — a \"P1\" that hit one merchant is a p2, an\n # \"info\" that took every region down is a p0. Reconciling the two is reasoning,\n # so it gets an unconstrained think pass before the constrained emit\n # (docs/ARCHITECTURE.md, Bug 2). The scratchpad is thrown away.\n two_stage: true\n think_max_tokens: 160\n max_tokens: 96\n\n route:\n type: generate\n description: Owning team, page-now decision, one-line summary.\n max_tokens: 128\n # Deterministic invariant: someone is woken up exactly when the severity says\n # p0, never on the model's enthusiasm.\n assert: page_now == (severity == \"p0\")\n on_fail: needs_human\n\n paged:\n type: end\n output: [alert_status, cause_category, confidence, severity, blast_radius, owner_team, page_now, summary]\n\n queued:\n type: end\n output: [alert_status, cause_category, confidence, severity, blast_radius, owner_team, page_now, summary]\n\n tracked:\n type: end\n output: [alert_status, cause_category, confidence, severity, blast_radius, owner_team, page_now, summary]\n\n dropped:\n type: end\n output: [alert_id, service, alert_status, defect]\n\n # Reached only when a node burns its retry ladder. `unreadable` fires before\n # anything is committed, so it can only hand back the payload it was given.\n unreadable:\n type: end\n output: [alert_id, service]\n\n needs_human:\n type: end\n output: [alert_id, service, severity, blast_radius, cause_category]\n\nedges:\n - from: intake\n to: dropped\n when: {alert_status: malformed}\n\n - from: intake\n to: cause\n\n - from: cause\n to: severity\n\n - from: severity\n to: route\n\n - from: route\n to: paged\n when: {severity: p0}\n\n - from: route\n to: queued\n when: {severity: p3}\n\n - from: route\n to: tracked\n", "examples/incident_triage/manifest.yaml": "name: incident_triage\nversion: 1\nentry: intake\nmodel: fake:fakes/script.json\ndescription: >-\n Four-node production-incident triage: intake check, cause category, normalised\n severity, then route and summarise. p0 pages, p3 queues, everything else is\n tracked; a payload that cannot be triaged is dropped before any work is spent\n on it.\n\n The model below is a scripted stand-in, so the evalset scores offline with no\n GPU and no network. Unlike a positional script it is keyed on the alert id, so\n `stepmold run` answers whichever of the thirteen alerts you hand it, not just the\n first. Point --model at a real backend to triage real alerts.\n", "examples/incident_triage/prompts/cause.txt": "Task: cause category\nAlert: {alert_id}\n\nYou are the cause step of an incident-alert triage workflow. Pick the one cause\ncategory the error text and message point at:\n dependency_timeout - an internal service or database did not answer in time\n deploy_regression - it started at a release, restart or rollout\n resource_exhaustion - pool, disk, memory, quota or queue backlog is full\n config_error - a setting, flag, key or route was changed or is wrong\n upstream_provider - a third party we do not run is failing or slow\n data_corruption - wrong, duplicated or missing rows in the data itself\n unknown - the alert does not say enough to choose\n\nThen say how sure you are: high, medium, or low. Use low whenever you picked\nunknown.\n\nService: {service}\nMessage: {message}\nError: {error_text}\n", "examples/incident_triage/prompts/intake.txt": "Task: intake check\nAlert: {alert_id}\n\nYou are the intake step of an incident-alert triage workflow. Decide one thing:\ncan this alert be triaged, or not?\n\nMark it malformed when any of these is true, and name the defect:\n no_message - the message field is empty, so there is nothing to triage\n missing_service - the service field is empty, so nobody can own it\n not_an_alert - it is a test, canary, heartbeat or drill, not an incident\n\nOtherwise mark it actionable and use defect \"none\".\n\nAn unfamiliar service name is still actionable. Only an empty one is not.\n\nService: {service}\nRaw severity: {severity_raw}\nMessage: {message}\nError: {error_text}\n", "examples/incident_triage/prompts/route.txt": "Task: route and summarise\nAlert: {alert_id}\n\nYou are the routing step of an incident-alert triage workflow.\n\nPick the owning team from the service name:\n payments - checkout-api, ledger-worker\n platform - edge-router, search-index\n identity - auth-gateway, sso-bridge\n data-eng - etl-nightly, warehouse-sync\n unknown - any service not named above\n\nSet page_now to true only when the severity is p0. Otherwise false.\n\nWrite a summary: one sentence, plain, no more than 20 words.\n\nService: {service}\nSeverity: {severity}\nBlast radius: {blast_radius}\nSuspected cause: {cause_category}\nMessage: {message}\n", "examples/incident_triage/prompts/severity.think.txt": "Task: severity notes\nAlert: {alert_id}\n\nYou are the severity reasoning step of an incident-alert triage workflow.\n\nIn two or three sentences, weigh how bad this is. Say who is affected: every\ncustomer, many customers, one customer, or only staff. Say whether money or\ndata is at risk right now. Note whether the raw severity string matches what\nthe message actually describes.\n\nDo not decide the severity yet and do not answer in JSON.\n\nRaw severity: {severity_raw}\nSuspected cause: {cause_category}\nMessage: {message}\nError: {error_text}\n", "examples/incident_triage/prompts/severity.txt": "Task: severity call\nAlert: {alert_id}\n\nYou are the severity step of an incident-alert triage workflow. Assign one\nnormalised severity:\n p0 - customer-facing and broken now for everyone, or money is being lost\n p1 - a real customer-facing fault, but not everyone, or data is drifting\n p2 - degraded but working, or one customer is affected\n p3 - no customer impact today, and no deadline\n\nAnd one blast radius: all_customers, many_customers, single_customer, or\ninternal_only.\n\nThe raw severity below is the vendor's guess. Trust the message over it.\n\nGive a one-sentence reason.\n\nRaw severity: {severity_raw}\nSuspected cause: {cause_category}\nMessage: {message}\nError: {error_text}\n", "examples/invoice_extract/evalset.jsonl": "{\"name\": \"clean USD invoice, due next month\", \"input\": {\"invoice_text\": \"ACME SUPPLIES INC.\\n120 Foundry Road, Newark NJ\\nInvoice INV-1001\\nDate: 2026-08-01 Due: 2026-09-30\\nBill to: Northgate Retail Ltd\\n1 x industrial shelving kit ............ $1,000.00\\nSubtotal ............................... $1,000.00\\nSales tax (8%) ......................... $80.00\\nTotal due .............................. $1,080.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"ACME SUPPLIES INC.\", \"invoice_number\": \"INV-1001\", \"currency\": \"USD\", \"subtotal\": 1000.0, \"tax_amount\": 80.0, \"total_amount\": 1080.0, \"due_date\": \"2026-09-30\", \"needs_review\": false, \"review_reason\": \"none\"}, \"end\": \"accepted\"}\n{\"name\": \"EUR invoice, no subtotal line\", \"input\": {\"invoice_text\": \"Nordwind GmbH\\nInvoice RE-2026-114\\nIssued: 2026-08-10 Payment due: 2026-09-15\\nConsulting services, August 2026 EUR 249.50\\nVAT 19% EUR 47.41\\nAmount payable EUR 296.91\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Nordwind GmbH\", \"invoice_number\": \"RE-2026-114\", \"currency\": \"EUR\", \"subtotal\": 249.5, \"tax_amount\": 47.41, \"total_amount\": 296.91, \"due_date\": \"2026-09-15\", \"needs_review\": false, \"review_reason\": \"none\"}, \"end\": \"accepted\"}\n{\"name\": \"GBP invoice, due on receipt so no date\", \"input\": {\"invoice_text\": \"Thistle Print Ltd\\nINVOICE TP-88\\nDate: 2026-08-18\\nTerms: due on receipt\\n500 leaflets, full colour GBP 120.00\\nVAT @ 20% GBP 24.00\\nTOTAL GBP 144.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Thistle Print Ltd\", \"invoice_number\": \"TP-88\", \"currency\": \"GBP\", \"subtotal\": 120.0, \"tax_amount\": 24.0, \"total_amount\": 144.0, \"due_date\": null, \"needs_review\": false, \"review_reason\": \"none\"}, \"end\": \"accepted\"}\n{\"name\": \"zero-rated export, tax is zero\", \"input\": {\"invoice_text\": \"Blue Harbor Freight\\nInvoice BH-4521\\nDate: 2026-08-05 Due date: 2026-10-01\\nOcean freight, container BHF-9912 ....... $500.00\\nTax: none (zero-rated export)\\nTotal ................................... $500.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Blue Harbor Freight\", \"invoice_number\": \"BH-4521\", \"currency\": \"USD\", \"subtotal\": 500.0, \"tax_amount\": 0.0, \"total_amount\": 500.0, \"due_date\": \"2026-10-01\", \"needs_review\": false, \"review_reason\": \"none\"}, \"end\": \"accepted\"}\n{\"name\": \"thousands separators in every amount\", \"input\": {\"invoice_text\": \"Kestrel Systems\\nInvoice number: KS-2026-0042\\nInvoice date: 2026-08-12 Due: 2026-09-01\\nAnnual licence renewal, 250 seats ..... $12,500.00\\nSubtotal .............................. $12,500.00\\nState tax ............................. $1,000.00\\nTotal ................................. $13,500.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Kestrel Systems\", \"invoice_number\": \"KS-2026-0042\", \"currency\": \"USD\", \"subtotal\": 12500.0, \"tax_amount\": 1000.0, \"total_amount\": 13500.0, \"due_date\": \"2026-09-01\", \"needs_review\": false, \"review_reason\": \"none\"}, \"end\": \"accepted\"}\n{\"name\": \"edge: subtotal plus tax does not equal the total\", \"input\": {\"invoice_text\": \"Ridgeline Tools\\nInvoice RT-7781\\nDate: 2026-08-14 Due: 2026-09-14\\nReplacement drill bits, box of 12 ...... $100.00\\nSubtotal ............................... $100.00\\nTax .................................... $8.00\\nTOTAL DUE .............................. $118.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Ridgeline Tools\", \"invoice_number\": \"RT-7781\", \"currency\": \"USD\", \"subtotal\": 100.0, \"tax_amount\": 8.0, \"total_amount\": 118.0, \"due_date\": \"2026-09-14\", \"needs_review\": true, \"review_reason\": \"totals_mismatch\"}, \"end\": \"flagged\"}\n{\"name\": \"edge: currency the business does not settle\", \"input\": {\"invoice_text\": \"Karachi Steel Works (Pvt) Ltd\\nInvoice KSW-3390\\nDate: 2026-08-09 Due: 2026-09-20\\nMild steel sheet, 2 tonne ......... PKR 50,000.00\\nSales tax 18% ..................... PKR 9,000.00\\nTotal payable ..................... PKR 59,000.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Karachi Steel Works (Pvt) Ltd\", \"invoice_number\": \"KSW-3390\", \"currency\": \"PKR\", \"subtotal\": 50000.0, \"tax_amount\": 9000.0, \"total_amount\": 59000.0, \"due_date\": \"2026-09-20\", \"needs_review\": true, \"review_reason\": \"unexpected_currency\"}, \"end\": \"flagged\"}\n{\"name\": \"edge: due date already gone by\", \"input\": {\"invoice_text\": \"Orchard Paper Co\\nInvoice OP-2211\\nDate: 2026-04-01 Due: 2026-05-01\\nCopier paper, 40 boxes ................. $300.00\\nSubtotal ............................... $300.00\\nTax (8%) ............................... $24.00\\nTotal .................................. $324.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Orchard Paper Co\", \"invoice_number\": \"OP-2211\", \"currency\": \"USD\", \"subtotal\": 300.0, \"tax_amount\": 24.0, \"total_amount\": 324.0, \"due_date\": \"2026-05-01\", \"needs_review\": true, \"review_reason\": \"past_due\"}, \"end\": \"flagged\"}\n{\"name\": \"edge: due exactly today is not past due\", \"input\": {\"invoice_text\": \"Vale Logistics\\nInvoice VL-9001\\nDate: 2026-07-24 Due: 2026-08-24\\nCourier services, July ................. $200.00\\nSubtotal ............................... $200.00\\nTax .................................... $16.00\\nTotal .................................. $216.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Vale Logistics\", \"invoice_number\": \"VL-9001\", \"currency\": \"USD\", \"subtotal\": 200.0, \"tax_amount\": 16.0, \"total_amount\": 216.0, \"due_date\": \"2026-08-24\", \"needs_review\": false, \"review_reason\": \"none\"}, \"end\": \"accepted\"}\n{\"name\": \"edge: no invoice number printed anywhere\", \"input\": {\"invoice_text\": \"Corner Cafe Catering\\nCatering for the staff offsite\\nDate: 2026-08-06 Due: 2026-09-05\\nSandwich platters, 8 ................... $80.00\\nSubtotal ............................... $80.00\\nTax .................................... $6.40\\nTotal .................................. $86.40\\nThanks! - Dee\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Corner Cafe Catering\", \"invoice_number\": \"unknown\", \"currency\": \"USD\", \"subtotal\": 80.0, \"tax_amount\": 6.4, \"total_amount\": 86.4, \"due_date\": \"2026-09-05\", \"needs_review\": true, \"review_reason\": \"missing_identifier\"}, \"end\": \"flagged\"}\n{\"name\": \"edge: invoice says it revises an earlier one\", \"input\": {\"invoice_text\": \"Halden Metalworks\\nInvoice HM-6620 *** REVISED ***\\nThis invoice replaces HM-6604. Do not pay both.\\nDate: 2026-08-11 Due: 2026-09-12\\nFabrication, batch 22 .................. $900.00\\nSubtotal ............................... $900.00\\nTax .................................... $72.00\\nTotal .................................. $972.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Halden Metalworks\", \"invoice_number\": \"HM-6620\", \"currency\": \"USD\", \"subtotal\": 900.0, \"tax_amount\": 72.0, \"total_amount\": 972.0, \"due_date\": \"2026-09-12\", \"needs_review\": true, \"review_reason\": \"unusual_document\"}, \"end\": \"flagged\"}\n{\"name\": \"edge: tax line too large to be a tax line\", \"input\": {\"invoice_text\": \"Summit Consulting LLC\\nInvoice SC-1188\\nDate: 2026-08-15 Due: 2026-09-18\\nAdvisory retainer, August .............. $400.00\\nSubtotal ............................... $400.00\\nTax .................................... $160.00\\nTotal .................................. $560.00\", \"today\": \"2026-08-24\"}, \"expect\": {\"supplier_name\": \"Summit Consulting LLC\", \"invoice_number\": \"SC-1188\", \"currency\": \"USD\", \"subtotal\": 400.0, \"tax_amount\": 160.0, \"total_amount\": 560.0, \"due_date\": \"2026-09-18\", \"needs_review\": true, \"review_reason\": \"tax_out_of_range\"}, \"end\": \"flagged\"}\n", "examples/invoice_extract/fakes/script.json": "{\n \"the header step\": [\n \"{\\\"supplier_name\\\": \\\"ACME SUPPLIES INC.\\\", \\\"invoice_number\\\": \\\"INV-1001\\\", \\\"currency\\\": \\\"USD\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Nordwind GmbH\\\", \\\"invoice_number\\\": \\\"RE-2026-114\\\", \\\"currency\\\": \\\"EUR\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Thistle Print Ltd\\\", \\\"invoice_number\\\": \\\"TP-88\\\", \\\"currency\\\": \\\"GBP\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Blue Harbor Freight\\\", \\\"invoice_number\\\": \\\"BH-4521\\\", \\\"currency\\\": \\\"USD\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Kestrel Systems\\\", \\\"invoice_number\\\": \\\"KS-2026-0042\\\", \\\"currency\\\": \\\"USD\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Ridgeline Tools\\\", \\\"invoice_number\\\": \\\"RT-7781\\\", \\\"currency\\\": \\\"USD\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Karachi Steel Works (Pvt) Ltd\\\", \\\"invoice_number\\\": \\\"KSW-3390\\\", \\\"currency\\\": \\\"PKR\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Orchard Paper Co\\\", \\\"invoice_number\\\": \\\"OP-2211\\\", \\\"currency\\\": \\\"USD\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Vale Logistics\\\", \\\"invoice_number\\\": \\\"VL-9001\\\", \\\"currency\\\": \\\"USD\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Corner Cafe Catering\\\", \\\"invoice_number\\\": \\\"unknown\\\", \\\"currency\\\": \\\"USD\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Halden Metalworks\\\", \\\"invoice_number\\\": \\\"HM-6620\\\", \\\"currency\\\": \\\"USD\\\"}\",\n \"{\\\"supplier_name\\\": \\\"Summit Consulting LLC\\\", \\\"invoice_number\\\": \\\"SC-1188\\\", \\\"currency\\\": \\\"USD\\\"}\"\n ],\n \"the amounts step\": [\n \"{\\\"subtotal\\\": 1000.0, \\\"tax_amount\\\": 80.0, \\\"total_amount\\\": 1080.0}\",\n \"{\\\"subtotal\\\": 249.5, \\\"tax_amount\\\": 47.41, \\\"total_amount\\\": 296.91}\",\n \"{\\\"subtotal\\\": 120.0, \\\"tax_amount\\\": 24.0, \\\"total_amount\\\": 144.0}\",\n \"{\\\"subtotal\\\": 500.0, \\\"tax_amount\\\": 0.0, \\\"total_amount\\\": 500.0}\",\n \"{\\\"subtotal\\\": 12500.0, \\\"tax_amount\\\": 1000.0, \\\"total_amount\\\": 13500.0}\",\n \"{\\\"subtotal\\\": 100.0, \\\"tax_amount\\\": 8.0, \\\"total_amount\\\": 118.0}\",\n \"{\\\"subtotal\\\": 50000.0, \\\"tax_amount\\\": 9000.0, \\\"total_amount\\\": 59000.0}\",\n \"{\\\"subtotal\\\": 300.0, \\\"tax_amount\\\": 24.0, \\\"total_amount\\\": 324.0}\",\n \"{\\\"subtotal\\\": 200.0, \\\"tax_amount\\\": 16.0, \\\"total_amount\\\": 216.0}\",\n \"{\\\"subtotal\\\": 80.0, \\\"tax_amount\\\": 6.4, \\\"total_amount\\\": 86.4}\",\n \"{\\\"subtotal\\\": 900.0, \\\"tax_amount\\\": 72.0, \\\"total_amount\\\": 972.0}\",\n \"{\\\"subtotal\\\": 400.0, \\\"tax_amount\\\": 160.0, \\\"total_amount\\\": 560.0}\"\n ],\n \"the due-date step\": [\n \"{\\\"due_date\\\": \\\"2026-09-30\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-09-15\\\"}\",\n \"{\\\"due_date\\\": null}\",\n \"{\\\"due_date\\\": \\\"2026-10-01\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-09-01\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-09-14\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-09-20\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-05-01\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-08-24\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-09-05\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-09-12\\\"}\",\n \"{\\\"due_date\\\": \\\"2026-09-18\\\"}\"\n ],\n \"the review reasoning step\": [\n \"The supplier and the invoice number are both printed clearly and the document does not describe itself as anything unusual. Nothing here needs a person.\",\n \"There is no line labelled subtotal, but the single service line is the amount before VAT. Supplier and invoice number are both legible and the invoice makes no odd claim about itself.\",\n \"Due on receipt is a term, not a printed date, so there is no due date to be past. The supplier and the number are both there and the document is an ordinary invoice.\",\n \"A zero tax line is normal on a zero-rated export and the totals are consistent with it. Both identifiers are printed, so there is nothing for a person to settle.\",\n \"The amounts are large but a 250-seat renewal explains them, and the tax is a plausible share. Supplier and invoice number are both printed, so nothing is unresolved.\",\n \"The due date is today, which is the last day it can be paid on time rather than a missed one. Everything else on the document is ordinary and both identifiers are present.\",\n \"The supplier is named but there is no invoice reference anywhere on the page, so nothing here can be matched against a purchase order or checked for a duplicate payment later.\",\n \"The document says on its face that it replaces an earlier invoice and warns against paying both. The arithmetic is fine, but paying this without checking what happened to HM-6604 risks paying twice.\"\n ],\n \"the review step\": [\n \"{\\\"needs_review\\\": false, \\\"review_reason\\\": \\\"none\\\"}\",\n \"{\\\"needs_review\\\": false, \\\"review_reason\\\": \\\"none\\\"}\",\n \"{\\\"needs_review\\\": false, \\\"review_reason\\\": \\\"none\\\"}\",\n \"{\\\"needs_review\\\": false, \\\"review_reason\\\": \\\"none\\\"}\",\n \"{\\\"needs_review\\\": false, \\\"review_reason\\\": \\\"none\\\"}\",\n \"{\\\"needs_review\\\": false, \\\"review_reason\\\": \\\"none\\\"}\",\n \"{\\\"needs_review\\\": true, \\\"review_reason\\\": \\\"missing_identifier\\\"}\",\n \"{\\\"needs_review\\\": true, \\\"review_reason\\\": \\\"unusual_document\\\"}\"\n ],\n \"the totals-mismatch step\": \"{\\\"needs_review\\\": true, \\\"review_reason\\\": \\\"totals_mismatch\\\"}\",\n \"the tax-out-of-range step\": \"{\\\"needs_review\\\": true, \\\"review_reason\\\": \\\"tax_out_of_range\\\"}\",\n \"the unexpected-currency step\": \"{\\\"needs_review\\\": true, \\\"review_reason\\\": \\\"unexpected_currency\\\"}\",\n \"the past-due step\": \"{\\\"needs_review\\\": true, \\\"review_reason\\\": \\\"past_due\\\"}\"\n}\n", "examples/invoice_extract/grammars/amounts.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"subtotal\": {\"type\": \"number\"},\n \"tax_amount\": {\"type\": \"number\"},\n \"total_amount\": {\"type\": \"number\"}\n },\n \"required\": [\"subtotal\", \"tax_amount\", \"total_amount\"],\n \"additionalProperties\": false\n}\n", "examples/invoice_extract/grammars/due.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"due_date\": {\"type\": [\"string\", \"null\"]}\n },\n \"required\": [\"due_date\"],\n \"additionalProperties\": false\n}\n", "examples/invoice_extract/grammars/flag_currency.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"needs_review\": {\n \"type\": \"boolean\",\n \"enum\": [\n true\n ]\n },\n \"review_reason\": {\n \"type\": \"string\",\n \"enum\": [\n \"unexpected_currency\"\n ]\n }\n },\n \"required\": [\n \"needs_review\",\n \"review_reason\"\n ],\n \"additionalProperties\": false\n}\n", "examples/invoice_extract/grammars/flag_overdue.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"needs_review\": {\n \"type\": \"boolean\",\n \"enum\": [\n true\n ]\n },\n \"review_reason\": {\n \"type\": \"string\",\n \"enum\": [\n \"past_due\"\n ]\n }\n },\n \"required\": [\n \"needs_review\",\n \"review_reason\"\n ],\n \"additionalProperties\": false\n}\n", "examples/invoice_extract/grammars/flag_tax.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"needs_review\": {\n \"type\": \"boolean\",\n \"enum\": [\n true\n ]\n },\n \"review_reason\": {\n \"type\": \"string\",\n \"enum\": [\n \"tax_out_of_range\"\n ]\n }\n },\n \"required\": [\n \"needs_review\",\n \"review_reason\"\n ],\n \"additionalProperties\": false\n}\n", "examples/invoice_extract/grammars/flag_totals.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"needs_review\": {\n \"type\": \"boolean\",\n \"enum\": [\n true\n ]\n },\n \"review_reason\": {\n \"type\": \"string\",\n \"enum\": [\n \"totals_mismatch\"\n ]\n }\n },\n \"required\": [\n \"needs_review\",\n \"review_reason\"\n ],\n \"additionalProperties\": false\n}\n", "examples/invoice_extract/grammars/header.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"supplier_name\": {\"type\": \"string\"},\n \"invoice_number\": {\"type\": \"string\"},\n \"currency\": {\n \"type\": \"string\",\n \"enum\": [\"USD\", \"EUR\", \"GBP\", \"PKR\", \"AED\", \"JPY\", \"unknown\"]\n }\n },\n \"required\": [\"supplier_name\", \"invoice_number\", \"currency\"],\n \"additionalProperties\": false\n}\n", "examples/invoice_extract/grammars/review.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"needs_review\": {\"type\": \"boolean\"},\n \"review_reason\": {\n \"type\": \"string\",\n \"enum\": [\"none\", \"missing_identifier\", \"unusual_document\"]\n }\n },\n \"required\": [\"needs_review\", \"review_reason\"],\n \"additionalProperties\": false\n}\n", "examples/invoice_extract/graph.yaml": "# inputs_check -> header -> amounts -> due -> [ four checks ] -> review -> end\n#\n# The shape of this pack is the whole argument: a small model is asked to *copy*\n# and to *judge*, never to *calculate*. Everything that is arithmetic or policy\n# is an `assert` node, evaluated by the runtime against committed state, so no\n# amount of model sloppiness can get a broken invoice past it.\n#\n# inputs_check\n# |\n# header\n# |\n# amounts\n# |\n# due\n# |\n# totals_check -> tax_check -> currency_check -> date_check -> review\n# | | | | | \\\n# flag_totals flag_tax flag_currency flag_overdue | accepted\n# \\_____________\\____________/________________/ |\n# flagged manual_review\n#\n# Four checks, four terminal reasons. Each failing check routes to its own\n# one-answer node, because the reason has to reach the output and in stepmold only a\n# node can write to state.\n#\n# `inputs_check` runs before any of it: a run needs `invoice_text` and a `today`\n# of the shape YYYY-MM-DD, and nothing else in the pack format says so.\n\nmax_steps: 16\n\nnodes:\n\n # -------------------------------------------------------------- input guard\n\n inputs_check:\n type: assert\n # Deliberately the only check in this pack with no `on_fail`. An assert node\n # that cannot evaluate its expression is routed exactly like one that\n # evaluated false, so a run started without `today` would take date_check's\n # failure edge and report a perfectly ordinary invoice as `past_due`. With\n # no failure edge the expression error escapes instead, naming the input\n # that is missing, before a single token is spent.\n expr: len(invoice_text) > 0 and len(today) == 10 and today[4] == \"-\"\n\n # ---------------------------------------------------------------- extraction\n\n header:\n type: generate\n # Three fields copied off the page. No judgement, no arithmetic, so no\n # think stage: two_stage here would buy nothing and cost a call.\n max_tokens: 96\n\n amounts:\n type: generate\n # Deliberately NOT asked to reconcile the numbers it reads — that is\n # totals_check's job, and a model that \"fixes\" a bad invoice on the way in\n # is the exact failure this pack exists to prevent.\n max_tokens: 64\n\n due:\n type: generate\n max_tokens: 32\n\n # ------------------------------------------------------ deterministic checks\n #\n # These are `assert` nodes: pure expressions over state, no model call, no\n # tokens, no retry ladder. They are also the reason the extraction prompts can\n # stay dumb — a copied-wrong number is caught here rather than believed.\n\n totals_check:\n # The check a model must never be trusted to do in its head. Tolerance\n # rather than equality because these are floats off a page.\n type: assert\n expr: abs(subtotal + tax_amount - total_amount) < 0.01\n on_fail: flag_totals\n\n tax_check:\n # A tax line larger than 30% of the subtotal is not a tax line; it is an OCR\n # slip or a different document. Cheap, and it catches a whole class of\n # extraction error the schema cannot express.\n type: assert\n expr: tax_amount <= subtotal * 0.30\n on_fail: flag_tax\n\n currency_check:\n # Policy, not extraction. The header grammar knows about six currencies\n # because invoices arrive in six; accounts payable settles in three.\n type: assert\n expr: currency in [\"USD\", \"EUR\", \"GBP\"]\n on_fail: flag_currency\n\n date_check:\n # ISO dates compare correctly as strings, so this needs no date library.\n # The null guard is first and `or` short-circuits, so an invoice with no\n # printed due date is not \"overdue\".\n type: assert\n expr: due_date == null or due_date >= today\n on_fail: flag_overdue\n\n # -------------------------------------------------------------- the judgement\n\n review:\n type: generate\n # The one node in the pack with a real judgement in it: everything a rule\n # could catch has already been caught, so what is left is \"does this\n # document look like something a human should see\" — unreadable identifiers,\n # an invoice that says it is a revision or a duplicate. That is a reading\n # task with no single right cue, which is exactly the case where forcing the\n # first token into a schema costs accuracy (docs/ARCHITECTURE.md §2, Bug 2). So it\n # reasons into a scratchpad first and emits second.\n two_stage: true\n think_max_tokens: 160\n max_tokens: 96\n # The model may flag or clear the invoice, but it may not do both or\n # neither: a reason without a flag (or a flag without a reason) is an\n # answer nobody downstream can act on.\n assert: needs_review == (review_reason != \"none\")\n on_fail: manual_review\n\n # ----------------------------------------------------------- forced outcomes\n #\n # One node per failed check. Each has a single-value grammar, so its answer is\n # decided by the pack rather than by the model — the node exists only because\n # a fact the runtime already knows has to be written into state, and only a\n # node can write to state.\n\n flag_totals:\n type: generate\n max_tokens: 24\n\n flag_tax:\n type: generate\n max_tokens: 24\n\n flag_currency:\n type: generate\n max_tokens: 24\n\n flag_overdue:\n type: generate\n max_tokens: 24\n\n # ------------------------------------------------------------------- endings\n\n accepted:\n type: end\n output:\n - supplier_name\n - invoice_number\n - currency\n - subtotal\n - tax_amount\n - total_amount\n - due_date\n - needs_review\n - review_reason\n\n flagged:\n type: end\n output:\n - supplier_name\n - invoice_number\n - currency\n - subtotal\n - tax_amount\n - total_amount\n - due_date\n - needs_review\n - review_reason\n\n manual_review:\n # The review node contradicted itself, so nothing it said is trustworthy.\n # A human gets the identity and the amount and nothing derived from the\n # answer that was rejected.\n type: end\n output:\n - supplier_name\n - invoice_number\n - currency\n - total_amount\n - due_date\n\nedges:\n\n - from: inputs_check\n to: header\n\n - from: header\n to: amounts\n\n - from: amounts\n to: due\n\n - from: due\n to: totals_check\n\n - from: totals_check\n to: tax_check\n\n - from: tax_check\n to: currency_check\n\n - from: currency_check\n to: date_check\n\n - from: date_check\n to: review\n\n # The one conditional edge: the model's own answer picks the ending.\n - from: review\n to: flagged\n when: {needs_review: true}\n\n - from: review\n to: accepted\n\n - from: flag_totals\n to: flagged\n\n - from: flag_tax\n to: flagged\n\n - from: flag_currency\n to: flagged\n\n - from: flag_overdue\n to: flagged\n", "examples/invoice_extract/manifest.yaml": "name: invoice_extract\nversion: 1\nentry: inputs_check\nmodel: fake:fakes/script.json\ndescription: >-\n Supplier-invoice extraction: read an invoice's raw text and return the\n supplier, the invoice number, the currency, the money, the due date, and\n whether a human has to look at it before it is paid.\n\n Every arithmetic and policy check is an `assert` node, not a model judgement —\n totals that do not add up, tax outside the plausible band, a currency the\n business does not accept, and a due date already in the past. The model only\n copies fields off the page and makes the one judgement that is genuinely\n fuzzy.\n\n A run needs two inputs: `invoice_text` and `today` (YYYY-MM-DD). `today` is an\n input rather than a clock read so a run is reproducible and the evalset can\n pin the past-due boundary.\n\n The model below is a scripted stand-in, so the evalset scores offline with no\n GPU and no network. It replays the twelve evalset cases in order and does not\n read the invoice, so a `stepmold run` of anything other than the first case will\n answer the first case. Point --model at a real backend to run real invoices.\n", "examples/invoice_extract/prompts/amounts.txt": "You are the amounts step of an invoice extraction workflow.\n\nRead three numbers off the invoice. Copy them. Never add them up yourself.\n\n subtotal - the amount before tax\n tax_amount - the tax, VAT, GST or sales tax line. If there is none, use 0\n total_amount - the total the invoice asks to be paid\n\nRules:\n - Numbers only. Drop the currency symbol and the thousands separators:\n $12,500.00 becomes 12500.00\n - If no subtotal line is printed, use the amount of the single line item.\n - Copy what is printed even when the numbers look wrong to you. A later step\n checks the arithmetic. Correcting it here hides the error.\n\nInvoice:\n{invoice_text}\n", "examples/invoice_extract/prompts/due.txt": "You are the due-date step of an invoice extraction workflow.\n\nFind the one date the invoice must be paid by.\n\n due_date - that date as YYYY-MM-DD, or null\n\nRules:\n - The invoice date is not the due date. Only a date labelled due, payable or\n payment due counts.\n - \"Due on receipt\" is not a date. Use null.\n - Never work a date out from payment terms such as \"Net 30\". Use null.\n - If no due date is printed, use null.\n\nInvoice:\n{invoice_text}\n", "examples/invoice_extract/prompts/flag_currency.txt": "You are the unexpected-currency step of an invoice extraction workflow.\n\nAn automatic check found that this invoice is billed in a currency accounts\npayable does not settle, so it cannot be paid without a human. That is already\ndecided.\n\nAnswer exactly this and nothing else:\n{{\"needs_review\": true, \"review_reason\": \"unexpected_currency\"}}\n", "examples/invoice_extract/prompts/flag_overdue.txt": "You are the past-due step of an invoice extraction workflow.\n\nAn automatic check found that this invoice's due date has already gone by, so\nit cannot be paid on the normal run without a human. That is already decided.\n\nAnswer exactly this and nothing else:\n{{\"needs_review\": true, \"review_reason\": \"past_due\"}}\n", "examples/invoice_extract/prompts/flag_tax.txt": "You are the tax-out-of-range step of an invoice extraction workflow.\n\nAn automatic check found that the tax line is too large a share of the subtotal\nto be a tax line, so this invoice cannot be paid without a human. That is\nalready decided.\n\nAnswer exactly this and nothing else:\n{{\"needs_review\": true, \"review_reason\": \"tax_out_of_range\"}}\n", "examples/invoice_extract/prompts/flag_totals.txt": "You are the totals-mismatch step of an invoice extraction workflow.\n\nAn automatic check found that subtotal + tax does not equal the total on this\ninvoice, so it cannot be paid without a human. That is already decided.\n\nAnswer exactly this and nothing else:\n{{\"needs_review\": true, \"review_reason\": \"totals_mismatch\"}}\n", "examples/invoice_extract/prompts/header.txt": "You are the header step of an invoice extraction workflow.\n\nCopy three facts off the invoice. Do not calculate anything.\n\n supplier_name - the company that issued the invoice, exactly as written.\n If no company is named, write: unknown\n invoice_number - the invoice reference, exactly as written, without the word\n \"invoice\". If none is printed, write: unknown\n currency - the currency of the amounts: USD, EUR, GBP, PKR, AED or JPY.\n $ is USD. EUR is EUR. £ is GBP.\n If you cannot tell, write: unknown\n\nInvoice:\n{invoice_text}\n", "examples/invoice_extract/prompts/review.think.txt": "You are the review reasoning step of an invoice extraction workflow.\n\nThe automatic checks have already passed on this invoice: the totals add up,\nthe tax is in range, the currency is accepted, and the due date is not past.\n\nIn two or three sentences, weigh whether a human should still look at it before\nit is paid. Only two things count:\n - the supplier name or the invoice number is missing or unreadable\n - the invoice says something unusual about itself, such as being a revision,\n a duplicate, a credit note or a draft\n\nDo not decide yet and do not answer in JSON.\n\nSupplier: {supplier_name}\nInvoice number: {invoice_number}\nInvoice:\n{invoice_text}\n", "examples/invoice_extract/prompts/review.txt": "You are the review step of an invoice extraction workflow.\n\nDecide whether a human must check this invoice before it is paid.\n\n needs_review - true or false\n review_reason - one of:\n none - nothing is wrong with the document\n missing_identifier - the supplier name or the invoice number is unknown\n unusual_document - the invoice says it is a revision, a duplicate,\n a credit note or a draft\n\nRule: review_reason is \"none\" when needs_review is false, and never otherwise.\n\nSupplier: {supplier_name}\nInvoice number: {invoice_number}\nInvoice:\n{invoice_text}\n", "examples/lead_qualify/evalset.jsonl": "{\"name\": \"enterprise, work email, budget approved, urgent\", \"input\": {\"name\": \"Priya Raman\", \"company\": \"Zenith Robotics\", \"email\": \"priya.raman@zenithrobotics.com\", \"message\": \"We have budget approved for this quarter and we need to replace our current vendor before the end of the month. Please get someone on a call this week.\", \"headcount\": 2400}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"1000+\", \"segment\": \"enterprise\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"manufacturing\", \"seniority\": \"manager\", \"budget_signal\": \"budget_approved\", \"urgency\": \"high\", \"fit_band\": \"strong\", \"next_action\": \"route_to_sales\", \"owner\": \"ae_enterprise\"}, \"end\": \"sales_queue\"}\n{\"name\": \"enterprise on a free mailbox is rejected\", \"input\": {\"name\": \"Dan Whitfield\", \"company\": \"Northwind Logistics\", \"email\": \"dan.whitfield91@gmail.com\", \"message\": \"Looking at tools for our 3,000 driver fleet. Budget is signed off.\", \"headcount\": 3000}, \"expect\": {\"email_domain_kind\": \"free_mail\", \"company_named\": true, \"headcount_band\": \"1000+\", \"segment\": \"enterprise\", \"disqualified\": true, \"disqualify_reason\": \"free_mail_enterprise\", \"next_action\": \"reject\"}, \"end\": \"rejected\"}\n{\"name\": \"mid market, exploring price, next year\", \"input\": {\"name\": \"Marta Silva\", \"company\": \"Brightline Health\", \"email\": \"m.silva@brightlinehealth.co\", \"message\": \"We are starting to look at options for next year and would like to understand your pricing before we shortlist.\", \"headcount\": 600}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"250-999\", \"segment\": \"mid_market\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"healthcare\", \"seniority\": \"manager\", \"budget_signal\": \"exploring\", \"urgency\": \"medium\", \"fit_band\": \"moderate\", \"next_action\": \"nurture\", \"owner\": \"marketing_nurture\"}, \"end\": \"nurture_queue\"}\n{\"name\": \"mid market, contract ending, budget approved\", \"input\": {\"name\": \"Tom Aldridge\", \"company\": \"Caldera Freight\", \"email\": \"t.aldridge@calderafreight.com\", \"message\": \"I run operations here. Our contract with the incumbent ends in six weeks and the budget is already approved, so we need to move quickly.\", \"headcount\": 480}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"250-999\", \"segment\": \"mid_market\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"other\", \"seniority\": \"executive\", \"budget_signal\": \"budget_approved\", \"urgency\": \"high\", \"fit_band\": \"strong\", \"next_action\": \"route_to_sales\", \"owner\": \"ae_mid_market\"}, \"end\": \"sales_queue\"}\n{\"name\": \"small company, no budget, no timeline\", \"input\": {\"name\": \"Chloe Barnes\", \"company\": \"Fernwood Design\", \"email\": \"chloe@fernwooddesign.studio\", \"message\": \"Just browsing for now. We might need something like this eventually, no timeline on our side.\", \"headcount\": 22}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"10-49\", \"segment\": \"smb\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"other\", \"seniority\": \"unknown\", \"budget_signal\": \"none\", \"urgency\": \"low\", \"fit_band\": \"weak\", \"next_action\": \"nurture\", \"owner\": \"marketing_nurture\"}, \"end\": \"nurture_queue\"}\n{\"name\": \"free mailbox on a one-person company passes the gate\", \"input\": {\"name\": \"Victor Osei\", \"company\": \"Osei Consulting\", \"email\": \"victor.osei@gmail.com\", \"message\": \"I am a one-man consultancy and I want to see whether this works for a single user.\", \"headcount\": 1}, \"expect\": {\"email_domain_kind\": \"free_mail\", \"company_named\": true, \"headcount_band\": \"1-9\", \"segment\": \"solo\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"other\", \"seniority\": \"executive\", \"budget_signal\": \"none\", \"urgency\": \"low\", \"fit_band\": \"weak\", \"next_action\": \"nurture\", \"owner\": \"marketing_nurture\"}, \"end\": \"nurture_queue\"}\n{\"name\": \"headcount left blank, size taken from the message\", \"input\": {\"name\": \"Anita Kowalski\", \"company\": \"Halberd Insurance\", \"email\": \"a.kowalski@halberd-insurance.com\", \"message\": \"There are about 400 of us and we are comparing two vendors this quarter. Finance has set money aside for it.\", \"headcount\": null}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"250-999\", \"segment\": \"mid_market\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"financial_services\", \"seniority\": \"manager\", \"budget_signal\": \"budget_approved\", \"urgency\": \"medium\", \"fit_band\": \"strong\", \"next_action\": \"route_to_sales\", \"owner\": \"ae_mid_market\"}, \"end\": \"sales_queue\"}\n{\"name\": \"headcount left blank and the message says nothing about size\", \"input\": {\"name\": \"Raj Patel\", \"company\": \"Loomis Bakery\", \"email\": \"raj@loomisbakery.com\", \"message\": \"Can you send me more information about what you do?\", \"headcount\": null}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"10-49\", \"segment\": \"smb\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"retail\", \"seniority\": \"unknown\", \"budget_signal\": \"none\", \"urgency\": \"low\", \"fit_band\": \"weak\", \"next_action\": \"nurture\", \"owner\": \"marketing_nurture\"}, \"end\": \"nurture_queue\"}\n{\"name\": \"enterprise is not an automatic route to sales\", \"input\": {\"name\": \"Helen Vance\", \"company\": \"Ministry of Transport\", \"email\": \"h.vance@transport.gov.example\", \"message\": \"We are gathering information for a possible procurement next year. No decision has been made yet.\", \"headcount\": 5200}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"1000+\", \"segment\": \"enterprise\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"public_sector\", \"seniority\": \"manager\", \"budget_signal\": \"none\", \"urgency\": \"low\", \"fit_band\": \"moderate\", \"next_action\": \"nurture\", \"owner\": \"marketing_nurture\"}, \"end\": \"nurture_queue\"}\n{\"name\": \"moderate fit with high urgency still goes to sales\", \"input\": {\"name\": \"Kwame Adjei\", \"company\": \"Tidewater Labs\", \"email\": \"kwame@tidewaterlabs.io\", \"message\": \"Our current tool is being shut down on Friday and we need a replacement immediately. I am not sure what our budget is.\", \"headcount\": 35}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"10-49\", \"segment\": \"smb\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"software\", \"seniority\": \"manager\", \"budget_signal\": \"none\", \"urgency\": \"high\", \"fit_band\": \"moderate\", \"next_action\": \"route_to_sales\", \"owner\": \"sdr\"}, \"end\": \"sales_queue\"}\n{\"name\": \"blank company and a free mailbox, still enterprise, still rejected\", \"input\": {\"name\": \"sam\", \"company\": \"\", \"email\": \"sam.k.2001@outlook.com\", \"message\": \"hi we are a big company 1500 staff, send pricing\", \"headcount\": 1500}, \"expect\": {\"email_domain_kind\": \"free_mail\", \"company_named\": false, \"headcount_band\": \"1000+\", \"segment\": \"enterprise\", \"disqualified\": true, \"disqualify_reason\": \"free_mail_enterprise\", \"next_action\": \"reject\"}, \"end\": \"rejected\"}\n{\"name\": \"off-topic pitch scores weak\", \"input\": {\"name\": \"Alex Turner\", \"company\": \"SEO Boost Pro\", \"email\": \"alex@seoboostpro.biz\", \"message\": \"Hello, I would like to offer you our link building services at a discount this month.\", \"headcount\": 3}, \"expect\": {\"email_domain_kind\": \"company_domain\", \"company_named\": true, \"headcount_band\": \"1-9\", \"segment\": \"solo\", \"disqualified\": false, \"disqualify_reason\": \"none\", \"industry\": \"other\", \"seniority\": \"unknown\", \"budget_signal\": \"none\", \"urgency\": \"low\", \"fit_band\": \"weak\", \"next_action\": \"nurture\", \"owner\": \"marketing_nurture\"}, \"end\": \"nurture_queue\"}\n", "examples/lead_qualify/fakes/script.json": "{\n \"screen step\": [\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"free_mail\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"free_mail\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\",\n \"{\\\"email_domain_kind\\\": \\\"free_mail\\\", \\\"company_named\\\": false}\",\n \"{\\\"email_domain_kind\\\": \\\"company_domain\\\", \\\"company_named\\\": true}\"\n ],\n \"segment step\": [\n \"{\\\"headcount_band\\\": \\\"1000+\\\", \\\"segment\\\": \\\"enterprise\\\"}\",\n \"{\\\"headcount_band\\\": \\\"1000+\\\", \\\"segment\\\": \\\"enterprise\\\"}\",\n \"{\\\"headcount_band\\\": \\\"250-999\\\", \\\"segment\\\": \\\"mid_market\\\"}\",\n \"{\\\"headcount_band\\\": \\\"250-999\\\", \\\"segment\\\": \\\"mid_market\\\"}\",\n \"{\\\"headcount_band\\\": \\\"10-49\\\", \\\"segment\\\": \\\"smb\\\"}\",\n \"{\\\"headcount_band\\\": \\\"1-9\\\", \\\"segment\\\": \\\"solo\\\"}\",\n \"{\\\"headcount_band\\\": \\\"250-999\\\", \\\"segment\\\": \\\"mid_market\\\"}\",\n \"{\\\"headcount_band\\\": \\\"10-49\\\", \\\"segment\\\": \\\"smb\\\"}\",\n \"{\\\"headcount_band\\\": \\\"1000+\\\", \\\"segment\\\": \\\"enterprise\\\"}\",\n \"{\\\"headcount_band\\\": \\\"10-49\\\", \\\"segment\\\": \\\"smb\\\"}\",\n \"{\\\"headcount_band\\\": \\\"1000+\\\", \\\"segment\\\": \\\"enterprise\\\"}\",\n \"{\\\"headcount_band\\\": \\\"1-9\\\", \\\"segment\\\": \\\"solo\\\"}\"\n ],\n \"gate step\": [\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": true, \\\"disqualify_reason\\\": \\\"free_mail_enterprise\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\",\n \"{\\\"disqualified\\\": true, \\\"disqualify_reason\\\": \\\"free_mail_enterprise\\\"}\",\n \"{\\\"disqualified\\\": false, \\\"disqualify_reason\\\": \\\"none\\\"}\"\n ],\n \"decline step\": [\n \"{\\\"next_action\\\": \\\"reject\\\", \\\"reply_note\\\": \\\"Thanks for getting in touch, Dan - could you write to us again from your Northwind Logistics work address so we can verify the account?\\\"}\",\n \"{\\\"next_action\\\": \\\"reject\\\", \\\"reply_note\\\": \\\"Thanks for writing in - please send this again from your company email address so we can confirm who you are.\\\"}\"\n ],\n \"enrich step\": [\n \"{\\\"industry\\\": \\\"manufacturing\\\", \\\"seniority\\\": \\\"manager\\\"}\",\n \"{\\\"industry\\\": \\\"healthcare\\\", \\\"seniority\\\": \\\"manager\\\"}\",\n \"{\\\"industry\\\": \\\"other\\\", \\\"seniority\\\": \\\"executive\\\"}\",\n \"{\\\"industry\\\": \\\"other\\\", \\\"seniority\\\": \\\"unknown\\\"}\",\n \"{\\\"industry\\\": \\\"other\\\", \\\"seniority\\\": \\\"executive\\\"}\",\n \"{\\\"industry\\\": \\\"financial_services\\\", \\\"seniority\\\": \\\"manager\\\"}\",\n \"{\\\"industry\\\": \\\"retail\\\", \\\"seniority\\\": \\\"unknown\\\"}\",\n \"{\\\"industry\\\": \\\"public_sector\\\", \\\"seniority\\\": \\\"manager\\\"}\",\n \"{\\\"industry\\\": \\\"software\\\", \\\"seniority\\\": \\\"manager\\\"}\",\n \"{\\\"industry\\\": \\\"other\\\", \\\"seniority\\\": \\\"unknown\\\"}\"\n ],\n \"signals step\": [\n \"{\\\"budget_signal\\\": \\\"budget_approved\\\", \\\"urgency\\\": \\\"high\\\"}\",\n \"{\\\"budget_signal\\\": \\\"exploring\\\", \\\"urgency\\\": \\\"medium\\\"}\",\n \"{\\\"budget_signal\\\": \\\"budget_approved\\\", \\\"urgency\\\": \\\"high\\\"}\",\n \"{\\\"budget_signal\\\": \\\"none\\\", \\\"urgency\\\": \\\"low\\\"}\",\n \"{\\\"budget_signal\\\": \\\"none\\\", \\\"urgency\\\": \\\"low\\\"}\",\n \"{\\\"budget_signal\\\": \\\"budget_approved\\\", \\\"urgency\\\": \\\"medium\\\"}\",\n \"{\\\"budget_signal\\\": \\\"none\\\", \\\"urgency\\\": \\\"low\\\"}\",\n \"{\\\"budget_signal\\\": \\\"none\\\", \\\"urgency\\\": \\\"low\\\"}\",\n \"{\\\"budget_signal\\\": \\\"none\\\", \\\"urgency\\\": \\\"high\\\"}\",\n \"{\\\"budget_signal\\\": \\\"none\\\", \\\"urgency\\\": \\\"low\\\"}\"\n ],\n \"score reasoning step\": [\n \"A two-thousand-person manufacturer with money already approved and a vendor contract they want out of within the month. The person speaks for a team. Nothing here is speculative.\",\n \"Six hundred people in healthcare, asking about price for a shortlist next year. Real buyer, but nobody has approved anything and the date is far out.\",\n \"The head of operations at a four-hundred-person freight firm, with money approved and an incumbent contract expiring in six weeks. Both the authority and the deadline are real.\",\n \"A twenty-two person design studio saying outright that they are browsing with no timeline. No money mentioned and no sign of who is asking.\",\n \"One person, evaluating for himself, no money mentioned and no date. He owns the decision, but there is almost nothing to sell.\",\n \"Four hundred people in insurance, money already set aside, and an active two-vendor comparison running this quarter. The form left headcount blank but the message did not.\",\n \"Nothing to weigh. A one-line request for information, no size, no money, no date and no clue who is asking.\",\n \"Large public body, but this is information gathering for a procurement that may not happen, with no money and no date. Size alone does not make it urgent.\",\n \"A small software team losing their tool on Friday. The need is real and immediate even though nobody has said what they can spend.\",\n \"This is not an inbound lead at all. Someone is selling to us, not buying, and there is nothing on our side to weigh.\"\n ],\n \"score step\": [\n \"{\\\"fit_band\\\": \\\"strong\\\", \\\"fit_reason\\\": \\\"Large manufacturer with approved budget and a hard replacement deadline this month.\\\"}\",\n \"{\\\"fit_band\\\": \\\"moderate\\\", \\\"fit_reason\\\": \\\"Real mid-market buyer, but pricing questions only and no approved budget.\\\"}\",\n \"{\\\"fit_band\\\": \\\"strong\\\", \\\"fit_reason\\\": \\\"Operations lead with approved budget and an incumbent contract ending in six weeks.\\\"}\",\n \"{\\\"fit_band\\\": \\\"weak\\\", \\\"fit_reason\\\": \\\"Small studio browsing with no budget, no timeline and no stated owner.\\\"}\",\n \"{\\\"fit_band\\\": \\\"weak\\\", \\\"fit_reason\\\": \\\"Sole consultant evaluating single-user use with no budget and no timeline.\\\"}\",\n \"{\\\"fit_band\\\": \\\"strong\\\", \\\"fit_reason\\\": \\\"Four-hundred-person insurer with money set aside and an active vendor comparison.\\\"}\",\n \"{\\\"fit_band\\\": \\\"weak\\\", \\\"fit_reason\\\": \\\"One-line information request with no size, budget or timeline given.\\\"}\",\n \"{\\\"fit_band\\\": \\\"moderate\\\", \\\"fit_reason\\\": \\\"Large public buyer gathering information for a procurement that is not yet funded.\\\"}\",\n \"{\\\"fit_band\\\": \\\"moderate\\\", \\\"fit_reason\\\": \\\"Small team with an immediate replacement deadline but no confirmed budget.\\\"}\",\n \"{\\\"fit_band\\\": \\\"weak\\\", \\\"fit_reason\\\": \\\"Inbound pitch selling services to us rather than a buying enquiry.\\\"}\"\n ],\n \"route step\": [\n \"{\\\"next_action\\\": \\\"route_to_sales\\\", \\\"owner\\\": \\\"ae_enterprise\\\"}\",\n \"{\\\"next_action\\\": \\\"nurture\\\", \\\"owner\\\": \\\"marketing_nurture\\\"}\",\n \"{\\\"next_action\\\": \\\"route_to_sales\\\", \\\"owner\\\": \\\"ae_mid_market\\\"}\",\n \"{\\\"next_action\\\": \\\"nurture\\\", \\\"owner\\\": \\\"marketing_nurture\\\"}\",\n \"{\\\"next_action\\\": \\\"nurture\\\", \\\"owner\\\": \\\"marketing_nurture\\\"}\",\n \"{\\\"next_action\\\": \\\"route_to_sales\\\", \\\"owner\\\": \\\"ae_mid_market\\\"}\",\n \"{\\\"next_action\\\": \\\"nurture\\\", \\\"owner\\\": \\\"marketing_nurture\\\"}\",\n \"{\\\"next_action\\\": \\\"nurture\\\", \\\"owner\\\": \\\"marketing_nurture\\\"}\",\n \"{\\\"next_action\\\": \\\"route_to_sales\\\", \\\"owner\\\": \\\"sdr\\\"}\",\n \"{\\\"next_action\\\": \\\"nurture\\\", \\\"owner\\\": \\\"marketing_nurture\\\"}\"\n ]\n}\n", "examples/lead_qualify/grammars/decline.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"next_action\": {\"type\": \"string\", \"enum\": [\"reject\"]},\n \"reply_note\": {\"type\": \"string\"}\n },\n \"required\": [\"next_action\", \"reply_note\"],\n \"additionalProperties\": false\n}\n", "examples/lead_qualify/grammars/enrich.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"industry\": {\n \"type\": \"string\",\n \"enum\": [\"software\", \"financial_services\", \"healthcare\", \"retail\",\n \"manufacturing\", \"education\", \"public_sector\", \"other\"]\n },\n \"seniority\": {\n \"type\": \"string\",\n \"enum\": [\"executive\", \"manager\", \"ic\", \"unknown\"]\n }\n },\n \"required\": [\"industry\", \"seniority\"],\n \"additionalProperties\": false\n}\n", "examples/lead_qualify/grammars/gate.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"disqualified\": {\"type\": \"boolean\"},\n \"disqualify_reason\": {\n \"type\": \"string\",\n \"enum\": [\"free_mail_enterprise\", \"none\"]\n }\n },\n \"required\": [\"disqualified\", \"disqualify_reason\"],\n \"additionalProperties\": false\n}\n", "examples/lead_qualify/grammars/route.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"next_action\": {\n \"type\": \"string\",\n \"enum\": [\"route_to_sales\", \"nurture\"]\n },\n \"owner\": {\n \"type\": \"string\",\n \"enum\": [\"ae_enterprise\", \"ae_mid_market\", \"sdr\", \"marketing_nurture\"]\n }\n },\n \"required\": [\"next_action\", \"owner\"],\n \"additionalProperties\": false\n}\n", "examples/lead_qualify/grammars/score.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"fit_band\": {\"type\": \"string\", \"enum\": [\"strong\", \"moderate\", \"weak\"]},\n \"fit_reason\": {\"type\": \"string\"}\n },\n \"required\": [\"fit_band\", \"fit_reason\"],\n \"additionalProperties\": false\n}\n", "examples/lead_qualify/grammars/screen.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"email_domain_kind\": {\n \"type\": \"string\",\n \"enum\": [\"company_domain\", \"free_mail\", \"unknown\"]\n },\n \"company_named\": {\"type\": \"boolean\"}\n },\n \"required\": [\"email_domain_kind\", \"company_named\"],\n \"additionalProperties\": false\n}\n", "examples/lead_qualify/grammars/segment.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"headcount_band\": {\n \"type\": \"string\",\n \"enum\": [\"1-9\", \"10-49\", \"50-249\", \"250-999\", \"1000+\"]\n },\n \"segment\": {\n \"type\": \"string\",\n \"enum\": [\"solo\", \"smb\", \"mid_market\", \"enterprise\"]\n }\n },\n \"required\": [\"headcount_band\", \"segment\"],\n \"additionalProperties\": false\n}\n", "examples/lead_qualify/grammars/signals.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"budget_signal\": {\n \"type\": \"string\",\n \"enum\": [\"budget_approved\", \"exploring\", \"none\"]\n },\n \"urgency\": {\"type\": \"string\", \"enum\": [\"high\", \"medium\", \"low\"]}\n },\n \"required\": [\"budget_signal\", \"urgency\"],\n \"additionalProperties\": false\n}\n", "examples/lead_qualify/graph.yaml": "# screen -> segment -> gate -+-> decline -> rejected\n# |\n# +-> enrich -> signals -> score -> route -+-> sales_queue\n# |\n# +-> nurture_queue\n#\n# The gate is the point of the shape. It costs one 48-token call and it decides\n# whether the four expensive nodes below it run at all, so the conditional edge\n# out of `gate` is a cost decision as much as a routing one: a disqualified lead\n# never reaches `enrich`, `signals`, `score` or `route`.\n#\n# Every node has one job and one grammar. Two nodes carry an `assert`, and both\n# of them restate a rule their own prompt already gave the model in words — the\n# prompt teaches it, the assert makes it non-negotiable, and `on_fail` sends the\n# lead to a human rather than letting a wrong answer out.\n\nmax_steps: 12\n\nnodes:\n\n screen:\n type: generate\n # Reads the email and the company field, nothing else.\n max_tokens: 48\n\n segment:\n type: generate\n max_tokens: 48\n # headcount_band -> segment is a lookup table, not a judgement, so it is\n # checked rather than trusted. A model that invents \"enterprise\" for a\n # 30-person company is caught here instead of in the sales queue.\n assert: >-\n segment == (\"solo\" if headcount_band == \"1-9\"\n else (\"smb\" if headcount_band == \"10-49\" or headcount_band == \"50-249\"\n else (\"mid_market\" if headcount_band == \"250-999\" else \"enterprise\")))\n on_fail: needs_review\n\n gate:\n type: generate\n max_tokens: 48\n # The whole rejection policy, as one expression: disqualified is true when\n # and only when an enterprise-sized company wrote in from a free mailbox,\n # and the reason field agrees with the flag.\n assert: >-\n disqualified == (segment == \"enterprise\" and email_domain_kind == \"free_mail\")\n and (disqualify_reason == \"free_mail_enterprise\") == disqualified\n on_fail: needs_review\n\n decline:\n type: generate\n # Only reached by a disqualified lead. `next_action` is a single-value enum,\n # so the grammar pins it; the model's actual job here is the one-sentence\n # reply note.\n max_tokens: 64\n\n enrich:\n type: generate\n # The node a rejected lead skips.\n max_tokens: 48\n\n signals:\n type: generate\n max_tokens: 48\n\n score:\n type: generate\n # The only genuine judgement in the pack: fit is a trade-off between size,\n # budget, urgency and seniority, and nothing upstream has weighed them. So\n # this node gets an unconstrained think pass before the constrained emit\n # (README, \"Think and emit are separate\"). Every other node is a lookup or a\n # slot fill, and pays for one call.\n two_stage: true\n think_max_tokens: 128\n max_tokens: 96\n\n route:\n type: generate\n max_tokens: 64\n # The routing policy, stated once here and once in prompts/route.txt. Sales\n # gets the lead only when the band and urgency say so, and the owner is a\n # pure function of the action and the segment.\n assert: >-\n (next_action == \"route_to_sales\") == (fit_band == \"strong\"\n or (fit_band == \"moderate\" and urgency == \"high\"))\n and (owner == \"marketing_nurture\") == (next_action == \"nurture\")\n and (owner == \"ae_enterprise\") == (next_action == \"route_to_sales\" and segment == \"enterprise\")\n and (owner == \"ae_mid_market\") == (next_action == \"route_to_sales\" and segment == \"mid_market\")\n on_fail: needs_review\n\n sales_queue:\n type: end\n output:\n - segment\n - headcount_band\n - email_domain_kind\n - industry\n - seniority\n - budget_signal\n - urgency\n - fit_band\n - fit_reason\n - next_action\n - owner\n\n nurture_queue:\n type: end\n output:\n - segment\n - headcount_band\n - email_domain_kind\n - industry\n - seniority\n - budget_signal\n - urgency\n - fit_band\n - fit_reason\n - next_action\n - owner\n\n rejected:\n type: end\n output:\n - segment\n - headcount_band\n - email_domain_kind\n - company_named\n - disqualified\n - disqualify_reason\n - next_action\n - reply_note\n\n needs_review:\n type: end\n # A lead whose deterministic invariant did not hold. It carries only what a\n # human needs to see the disagreement.\n output: [segment, headcount_band, email_domain_kind, disqualified]\n\nedges:\n\n - from: screen\n to: segment\n\n - from: segment\n to: gate\n\n # The conditional edge: a disqualified lead leaves before enrichment.\n - from: gate\n to: decline\n when: {disqualified: true}\n\n - from: gate\n to: enrich\n\n - from: decline\n to: rejected\n\n - from: enrich\n to: signals\n\n - from: signals\n to: score\n\n - from: score\n to: route\n\n - from: route\n to: sales_queue\n when: {next_action: \"route_to_sales\"}\n\n - from: route\n to: nurture_queue\n", "examples/lead_qualify/manifest.yaml": "name: lead_qualify\nversion: 1\nentry: screen\nmodel: fake:fakes/script.json\ndescription: >-\n Inbound-lead qualifier. Screen the email domain, size the company, apply the\n free-mail/enterprise gate, then enrich, read the buying signals, score fit and\n route. A disqualified lead skips enrichment entirely, so the cheap check runs\n before the expensive nodes.\n\n The model below is a scripted stand-in, so the evalset scores offline with no\n GPU and no network. Each node replays its answers in the order the evalset\n visits that node, so a `stepmold run` of some other lead answers the first case.\n Point --model at a real backend to qualify real leads.\n", "examples/lead_qualify/prompts/decline.txt": "You are the decline step of the inbound lead workflow.\n\nThis lead is refused: an enterprise-sized company wrote in from a personal\nmailbox, so we cannot confirm who they are.\n\nnext_action is always reject.\n\nWrite reply_note: one polite sentence, 25 words or fewer, asking them to write\nin again from their work email address.\n\nName: {name}\nCompany: {company}\n", "examples/lead_qualify/prompts/enrich.txt": "You are the enrich step of the inbound lead workflow.\n\nindustry - what the company sells or does. Choose one:\n software, financial_services, healthcare, retail, manufacturing, education,\n public_sector, other\nChoose other when the company is none of the first seven.\n\nseniority - how senior the person who wrote in sounds:\n executive owner, founder, chief, head of, director, VP, or \"I run ...\"\n manager manager, lead, or someone speaking for a team\n ic speaks only for their own work\n unknown the message gives no sign\n\nName: {name}\nCompany: {company}\nMessage: {message}\n", "examples/lead_qualify/prompts/gate.txt": "You are the gate step of the inbound lead workflow.\n\nApply one rule and nothing else.\n\n When segment is enterprise AND email_domain_kind is free_mail:\n disqualified is true, disqualify_reason is free_mail_enterprise\n\n In every other case:\n disqualified is false, disqualify_reason is none\n\nA personal mailbox on a small company is fine. Only enterprise is refused.\n\nsegment: {segment}\nemail_domain_kind: {email_domain_kind}\n", "examples/lead_qualify/prompts/route.txt": "You are the route step of the inbound lead workflow.\n\nStep 1. next_action:\n route_to_sales when fit_band is strong,\n or fit_band is moderate and urgency is high\n nurture in every other case\n\nStep 2. owner:\n next_action nurture -> marketing_nurture\n next_action route_to_sales, and\n segment enterprise -> ae_enterprise\n segment mid_market -> ae_mid_market\n segment solo or smb -> sdr\n\nFit band: {fit_band}\nUrgency: {urgency}\nSegment: {segment}\n", "examples/lead_qualify/prompts/score.think.txt": "You are the score reasoning step of the inbound lead workflow.\n\nIn two or three sentences, weigh how good a fit this lead is. Consider the\ncompany size, whether money is approved, how soon they need it, and how senior\nthe person is. Do not choose the band yet and do not answer in JSON.\n\nSegment: {segment}\nSeniority: {seniority}\nBudget signal: {budget_signal}\nUrgency: {urgency}\nMessage: {message}\n", "examples/lead_qualify/prompts/score.txt": "You are the score step of the inbound lead workflow.\n\nfit_band:\n strong mid_market or enterprise with budget_approved,\n or any company with budget_approved and high urgency\n moderate a real buyer, but no approved budget yet\n weak solo or smb with no budget and no urgency,\n or a message that is not about buying from us\n\nfit_reason: one sentence, 20 words or fewer.\n\nSegment: {segment}\nSeniority: {seniority}\nBudget signal: {budget_signal}\nUrgency: {urgency}\nMessage: {message}\n", "examples/lead_qualify/prompts/screen.txt": "You are the screen step of the inbound lead workflow.\n\nLook at the two fields below. Do not read the message.\n\nemail_domain_kind - the part of the email address after the @:\n free_mail gmail.com, googlemail.com, yahoo.com, hotmail.com,\n outlook.com, live.com, msn.com, aol.com, icloud.com, me.com,\n proton.me, protonmail.com, gmx.com, mail.com, yandex.com,\n mail.ru, qq.com\n company_domain any other domain\n unknown there is no email address\n\ncompany_named - does the company field name a company?\n true it names a company\n false it is blank, or \"-\", \"n/a\", \"none\", or just the person's own name\n\nEmail: {email}\nCompany: {company}\n", "examples/lead_qualify/prompts/segment.txt": "You are the segment step of the inbound lead workflow.\n\nStep 1. Choose headcount_band.\n When the form headcount is a number, use it:\n 1 to 9 -> 1-9\n 10 to 49 -> 10-49\n 50 to 249 -> 50-249\n 250 to 999 -> 250-999\n 1000 or more -> 1000+\n When the form headcount is null, use a staff number stated in the message.\n When neither gives a number, answer 10-49.\n\nStep 2. Choose segment from the band you just picked. This table is fixed:\n 1-9 -> solo\n 10-49 -> smb\n 50-249 -> smb\n 250-999 -> mid_market\n 1000+ -> enterprise\n\nForm headcount: {headcount}\n(null above means the form field was left blank)\n\nCompany: {company}\nMessage: {message}\n", "examples/lead_qualify/prompts/signals.txt": "You are the signals step of the inbound lead workflow.\n\nRead the message. Ignore everything else.\n\nbudget_signal:\n budget_approved money is approved, signed off, or set aside\n exploring they ask about price or cost, nothing approved yet\n none money is not mentioned, or they say they do not know\n\nurgency:\n high a deadline, a contract ending, an outage, \"this week\", \"immediately\"\n medium a named quarter or year, or an active comparison of vendors\n low no date at all, \"eventually\", \"just looking\"\n\nMessage: {message}\n", "examples/meeting_actions/evalset.jsonl": "{\"name\": \"standup, everything owned\", \"input\": {\"notes\": \"Standup, Tuesday. Ravi: shipped the export fix, picking up the CSV importer today. Sara: still blocked on the staging cert, will ping infra this morning. Tom is out sick. Decision: we hold the 2.1 release until the cert is sorted.\"}, \"expect\": {\"meeting_kind\": \"standup\", \"attendees\": [\"Ravi\", \"Sara\", \"Tom\"], \"lead\": null, \"action_count\": 2, \"unowned\": \"none\", \"action_items\": [{\"task\": \"Pick up the CSV importer\", \"owner\": \"Ravi\", \"owner_source\": \"explicit\", \"due_bucket\": \"today\", \"priority\": \"p2\"}, {\"task\": \"Ping infra about the staging cert\", \"owner\": \"Sara\", \"owner_source\": \"explicit\", \"due_bucket\": \"today\", \"priority\": \"p1\"}], \"decision_count\": 1, \"follow_up_needed\": false, \"follow_up_when\": \"none\"}, \"end\": \"tracked\"}\n{\"name\": \"planning, unowned work goes to the lead\", \"input\": {\"notes\": \"Planning call. Maya ran it. We agreed the onboarding rewrite lands this quarter. Someone needs to write the migration doc before we start, and the pricing page copy still needs a rewrite - nobody picked it up. Maya will book time with legal next week.\"}, \"expect\": {\"meeting_kind\": \"planning\", \"attendees\": [\"Maya\"], \"lead\": \"Maya\", \"action_count\": 3, \"unowned\": \"some\", \"fallback_owner\": \"Maya\", \"fallback_basis\": \"meeting_lead\", \"decision_count\": 1, \"follow_up_needed\": true, \"follow_up_when\": \"next_week\"}, \"end\": \"tracked\"}\n{\"name\": \"all-hands with no commitments\", \"input\": {\"notes\": \"Company all-hands. Finance walked through the Q3 numbers. Revenue up 12%. No new commitments; questions were answered live.\"}, \"expect\": {\"meeting_kind\": \"other\", \"attendees\": [], \"lead\": null, \"action_count\": 0, \"unowned\": \"none\", \"action_items\": [], \"decision_count\": 0, \"follow_up_needed\": false, \"follow_up_when\": \"none\"}, \"end\": \"tracked\"}\n{\"name\": \"incident review, owner inferred from a team\", \"input\": {\"notes\": \"Incident review for the Friday outage. Root cause was the expired cert. The oncall rota clearly needs a secondary - the platform team owns that. Dana is writing the postmortem by Thursday. We decided not to roll back 2.0.\"}, \"expect\": {\"meeting_kind\": \"incident\", \"attendees\": [\"Dana\"], \"lead\": null, \"action_count\": 2, \"unowned\": \"none\", \"decision_count\": 1, \"follow_up_needed\": true, \"follow_up_when\": \"this_week\"}, \"end\": \"tracked\"}\n{\"name\": \"client call, a customer wish is not an action\", \"input\": {\"notes\": \"Client call with Northwind. They want SSO by the end of the month. Priya said she'd chase the vendor before Friday. We promised a written scope by next Wednesday - Alex has it. Northwind will confirm budget on their side.\"}, \"expect\": {\"meeting_kind\": \"client_call\", \"attendees\": [\"Priya\", \"Alex\"], \"lead\": null, \"action_count\": 2, \"unowned\": \"none\", \"decision_count\": 1, \"follow_up_needed\": true, \"follow_up_when\": \"next_week\"}, \"end\": \"tracked\"}\n{\"name\": \"retro with nobody named\", \"input\": {\"notes\": \"Retro. Mood was flat. Things that went badly: the release checklist was ignored, and nobody updated the runbook. Both need fixing before the next release. No one volunteered.\"}, \"expect\": {\"meeting_kind\": \"review\", \"attendees\": [], \"lead\": null, \"action_count\": 2, \"unowned\": \"some\", \"fallback_owner\": null, \"fallback_basis\": \"unclear\", \"decision_count\": 0, \"follow_up_needed\": true, \"follow_up_when\": \"next_week\"}, \"end\": \"tracked\"}\n{\"name\": \"one-on-one, the only attendee holds it\", \"input\": {\"notes\": \"1:1 with Jonas. He's taking over the billing alerts. The dashboard cleanup is still open - we didn't say who. Jonas thinks it's a two-day job. Agreed he moves to the payments squad in September.\"}, \"expect\": {\"meeting_kind\": \"one_on_one\", \"attendees\": [\"Jonas\"], \"lead\": null, \"action_count\": 2, \"unowned\": \"some\", \"action_items\": [{\"task\": \"Take over the billing alerts\", \"owner\": \"Jonas\", \"owner_source\": \"explicit\", \"due_bucket\": \"this_week\", \"priority\": \"p2\"}, {\"task\": \"Do the dashboard cleanup\", \"owner\": null, \"owner_source\": \"unassigned\", \"due_bucket\": \"no_date\", \"priority\": \"p3\"}], \"fallback_owner\": \"Jonas\", \"fallback_basis\": \"only_attendee\", \"decision_count\": 1, \"follow_up_needed\": false, \"follow_up_when\": \"none\"}, \"end\": \"tracked\"}\n{\"name\": \"weekly sync, chatter mixed with commitments\", \"input\": {\"notes\": \"Weekly sync, lots of ground. Started late. Ben mentioned the analytics job has been failing quietly since the 3rd - he'll fix it today. Then we went off on the hiring pipeline for a while; nothing decided there. Sara raised that the docs site is a mess, she'll do a pass this week if she has time. Tom wants to move the standup to 9:30 - everyone shrugged, so we're leaving it. Oh and the security questionnaire from Northwind is due next Friday, Ben said he'd start it but Sara has the compliance context.\"}, \"expect\": {\"meeting_kind\": \"other\", \"attendees\": [\"Ben\", \"Sara\", \"Tom\"], \"lead\": null, \"action_count\": 3, \"unowned\": \"none\", \"decision_count\": 1, \"follow_up_needed\": false, \"follow_up_when\": \"none\"}, \"end\": \"tracked\"}\n{\"name\": \"architecture review, decision only\", \"input\": {\"notes\": \"Architecture review. We compared Postgres and DynamoDB for the events table and settled on Postgres for now, though we'll revisit if write volume triples. Nothing to do until the load test numbers come back.\"}, \"expect\": {\"meeting_kind\": \"review\", \"attendees\": [], \"lead\": null, \"action_count\": 0, \"unowned\": \"none\", \"decision_count\": 1, \"follow_up_needed\": true, \"follow_up_when\": \"later\"}, \"end\": \"tracked\"}\n{\"name\": \"ops sync spanning every due bucket\", \"input\": {\"notes\": \"Ops sync. Dana: the backup restore test has to happen today, it's overdue. Ravi will rotate the API keys this week. Maya's taking the vendor review next week. And at some point this month someone should tidy the terraform - Ravi said he'd try.\"}, \"expect\": {\"meeting_kind\": \"other\", \"attendees\": [\"Dana\", \"Ravi\", \"Maya\"], \"lead\": null, \"action_count\": 4, \"unowned\": \"none\", \"decision_count\": 0, \"follow_up_needed\": false, \"follow_up_when\": \"none\"}, \"end\": \"tracked\"}\n{\"name\": \"roadmap planning, owners inferred from roles\", \"input\": {\"notes\": \"Roadmap planning. The mobile team will take the offline mode spike in Q4. Design owes us the empty states - Kim is design lead. We agreed to drop the tablet layout entirely.\"}, \"expect\": {\"meeting_kind\": \"planning\", \"attendees\": [\"Kim\"], \"lead\": null, \"action_count\": 2, \"unowned\": \"none\", \"decision_count\": 1, \"follow_up_needed\": false, \"follow_up_when\": \"none\"}, \"end\": \"tracked\"}\n{\"name\": \"budget chat, an owed answer with no owner\", \"input\": {\"notes\": \"Budget chat, 15 minutes. Nothing signed off. Finance wants a number from us before the board meeting; we said we'd come back next week with one. Alex to pull last year's spend in the meantime.\"}, \"expect\": {\"meeting_kind\": \"other\", \"attendees\": [\"Alex\"], \"lead\": null, \"action_count\": 2, \"unowned\": \"some\", \"fallback_owner\": \"Alex\", \"fallback_basis\": \"only_attendee\", \"decision_count\": 0, \"follow_up_needed\": true, \"follow_up_when\": \"next_week\"}, \"end\": \"tracked\"}\n", "examples/meeting_actions/fakes/script.json": "{\n \"attendees step\": [\n \"{\\\"attendees\\\": [\\\"Ravi\\\", \\\"Sara\\\", \\\"Tom\\\"], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"standup\\\"}\",\n \"{\\\"attendees\\\": [\\\"Maya\\\"], \\\"lead\\\": \\\"Maya\\\", \\\"meeting_kind\\\": \\\"planning\\\"}\",\n \"{\\\"attendees\\\": [], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"other\\\"}\",\n \"{\\\"attendees\\\": [\\\"Dana\\\"], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"incident\\\"}\",\n \"{\\\"attendees\\\": [\\\"Priya\\\", \\\"Alex\\\"], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"client_call\\\"}\",\n \"{\\\"attendees\\\": [], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"review\\\"}\",\n \"{\\\"attendees\\\": [\\\"Jonas\\\"], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"one_on_one\\\"}\",\n \"{\\\"attendees\\\": [\\\"Ben\\\", \\\"Sara\\\", \\\"Tom\\\"], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"other\\\"}\",\n \"{\\\"attendees\\\": [], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"review\\\"}\",\n \"{\\\"attendees\\\": [\\\"Dana\\\", \\\"Ravi\\\", \\\"Maya\\\"], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"other\\\"}\",\n \"{\\\"attendees\\\": [\\\"Kim\\\"], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"planning\\\"}\",\n \"{\\\"attendees\\\": [\\\"Alex\\\"], \\\"lead\\\": null, \\\"meeting_kind\\\": \\\"other\\\"}\"\n ],\n \"actions reasoning step\": [\n \"Ravi said he is 'picking up the CSV importer today' and Sara 'will ping infra this morning'. Shipping the export fix is already done, so it is not an action.\",\n \"Two things have no name on them: 'someone needs to write the migration doc' and the pricing page copy that 'nobody picked up'. Maya 'will book time with legal next week' is hers.\",\n \"Nobody agreed to do anything. The notes say outright that there were 'no new commitments'.\",\n \"'The platform team owns that' names a team, not a person. 'Dana is writing the postmortem by Thursday' names a person and a date.\",\n \"Northwind 'want SSO' is their wish, not our commitment. Priya 'said she'd chase the vendor before Friday' and Alex 'has' the written scope are ours.\",\n \"'Both need fixing before the next release' is a commitment the room made, but 'no one volunteered', so neither item has a name on it.\",\n \"Jonas is 'taking over the billing alerts'. The dashboard cleanup is 'still open' and 'we didn't say who', so it has no owner.\",\n \"Three commitments: Ben 'he'll fix it today', Sara 'she'll do a pass this week', Ben 'said he'd start' the questionnaire. The hiring pipeline had 'nothing decided', and Tom only 'wants' the standup moved.\",\n \"'Nothing to do until the load test numbers come back' says outright that nobody took an action. The Postgres choice is a decision, not a task.\",\n \"Four commitments, each with a different horizon: today, this week, next week, and 'at some point this month'. Ravi 'said he'd try' still counts as taking it.\",\n \"'The mobile team will take' names a team. 'Design owes us the empty states' names a function, and the notes say 'Kim is design lead', so Kim carries it.\",\n \"'We said we'd come back next week with one' is a commitment the room made without naming anybody. 'Alex to pull last year's spend' names Alex.\"\n ],\n \"actions step\": [\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Pick up the CSV importer\\\", \\\"owner\\\": \\\"Ravi\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"today\\\", \\\"priority\\\": \\\"p2\\\"}, {\\\"task\\\": \\\"Ping infra about the staging cert\\\", \\\"owner\\\": \\\"Sara\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"today\\\", \\\"priority\\\": \\\"p1\\\"}], \\\"action_count\\\": 2, \\\"unowned\\\": \\\"none\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Write the migration doc\\\", \\\"owner\\\": null, \\\"owner_source\\\": \\\"unassigned\\\", \\\"due_bucket\\\": \\\"no_date\\\", \\\"priority\\\": \\\"p2\\\"}, {\\\"task\\\": \\\"Rewrite the pricing page copy\\\", \\\"owner\\\": null, \\\"owner_source\\\": \\\"unassigned\\\", \\\"due_bucket\\\": \\\"no_date\\\", \\\"priority\\\": \\\"p3\\\"}, {\\\"task\\\": \\\"Book time with legal\\\", \\\"owner\\\": \\\"Maya\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"next_week\\\", \\\"priority\\\": \\\"p2\\\"}], \\\"action_count\\\": 3, \\\"unowned\\\": \\\"some\\\"}\",\n \"{\\\"action_items\\\": [], \\\"action_count\\\": 0, \\\"unowned\\\": \\\"none\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Add a secondary to the oncall rota\\\", \\\"owner\\\": \\\"platform team\\\", \\\"owner_source\\\": \\\"inferred\\\", \\\"due_bucket\\\": \\\"this_week\\\", \\\"priority\\\": \\\"p1\\\"}, {\\\"task\\\": \\\"Write the outage postmortem\\\", \\\"owner\\\": \\\"Dana\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"this_week\\\", \\\"priority\\\": \\\"p1\\\"}], \\\"action_count\\\": 2, \\\"unowned\\\": \\\"none\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Chase the SSO vendor\\\", \\\"owner\\\": \\\"Priya\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"this_week\\\", \\\"priority\\\": \\\"p1\\\"}, {\\\"task\\\": \\\"Send Northwind the written scope\\\", \\\"owner\\\": \\\"Alex\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"next_week\\\", \\\"priority\\\": \\\"p1\\\"}], \\\"action_count\\\": 2, \\\"unowned\\\": \\\"none\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Fix the release checklist process\\\", \\\"owner\\\": null, \\\"owner_source\\\": \\\"unassigned\\\", \\\"due_bucket\\\": \\\"this_month\\\", \\\"priority\\\": \\\"p2\\\"}, {\\\"task\\\": \\\"Update the runbook\\\", \\\"owner\\\": null, \\\"owner_source\\\": \\\"unassigned\\\", \\\"due_bucket\\\": \\\"this_month\\\", \\\"priority\\\": \\\"p2\\\"}], \\\"action_count\\\": 2, \\\"unowned\\\": \\\"some\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Take over the billing alerts\\\", \\\"owner\\\": \\\"Jonas\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"this_week\\\", \\\"priority\\\": \\\"p2\\\"}, {\\\"task\\\": \\\"Do the dashboard cleanup\\\", \\\"owner\\\": null, \\\"owner_source\\\": \\\"unassigned\\\", \\\"due_bucket\\\": \\\"no_date\\\", \\\"priority\\\": \\\"p3\\\"}], \\\"action_count\\\": 2, \\\"unowned\\\": \\\"some\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Fix the failing analytics job\\\", \\\"owner\\\": \\\"Ben\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"today\\\", \\\"priority\\\": \\\"p1\\\"}, {\\\"task\\\": \\\"Do a pass over the docs site\\\", \\\"owner\\\": \\\"Sara\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"this_week\\\", \\\"priority\\\": \\\"p3\\\"}, {\\\"task\\\": \\\"Start the Northwind security questionnaire\\\", \\\"owner\\\": \\\"Ben\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"next_week\\\", \\\"priority\\\": \\\"p1\\\"}], \\\"action_count\\\": 3, \\\"unowned\\\": \\\"none\\\"}\",\n \"{\\\"action_items\\\": [], \\\"action_count\\\": 0, \\\"unowned\\\": \\\"none\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Run the backup restore test\\\", \\\"owner\\\": \\\"Dana\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"today\\\", \\\"priority\\\": \\\"p1\\\"}, {\\\"task\\\": \\\"Rotate the API keys\\\", \\\"owner\\\": \\\"Ravi\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"this_week\\\", \\\"priority\\\": \\\"p1\\\"}, {\\\"task\\\": \\\"Take the vendor review\\\", \\\"owner\\\": \\\"Maya\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"next_week\\\", \\\"priority\\\": \\\"p2\\\"}, {\\\"task\\\": \\\"Tidy the terraform\\\", \\\"owner\\\": \\\"Ravi\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"this_month\\\", \\\"priority\\\": \\\"p3\\\"}], \\\"action_count\\\": 4, \\\"unowned\\\": \\\"none\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Take the offline mode spike\\\", \\\"owner\\\": \\\"mobile team\\\", \\\"owner_source\\\": \\\"inferred\\\", \\\"due_bucket\\\": \\\"no_date\\\", \\\"priority\\\": \\\"p3\\\"}, {\\\"task\\\": \\\"Deliver the empty states\\\", \\\"owner\\\": \\\"Kim\\\", \\\"owner_source\\\": \\\"inferred\\\", \\\"due_bucket\\\": \\\"no_date\\\", \\\"priority\\\": \\\"p2\\\"}], \\\"action_count\\\": 2, \\\"unowned\\\": \\\"none\\\"}\",\n \"{\\\"action_items\\\": [{\\\"task\\\": \\\"Give Finance a budget number\\\", \\\"owner\\\": null, \\\"owner_source\\\": \\\"unassigned\\\", \\\"due_bucket\\\": \\\"next_week\\\", \\\"priority\\\": \\\"p1\\\"}, {\\\"task\\\": \\\"Pull last year's spend\\\", \\\"owner\\\": \\\"Alex\\\", \\\"owner_source\\\": \\\"explicit\\\", \\\"due_bucket\\\": \\\"this_week\\\", \\\"priority\\\": \\\"p2\\\"}], \\\"action_count\\\": 2, \\\"unowned\\\": \\\"some\\\"}\"\n ],\n \"assign step\": [\n \"{\\\"fallback_owner\\\": \\\"Maya\\\", \\\"fallback_basis\\\": \\\"meeting_lead\\\"}\",\n \"{\\\"fallback_owner\\\": null, \\\"fallback_basis\\\": \\\"unclear\\\"}\",\n \"{\\\"fallback_owner\\\": \\\"Jonas\\\", \\\"fallback_basis\\\": \\\"only_attendee\\\"}\",\n \"{\\\"fallback_owner\\\": \\\"Alex\\\", \\\"fallback_basis\\\": \\\"only_attendee\\\"}\"\n ],\n \"decisions step\": [\n \"{\\\"decisions\\\": [{\\\"decision\\\": \\\"Hold the 2.1 release until the staging cert is sorted\\\", \\\"firmness\\\": \\\"final\\\"}], \\\"decision_count\\\": 1}\",\n \"{\\\"decisions\\\": [{\\\"decision\\\": \\\"The onboarding rewrite lands this quarter\\\", \\\"firmness\\\": \\\"final\\\"}], \\\"decision_count\\\": 1}\",\n \"{\\\"decisions\\\": [], \\\"decision_count\\\": 0}\",\n \"{\\\"decisions\\\": [{\\\"decision\\\": \\\"Do not roll back 2.0\\\", \\\"firmness\\\": \\\"final\\\"}], \\\"decision_count\\\": 1}\",\n \"{\\\"decisions\\\": [{\\\"decision\\\": \\\"Commit to SSO for Northwind this quarter\\\", \\\"firmness\\\": \\\"tentative\\\"}], \\\"decision_count\\\": 1}\",\n \"{\\\"decisions\\\": [], \\\"decision_count\\\": 0}\",\n \"{\\\"decisions\\\": [{\\\"decision\\\": \\\"Jonas moves to the payments squad in September\\\", \\\"firmness\\\": \\\"final\\\"}], \\\"decision_count\\\": 1}\",\n \"{\\\"decisions\\\": [{\\\"decision\\\": \\\"Leave the standup at its current time\\\", \\\"firmness\\\": \\\"final\\\"}], \\\"decision_count\\\": 1}\",\n \"{\\\"decisions\\\": [{\\\"decision\\\": \\\"Use Postgres for the events table\\\", \\\"firmness\\\": \\\"tentative\\\"}], \\\"decision_count\\\": 1}\",\n \"{\\\"decisions\\\": [], \\\"decision_count\\\": 0}\",\n \"{\\\"decisions\\\": [{\\\"decision\\\": \\\"Drop the tablet layout entirely\\\", \\\"firmness\\\": \\\"final\\\"}], \\\"decision_count\\\": 1}\",\n \"{\\\"decisions\\\": [], \\\"decision_count\\\": 0}\"\n ],\n \"followup step\": [\n \"{\\\"follow_up_needed\\\": false, \\\"follow_up_when\\\": \\\"none\\\", \\\"follow_up_reason\\\": \\\"Not needed.\\\"}\",\n \"{\\\"follow_up_needed\\\": true, \\\"follow_up_when\\\": \\\"next_week\\\", \\\"follow_up_reason\\\": \\\"Two items still need real owners.\\\"}\",\n \"{\\\"follow_up_needed\\\": false, \\\"follow_up_when\\\": \\\"none\\\", \\\"follow_up_reason\\\": \\\"Not needed.\\\"}\",\n \"{\\\"follow_up_needed\\\": true, \\\"follow_up_when\\\": \\\"this_week\\\", \\\"follow_up_reason\\\": \\\"The postmortem still needs a read-out.\\\"}\",\n \"{\\\"follow_up_needed\\\": true, \\\"follow_up_when\\\": \\\"next_week\\\", \\\"follow_up_reason\\\": \\\"Northwind is waiting on the scope and the budget answer.\\\"}\",\n \"{\\\"follow_up_needed\\\": true, \\\"follow_up_when\\\": \\\"next_week\\\", \\\"follow_up_reason\\\": \\\"Nobody owns either retro item.\\\"}\",\n \"{\\\"follow_up_needed\\\": false, \\\"follow_up_when\\\": \\\"none\\\", \\\"follow_up_reason\\\": \\\"Not needed.\\\"}\",\n \"{\\\"follow_up_needed\\\": false, \\\"follow_up_when\\\": \\\"none\\\", \\\"follow_up_reason\\\": \\\"Not needed.\\\"}\",\n \"{\\\"follow_up_needed\\\": true, \\\"follow_up_when\\\": \\\"later\\\", \\\"follow_up_reason\\\": \\\"The choice gets revisited once the load test numbers land.\\\"}\",\n \"{\\\"follow_up_needed\\\": false, \\\"follow_up_when\\\": \\\"none\\\", \\\"follow_up_reason\\\": \\\"Not needed.\\\"}\",\n \"{\\\"follow_up_needed\\\": false, \\\"follow_up_when\\\": \\\"none\\\", \\\"follow_up_reason\\\": \\\"Not needed.\\\"}\",\n \"{\\\"follow_up_needed\\\": true, \\\"follow_up_when\\\": \\\"next_week\\\", \\\"follow_up_reason\\\": \\\"Finance is waiting on a number before the board meeting.\\\"}\"\n ]\n}\n", "examples/meeting_actions/grammars/actions.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"action_items\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"task\": {\"type\": \"string\"},\n \"owner\": {\"type\": [\"string\", \"null\"]},\n \"owner_source\": {\n \"type\": \"string\",\n \"enum\": [\"explicit\", \"inferred\", \"unassigned\"]\n },\n \"due_bucket\": {\n \"type\": \"string\",\n \"enum\": [\"today\", \"this_week\", \"next_week\", \"this_month\", \"no_date\"]\n },\n \"priority\": {\"type\": \"string\", \"enum\": [\"p1\", \"p2\", \"p3\"]}\n },\n \"required\": [\"task\", \"owner\", \"owner_source\", \"due_bucket\", \"priority\"],\n \"additionalProperties\": false\n }\n },\n \"action_count\": {\"type\": \"integer\"},\n \"unowned\": {\"type\": \"string\", \"enum\": [\"none\", \"some\"]}\n },\n \"required\": [\"action_items\", \"action_count\", \"unowned\"],\n \"additionalProperties\": false\n}\n", "examples/meeting_actions/grammars/assign.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"fallback_owner\": {\"type\": [\"string\", \"null\"]},\n \"fallback_basis\": {\n \"type\": \"string\",\n \"enum\": [\"meeting_lead\", \"only_attendee\", \"most_mentioned\", \"unclear\"]\n }\n },\n \"required\": [\"fallback_owner\", \"fallback_basis\"],\n \"additionalProperties\": false\n}\n", "examples/meeting_actions/grammars/attendees.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"attendees\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"}\n },\n \"lead\": {\"type\": [\"string\", \"null\"]},\n \"meeting_kind\": {\n \"type\": \"string\",\n \"enum\": [\"standup\", \"planning\", \"review\", \"client_call\", \"incident\",\n \"one_on_one\", \"other\"]\n }\n },\n \"required\": [\"attendees\", \"lead\", \"meeting_kind\"],\n \"additionalProperties\": false\n}\n", "examples/meeting_actions/grammars/decisions.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"decisions\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"decision\": {\"type\": \"string\"},\n \"firmness\": {\"type\": \"string\", \"enum\": [\"final\", \"tentative\"]}\n },\n \"required\": [\"decision\", \"firmness\"],\n \"additionalProperties\": false\n }\n },\n \"decision_count\": {\"type\": \"integer\"}\n },\n \"required\": [\"decisions\", \"decision_count\"],\n \"additionalProperties\": false\n}\n", "examples/meeting_actions/grammars/followup.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"follow_up_needed\": {\"type\": \"boolean\"},\n \"follow_up_when\": {\n \"type\": \"string\",\n \"enum\": [\"none\", \"this_week\", \"next_week\", \"later\"]\n },\n \"follow_up_reason\": {\"type\": \"string\"}\n },\n \"required\": [\"follow_up_needed\", \"follow_up_when\", \"follow_up_reason\"],\n \"additionalProperties\": false\n}\n", "examples/meeting_actions/graph.yaml": "# attendees -> actions -> (assign)? -> decisions -> followup -> tracked\n# \\__ on_fail ____________________________ needs_review\n#\n# One narrow job per node. Nothing here plans: the graph already decided the\n# order, so the model only ever fills one slot at a time.\n\nmax_steps: 12\n\nnodes:\n attendees:\n type: generate\n # Who was in the room, and what kind of meeting it was. Cheap, factual, and\n # first because every later node wants the roster.\n max_tokens: 96\n\n actions:\n type: generate\n # The one node with real judgement in it. Notes ramble: a commitment hides in\n # a subordinate clause (\"...though Priya said she'd chase the vendor\"), and\n # right next to it sits a wish nobody agreed to. Deciding that *and* filling\n # five typed slots per item on the first token is two jobs at once, so this\n # node thinks in plain sentences first and only then emits under its grammar\n # (docs/ARCHITECTURE.md, Bug 2). The notes are thrown away; only the list survives.\n two_stage: true\n think_max_tokens: 256\n max_tokens: 512\n # Deterministic invariants, checked before anything is committed:\n # - the count has to match the list it counts (a truncated array is the\n # classic way a small model's list output goes wrong, and it is silent),\n # - and \"some work is unowned\" cannot be true of an empty list.\n assert: action_count == len(action_items) and (unowned == \"none\" or action_count > 0)\n on_fail: needs_review\n\n assign:\n type: generate\n # Only reached when something is unowned. Unowned work quietly evaporates, so\n # somebody holds it until it is claimed. One slot, one name.\n max_tokens: 96\n # A basis of \"unclear\" is the only case where there is no name to give, and a\n # name is the only case where the basis is not \"unclear\".\n assert: (fallback_basis == \"unclear\") == (fallback_owner == null)\n on_fail: needs_review\n\n decisions:\n type: generate\n # Settled things, as opposed to things somebody has to go and do. Separate\n # node because \"was this decided or assigned?\" is a different question from\n # \"who does it\", and a node that answers two questions answers both worse.\n max_tokens: 256\n assert: decision_count == len(decisions)\n on_fail: needs_review\n\n followup:\n type: generate\n # Single-stage on purpose. By this point the hard reading is done and the\n # state is already structured, so this is a small rule over counts, not a\n # judgement over prose — a think pass here would buy tokens and nothing else.\n max_tokens: 128\n assert: follow_up_needed == (follow_up_when != \"none\")\n on_fail: needs_review\n\n tracked:\n type: end\n # stepmold's YAML subset takes a flow sequence only on one line, so this is a\n # block sequence rather than a wrapped [a, b, c].\n output:\n - meeting_kind\n - attendees\n - lead\n - action_items\n - action_count\n - unowned\n - fallback_owner\n - fallback_basis\n - decisions\n - decision_count\n - follow_up_needed\n - follow_up_when\n - follow_up_reason\n\n needs_review:\n type: end\n # A human gets the notes back plus whatever was verified before the node that\n # failed. Deliberately not the half-built action list: nothing unverified.\n output: [meeting_kind, attendees, lead]\n\nedges:\n - from: attendees\n to: actions\n\n # The conditional. Nothing is unowned in most meetings, and there is no point\n # asking a model who holds an empty set.\n - from: actions\n to: assign\n when: {unowned: some}\n\n - from: actions\n to: decisions\n\n - from: assign\n to: decisions\n\n - from: decisions\n to: followup\n\n - from: followup\n to: tracked\n", "examples/meeting_actions/manifest.yaml": "name: meeting_actions\nversion: 1\nentry: attendees\nmodel: fake:fakes/script.json\ndescription: >-\n Five-node meeting-notes workflow: read who was in the room, pull the action\n items out of the notes, give the unowned ones a holder, list the decisions,\n and say whether the group has to meet again.\n\n The model below is a scripted stand-in, so the evalset scores offline with no\n GPU and no network. It is keyed by node and replays each node's answers in\n evalset order, so a `stepmold run` of anything other than the first case will\n answer the first case. Point --model at a real backend to run real notes.\n", "examples/meeting_actions/prompts/actions.think.txt": "You are the actions reasoning step of a meeting-notes workflow.\n\nWrite two or three plain sentences listing every thing somebody agreed to do,\nand quote the words that made you call it a commitment.\n\nLeave out things that were only discussed, and things somebody wants but\nnobody agreed to.\n\nDo not answer in JSON. Do not pick owners, dates, or priorities yet.\n\nNotes: {notes}\n", "examples/meeting_actions/prompts/actions.txt": "You are the actions step of a meeting-notes workflow.\n\nList the action items. One item per thing somebody has to do.\n\nEach item has:\n task - what has to be done, under 10 words\n owner - a first name, or null if the notes name nobody\n owner_source - explicit the notes name this person for this task\n inferred the notes name a team or a role, not a person\n unassigned nobody was named (owner must be null)\n due_bucket - today, this_week, next_week, this_month, or no_date\n priority - p1 someone is blocked, or it is already late\n p2 normal work with a date on it\n p3 no date and nobody waiting\n\nThen answer:\n action_count - how many items you listed\n unowned - \"some\" when any item has owner null, otherwise \"none\"\n\nIf nobody agreed to do anything: empty list, action_count 0, unowned \"none\".\n\nPeople at the meeting: {attendees}\nNotes: {notes}\n", "examples/meeting_actions/prompts/assign.txt": "You are the assign step of a meeting-notes workflow.\n\nSome of these action items have no owner. Name one person to hold them until\nsomebody claims them.\n\nfallback_owner - a first name from the people below, or null when there is\n nobody sensible to pick\nfallback_basis - meeting_lead they ran the meeting\n only_attendee they are the only person named\n most_mentioned they come up most often in the notes\n unclear nobody sensible to pick\n\nAnswer null for fallback_owner when, and only when, the basis is unclear.\n\nPeople at the meeting: {attendees}\nPerson who ran it: {lead}\nNotes: {notes}\n", "examples/meeting_actions/prompts/attendees.txt": "You are the attendees step of a meeting-notes workflow.\n\nAnswer three things about the notes.\n\nattendees - every person named in the notes, as a list of first names.\n Use [] if the notes name nobody. People only: not teams,\n not companies, not job titles.\nlead - the person the notes say ran the meeting, or null.\n Do not guess. If the notes do not say, answer null.\nmeeting_kind - one of:\n standup a short status round\n planning deciding what to work on next\n review looking back at work already done\n client_call a call with someone outside the company\n incident something broke\n one_on_one two people only\n other anything else\n\nNotes: {notes}\n", "examples/meeting_actions/prompts/decisions.txt": "You are the decisions step of a meeting-notes workflow.\n\nList what the meeting settled. A decision is something that is now true.\nSomething a person still has to go and do is not a decision.\n\nEach decision has:\n decision - what was settled, under 15 words\n firmness - final it is settled\n tentative settled for now, and the notes say it may be revisited\n\nThen answer decision_count: how many decisions you listed.\n\nIf nothing was settled: empty list and decision_count 0.\n\nNotes: {notes}\n", "examples/meeting_actions/prompts/followup.txt": "You are the followup step of a meeting-notes workflow.\n\nSay whether these people have to meet about this again.\n\nA follow-up is needed when work is still unowned, when the notes leave\nsomething undecided, or when someone outside the meeting is waiting on an\nanswer. Otherwise it is not needed.\n\nfollow_up_needed - true or false\nfollow_up_when - none, this_week, next_week, or later.\n Answer none when follow_up_needed is false.\nfollow_up_reason - one sentence. Write \"Not needed.\" when it is false.\n\nMeeting kind: {meeting_kind}\nAction items: {action_count}\nUnowned work: {unowned}\nDecisions: {decision_count}\nNotes: {notes}\n", "examples/refund_desk/README.md": "# refund_desk — the pack that acts\n\nEvery other pack in `examples/` decides. This one decides and then *does*: it reads a real\norder out of a store, judges the claim, and — only when the judgement holds up — issues\nthe refund. It is the worked example for two capabilities that have tests but had no pack:\nthe `tool` node, and the confidence gate.\n\nFive working nodes and two endings:\n\n```\nclassify -> lookup -> assess -> approve -> refund -> done\ngenerate tool generate generate tool\n | |\n +---> needs_human <--+\n on_fail on_fail / on_unsure\n```\n\n| node | type | what it does | how it can go wrong |\n| --- | --- | --- | --- |\n| `classify` | generate | refund request, question, or complaint | a question or complaint leaves on an ordinary edge — `needs_human` |\n| `lookup` | tool `fetch_order` | reads the order from the host's store | an unknown order id raises; `on_fail: needs_human` |\n| `assess` | generate | is the refund justified, given what the store said | burns its ladder; `on_fail` is not set, so this one would abort the run |\n| `approve` | generate | the judgement the money moves on | `assert` catches a contradiction, `on_unsure` catches a coin flip; both go to `needs_human` |\n| `refund` | tool `issue_refund` | moves the money | `on_fail: needs_human` |\n| `done`, `needs_human` | end | the two endings the evalset holds under contract | — |\n\n## The gate comes before the action\n\n`approve` is the gated node: it draws several independent answers and commits only if\nenough of them agree, and a node that cannot agree with itself takes `on_unsure` to\n`needs_human`. `refund` — the node that moves money — sits *downstream* of that edge, and\nthere is no other way into it. Read the ordering off the graph rather than off this\nsentence: the only edge whose target is `refund` is the one `approve` takes when it is\nsure (`tests/test_example_refund.py:test_the_only_edge_into_refund_comes_from_approve`).\n\n(One honest caveat before the argument: the *exit* from the gate, `on_unsure:`, is in this\npack's graph.yaml. The *entrance*, `samples:`/`agree:`, cannot be written there yet — see\n\"What does not work\" below, and `gate_demo.py`, which runs the real gate on this real pack\nfrom Python.)\n\nThat ordering is the whole design, and reversing it is the obvious-looking mistake. A gate\nplaced *after* the action is a review: the money has already moved, the email has already\ngone, and being unsure now buys an apology and a reversal — assuming the action was\nreversible at all, which the interesting ones are not. A gate placed *before* the action is\na decision that never happened. Disagreement costs three generations and a row in a human\nqueue; that is the entire bill, because nothing downstream ever ran. A tool call is, in\n`stepmold/graph.py`'s own words, \"the one thing in a run that retrying cannot undo\" — so the\nonly place a doubt is cheap is upstream of the first side effect. Spend the confidence on\nthe decision, and let the action be the thing that happens when there is nothing left to\ndoubt.\n\n## How to run it\n\nThe tools are the host's, so the operator hands them over on the command line. There is\ndeliberately no manifest key for this (`stepmold/cli.py:_add_tools_option`): a pack you did not\nwrite must not be able to choose which code its tool names resolve to.\n\n```\n$ python3 -m stepmold eval examples/refund_desk --tools examples/refund_desk/tools.py\nrefund_desk: 12/12 cases passed\n```\n\n```\n$ python3 -m stepmold eval examples/refund_desk --tools examples/refund_desk/tools.py --tiers\nrefund_desk: 12/12 cases passed\nrefund_desk: 12 cases — 10 auto, 2 escalated, 0 failed\n auto 83.3% accuracy 100.0% (10/10 correct)\n escalated 16.7% at approve=1, lookup=1\n failed 0.0%\n```\n\nOne message at a time. Unlike the other example packs, the scripted model here is keyed on\nthe order id rather than on case order, so any single case answers itself:\n\n```\n$ python3 -m stepmold run examples/refund_desk --tools examples/refund_desk/tools.py \\\n --input '{\"message\":\"The mug arrived smashed in three pieces.\",\"order_id\":\"R-1001\"}'\n{\"approved\": true, \"justified\": true, \"kind\": \"refund\", \"order_status\": \"delivered\", \"refund_amount\": 49.99, \"refund_id\": \"RF-R-1001\"}\n\n$ python3 -m stepmold run examples/refund_desk --tools examples/refund_desk/tools.py \\\n --input '{\"message\":\"The lamp works fine, I just do not want it any more.\",\"order_id\":\"R-1007\"}'\n{\"approved\": false, \"justified\": false, \"kind\": \"refund\", \"order_status\": \"delivered\"}\n\n$ python3 -m stepmold run examples/refund_desk --tools examples/refund_desk/tools.py \\\n --input '{\"message\":\"I never got order R-9999 and I want a refund.\",\"order_id\":\"R-9999\"}'\n{\"kind\": \"refund\", \"order_id\": \"R-9999\"}\n```\n\nThe declined run has no `refund_id` and no `refund_amount` in it. That is not a null — an\nend node projects the keys state *has* (`graph._project`), and a run that never entered\n`refund` never wrote them.\n\nTwo scripts in this directory print the things a transcript shows better than prose:\n\n```\n$ python3 examples/refund_desk/gate_demo.py # the gate, three times over\n$ python3 examples/refund_desk/once_only.py # crash mid-refund, resume, count the money\n```\n\n## The two tools\n\n`tools.py` is the host half: an in-memory order store, the two functions, and the\n`ToolRegistry` that exposes them. The pack names `fetch_order` and `issue_refund` and\ncontains neither. They are deliberately not the same kind of thing:\n\n| | `fetch_order` | `issue_refund` |\n| --- | --- | --- |\n| what it does | reads one order | moves money, appends to the ledger |\n| `reads` | `order_id` | `order_id`, `order_total` |\n| `writes` | `order_total`, `order_status`, `days_since_delivery` | `refund_id`, `refund_amount` |\n| `idempotent=` | `True` | `False` |\n| in the checkpoint | nothing | the node, the tool, the arguments, the result |\n| a resumed run | reads again | replays the recorded result |\n\nThe bookkeeping is the price of not being repeatable, and only the tool that is not\nrepeatable pays it. `python3 examples/refund_desk/once_only.py` kills a run inside the few\nmicroseconds between `issue_refund` returning and the walk leaving its node, then resumes\nit:\n\n```\ncrashed: worker killed after the refund, before the edge\nledger after the crash [{'order_id': 'R-1001', 'refund_id': 'RF-R-1001', 'amount': 49.99}]\ncheckpoint next_node refund\ncheckpoint tool_calls [{'args': {'order_id': 'R-1001', 'order_total': 49.99}, 'node': 'refund', 'result': {'refund_amount': 49.99, 'refund_id': 'RF-R-1001'}, 'tool': 'issue_refund'}]\n\nresumed to done\nledger after the resume [{'order_id': 'R-1001', 'refund_id': 'RF-R-1001', 'amount': 49.99}]\nrefunds for R-1001 1\noutput {'kind': 'refund', 'order_status': 'delivered', 'justified': True, 'approved': True, 'refund_id': 'RF-R-1001', 'refund_amount': 49.99}\n```\n\n`next_node` still says `refund` because the row is written *before* the commit and before\nthe edge — everything after that line may die, and the resume lands back on the node and\nreplays. Committed state could not have answered this: it records what a call returned,\nnever that it happened. The ledger counts calls, which is why it is the assertion.\n\n## What does not work\n\nThe most useful part of this file. Most lines below are pinned by a test in tests/test_example_refund.py, so they cannot rot into a false claim. The exception is noted where it appears.\n`tests/test_example_refund.py`, so it cannot rot into a false claim.\n\n**`samples:` and `agree:` cannot be written in graph.yaml.** This is the big one, and it is why the gate below is demonstrated by a script rather than by a line in this pack's graph.\n`stepmold.pack._NODE_KEYS` does not carry them and `stepmold.pack.Node` has no field for them, so the\ngraph in this directory declares only the gate's *exit*:\n\n```\n$ cp -r examples/refund_desk /tmp/rd-samples\n$ python3 -c \"\nimport pathlib\np = pathlib.Path('/tmp/rd-samples/graph.yaml')\np.write_text(p.read_text().replace(\n ' on_unsure: needs_human',\n ' samples: 3\\n agree: 2\\n on_unsure: needs_human'))\n\"\n$ python3 -m stepmold validate /tmp/rd-samples\nstepmold: pack error: graph.yaml: node 'approve' has unknown key(s): agree, samples\n```\n\nThe gate itself is real and shipped: `stepmold.verify.gate_for` reads the two keys off the node\nwith `getattr`, `run_node` draws and compares, and `stepmold.graph` routes `Unsure` to\n`on_unsure` (which *is* a pack key today). What is missing is one line of the pack format.\nSo `gate_demo.py` attaches the keys from Python — the same stand-in\n`tests/test_verify.py:GatedNode` uses, for the same stated reason — and runs the real gate\nagainst this real pack:\n\n```\nAGREED (draw 1 == draw 2)\n draws true, true, false\n log WARNING stepmold.verify node.samples.blind node=approve samples=3 model=FakeModel reason=\"backend takes no sampling hint, so extra draws repeat the first\"\n log INFO stepmold.verify node.agreed node=approve agreed=2 of=2 required=2 asked=3 generations=2\n path classify -> lookup -> assess -> approve -> refund -> done\n end node done\n ledger [{'order_id': 'R-1001', 'refund_id': 'RF-R-1001', 'amount': 49.99}]\n refunded? True\n\nUNSURE (a real disagreement)\n draws true, false, true\n log WARNING stepmold.verify node.samples.blind node=approve samples=3 model=FakeModel reason=\"backend takes no sampling hint, so extra draws repeat the first\"\n log WARNING stepmold.verify node.unsure node=approve agreed=1 of=3 required=2 asked=3 distinct=3 generations=3\n log INFO stepmold.graph edge.on_unsure run_id=d6b459e49e7e4565964f3ab648474dc9 node=approve to=needs_human\n path classify -> lookup -> assess -> approve -> needs_human\n end node needs_human\n ledger []\n refunded? False\n\nUNSURE (same decision, three wordings)\n draws true, true, true\n log WARNING stepmold.verify node.samples.blind node=approve samples=3 model=FakeModel reason=\"backend takes no sampling hint, so extra draws repeat the first\"\n log WARNING stepmold.verify node.unsure node=approve agreed=1 of=3 required=2 asked=3 distinct=3 generations=3\n log INFO stepmold.graph edge.on_unsure run_id=532fed4bba0642efa98b7c0da5e08c22 node=approve to=needs_human\n path classify -> lookup -> assess -> approve -> needs_human\n end node needs_human\n ledger []\n refunded? False\n```\n\nBecause the entrance is Python-only, `evalset.jsonl` has **no case that ends at\n`needs_human` by way of `on_unsure`** — the four that land there get there by an ordinary\nedge (a question, a complaint) or by `on_fail` (an unknown order, a burnt ladder). Read\nthat gap as a limit of the pack format, not of the gate.\n\n**All three draws said `approved: true` and the gate still refused.** Look at the third\nattempt above: `distinct=3`, and no refund. Agreement is on the *whole object the node\nwould commit* (`verify._canonical`), not on the field you care about, and the `rationale`\nstring differed three ways. This is the trap to know about before putting a gate on a wide\nnode. A gate that should be about a decision needs a node that commits the decision alone —\nnarrow the grammar, or split the node.\n\n**`node.samples.blind` fires on every sampled run here.** `FakeModel.generate` has no\n`sampling` keyword, so `codegen.accepts_sampling` is false and stepmold warns that the extra\ndraws would be the first draw repeated. It is right to warn: against a real greedy backend\nthey would be. The draws in `gate_demo.py` differ only because the script says they do —\nscripted disagreement, not measured disagreement. Nothing here is evidence about how often\na real model agrees with itself.\n\n**Without `--tools` the pack does not run at all**, and it fails ten cases rather than\nsaying so once:\n\n```\n$ python3 -m stepmold eval examples/refund_desk\nrefund_desk: 2/12 cases passed\n FAIL damaged on arrival -> refunded [lookup]\n error: ToolsNotAvailable: node 'lookup' is a tool node, and this run was given no tools: this pack needs tools; pass tools= to run()\n ...\n failures by node: lookup=10\n```\n\nExit status 1. The two that \"pass\" are the question and the complaint, which never reach a\ntool node. `--tools` exists on `run` and `eval` only.\n\n**`stepmold validate` now takes `--tools`**, so the load-time tool checks — is this name\nregistered, and can its `reads` be satisfied by this graph — never run from the command\nline. `stepmold.pack.check_tools` is reachable only as `load_pack(path, tools=registry)` from\nPython. A clean `stepmold validate` on a pack with tool nodes says nothing about its wiring.\n\n**Scoring this pack moves money.** `stepmold eval` is not a dry run: five of the twelve cases\nreach `refund`, and a scored run leaves five entries in the ledger. The store is in memory\nand dies with the process, which is the only reason this is safe to ship.\n\n**`issue_refund` raises `AlreadyRefunded` on a repeat.** Nothing in the evalset or the\ntests ever triggers it — that is the point of it. It is the alarm that would go off if\nstepmold's exactly-once record stopped working, instead of a quiet second row in the ledger.\n\n**The model is a script, not a model.** `fakes/script.json` is keyed on the footer line\neach prompt ends with (`Refund desk / approve / order R-1001`), which is what lets a single\n`stepmold run` answer its own case instead of the first one. The footer means nothing to a real\nbackend. Point `--model` at one to run real messages, and expect the numbers above to\nchange.\n\n## Files\n\n| file | what it is |\n| --- | --- |\n| `manifest.yaml` | name, entry, the scripted model, and the two inputs |\n| `graph.yaml` | five working nodes, two endings, and the comment explaining the missing gate keys |\n| `prompts/*.txt` | one per generate node; each ends with the footer the script keys on |\n| `grammars/*.json` | the schema each generate node is verified against |\n| `fakes/script.json` | 30 entries keyed by node and order id; 29 hold one response, and `approve / order R-1010` holds the three that burn a ladder |\n| `evalset.jsonl` | 12 cases: 5 refunded, 3 declined, 4 to a human, 2 of them `rescued: true` |\n| `tools.py` | the host: the order store, the two actions, and the `ToolRegistry` |\n| `gate_demo.py` | the confidence gate, three times, with the ledger printed |\n| `once_only.py` | crash mid-refund, resume, and count the money |\n", "examples/refund_desk/evalset.jsonl": "{\"name\": \"damaged on arrival -> refunded\", \"input\": {\"message\": \"The mug arrived smashed in three pieces.\", \"order_id\": \"R-1001\"}, \"expect\": {\"kind\": \"refund\", \"order_status\": \"delivered\", \"justified\": true, \"approved\": true, \"refund_id\": \"RF-R-1001\", \"refund_amount\": 49.99}, \"end\": \"done\"}\n{\"name\": \"changed their mind, 45 days on -> no refund\", \"input\": {\"message\": \"I have changed my mind about the jacket and would like my money back.\", \"order_id\": \"R-1002\"}, \"expect\": {\"kind\": \"refund\", \"justified\": false, \"approved\": false}, \"end\": \"done\"}\n{\"name\": \"no such order -> the lookup tool raises\", \"input\": {\"message\": \"I never got order R-9999 and I want a refund.\", \"order_id\": \"R-9999\"}, \"expect\": {\"kind\": \"refund\", \"order_id\": \"R-9999\"}, \"end\": \"needs_human\", \"rescued\": true}\n{\"name\": \"carrier lost it -> refunded\", \"input\": {\"message\": \"Tracking has said the same thing for two weeks and nothing has arrived.\", \"order_id\": \"R-1004\"}, \"expect\": {\"kind\": \"refund\", \"order_status\": \"lost\", \"justified\": true, \"approved\": true, \"refund_id\": \"RF-R-1004\", \"refund_amount\": 32.0}, \"end\": \"done\"}\n{\"name\": \"a question is not a refund request\", \"input\": {\"message\": \"How do I track this order?\", \"order_id\": \"R-1005\"}, \"expect\": {\"kind\": \"question\", \"order_id\": \"R-1005\"}, \"end\": \"needs_human\"}\n{\"name\": \"charged twice -> refunded\", \"input\": {\"message\": \"I was charged twice for this order, two identical charges on my card.\", \"order_id\": \"R-1006\"}, \"expect\": {\"kind\": \"refund\", \"justified\": true, \"approved\": true, \"refund_id\": \"RF-R-1006\", \"refund_amount\": 75.0}, \"end\": \"done\"}\n{\"name\": \"buyer's remorse, 60 days on -> no refund\", \"input\": {\"message\": \"The lamp works fine, I just do not want it any more.\", \"order_id\": \"R-1007\"}, \"expect\": {\"kind\": \"refund\", \"justified\": false, \"approved\": false}, \"end\": \"done\"}\n{\"name\": \"a complaint is not a refund request\", \"input\": {\"message\": \"Your support line kept me on hold for an hour and nobody called back.\", \"order_id\": \"R-1008\"}, \"expect\": {\"kind\": \"complaint\", \"order_id\": \"R-1008\"}, \"end\": \"needs_human\"}\n{\"name\": \"wrong item shipped -> refunded\", \"input\": {\"message\": \"You sent me the wrong item, I ordered the blue one.\", \"order_id\": \"R-1009\"}, \"expect\": {\"kind\": \"refund\", \"justified\": true, \"approved\": true, \"refund_id\": \"RF-R-1009\", \"refund_amount\": 15.0}, \"end\": \"done\"}\n{\"name\": \"approve burns its ladder -> nothing is issued\", \"input\": {\"message\": \"it is sort of broken but also i think i ordered the wrong one anyway???\", \"order_id\": \"R-1010\"}, \"expect\": {\"kind\": \"refund\", \"justified\": true, \"order_id\": \"R-1010\"}, \"end\": \"needs_human\", \"rescued\": true}\n{\"name\": \"not delivered yet -> no refund\", \"input\": {\"message\": \"I want to cancel and get my money back before it arrives.\", \"order_id\": \"R-1011\"}, \"expect\": {\"kind\": \"refund\", \"order_status\": \"in_transit\", \"justified\": false, \"approved\": false}, \"end\": \"done\"}\n{\"name\": \"cracked screen out of the box -> refunded\", \"input\": {\"message\": \"The screen was cracked when I opened the box.\", \"order_id\": \"R-1012\"}, \"expect\": {\"kind\": \"refund\", \"justified\": true, \"approved\": true, \"refund_id\": \"RF-R-1012\", \"refund_amount\": 149.99}, \"end\": \"done\"}\n", "examples/refund_desk/fakes/script.json": "{\n \"Refund desk / classify / order R-1001\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1001\": \"{\\\"justified\\\": true, \\\"grounds\\\": \\\"The order was delivered 3 days ago and arrived damaged.\\\"}\",\n \"Refund desk / approve / order R-1001\": \"{\\\"approved\\\": true, \\\"rationale\\\": \\\"Damage on a delivery three days old is ours to make good.\\\"}\",\n \"Refund desk / classify / order R-1002\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1002\": \"{\\\"justified\\\": false, \\\"grounds\\\": \\\"Delivery was 45 days ago, outside the 30-day window, and nothing is faulty.\\\"}\",\n \"Refund desk / approve / order R-1002\": \"{\\\"approved\\\": false, \\\"rationale\\\": \\\"The assessment found no fault and the window has closed.\\\"}\",\n \"Refund desk / classify / order R-9999\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / classify / order R-1004\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1004\": \"{\\\"justified\\\": true, \\\"grounds\\\": \\\"The order store has this order as lost, so it never arrived.\\\"}\",\n \"Refund desk / approve / order R-1004\": \"{\\\"approved\\\": true, \\\"rationale\\\": \\\"An order the carrier lost is refundable without argument.\\\"}\",\n \"Refund desk / classify / order R-1005\": \"{\\\"kind\\\": \\\"question\\\"}\",\n \"Refund desk / classify / order R-1006\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1006\": \"{\\\"justified\\\": true, \\\"grounds\\\": \\\"Delivered 9 days ago and the customer was charged twice for it.\\\"}\",\n \"Refund desk / approve / order R-1006\": \"{\\\"approved\\\": true, \\\"rationale\\\": \\\"A duplicate charge inside the window is a real fault.\\\"}\",\n \"Refund desk / classify / order R-1007\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1007\": \"{\\\"justified\\\": false, \\\"grounds\\\": \\\"Delivered 60 days ago and the customer says the lamp works.\\\"}\",\n \"Refund desk / approve / order R-1007\": \"{\\\"approved\\\": false, \\\"rationale\\\": \\\"Nothing is wrong with the order and the window has closed.\\\"}\",\n \"Refund desk / classify / order R-1008\": \"{\\\"kind\\\": \\\"complaint\\\"}\",\n \"Refund desk / classify / order R-1009\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1009\": \"{\\\"justified\\\": true, \\\"grounds\\\": \\\"The wrong item was shipped, six days ago.\\\"}\",\n \"Refund desk / approve / order R-1009\": \"{\\\"approved\\\": true, \\\"rationale\\\": \\\"We shipped the wrong item, so the refund stands.\\\"}\",\n \"Refund desk / classify / order R-1010\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1010\": \"{\\\"justified\\\": true, \\\"grounds\\\": \\\"Delivered 4 days ago and the customer reports a fault.\\\"}\",\n \"Refund desk / approve / order R-1010\": [\n \"{\\\"approved\\\": \\\"yes\\\", \\\"rationale\\\": \\\"I think so.\\\"}\",\n \"{\\\"approved\\\": \\\"probably\\\", \\\"rationale\\\": \\\"Hard to say.\\\"}\",\n \"{\\\"approved\\\": \\\"maybe\\\", \\\"rationale\\\": \\\"Could go either way.\\\"}\"\n ],\n \"Refund desk / classify / order R-1011\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1011\": \"{\\\"justified\\\": false, \\\"grounds\\\": \\\"The order is still in transit, so there is nothing to refund yet.\\\"}\",\n \"Refund desk / approve / order R-1011\": \"{\\\"approved\\\": false, \\\"rationale\\\": \\\"Nothing has been delivered, so no refund is due yet.\\\"}\",\n \"Refund desk / classify / order R-1012\": \"{\\\"kind\\\": \\\"refund\\\"}\",\n \"Refund desk / assess / order R-1012\": \"{\\\"justified\\\": true, \\\"grounds\\\": \\\"Delivered 2 days ago with a cracked screen.\\\"}\",\n \"Refund desk / approve / order R-1012\": \"{\\\"approved\\\": true, \\\"rationale\\\": \\\"A cracked screen out of the box is a fault we cover.\\\"}\"\n}\n", "examples/refund_desk/gate_demo.py": "\"\"\"The confidence gate, on this pack, with the money in view.\n\nRun it:\n\n python3 examples/refund_desk/gate_demo.py\n\n`approve` is the node the refund hangs off. This script runs it three times against the same\norder and the same graph, changing one thing: whether the model's independent draws agree.\n\n draws agree -> approve commits -> refund -> done ledger: 1 entry\n draws disagree -> verify raises Unsure -> on_unsure ledger: 0 entries\n\nThat is the ordering the whole design is about. The gate is spent on the *decision*, and\nthe action is downstream of it, so a coin flip never reaches `issue_refund` at all — there\nis nothing to undo, because nothing was done.\n\nWHY THIS IS A SCRIPT AND NOT A LINE IN graph.yaml\n-------------------------------------------------\n`samples:` and `agree:` are not in `stepmold.pack._NODE_KEYS`, so a graph.yaml that names them\nis refused at load — `stepmold.pack.Node` has no field for them yet. `stepmold.verify.gate_for`\nreads them off the node with `getattr`, which is what lets this script attach them from\nPython and get the real, shipped gate. `tests/test_verify.py:GatedNode` does exactly the\nsame thing, and for the same stated reason.\n\n`on_unsure:` IS a pack key today (`stepmold/pack.py:_NODE_KEYS`, and the walker routes it at\n`stepmold/graph.py`, the `except Unsure` clause), so the edge this demo takes is the one\ngraph.yaml already declares. Only the entrance to the gate is missing.\n\"\"\"\n\nimport dataclasses\nimport io\nimport json\nimport os\nimport sys\n\nHERE = os.path.dirname(os.path.abspath(__file__))\nsys.path.insert(0, os.path.dirname(os.path.dirname(HERE)))\nsys.path.insert(0, HERE)\n\nfrom stepmold.graph import run # noqa: E402\nfrom stepmold.log import configure # noqa: E402\nfrom stepmold.model import FakeModel # noqa: E402\nfrom stepmold.pack import Node, load_pack # noqa: E402\n\nfrom tools import RefundDesk # noqa: E402\n\nORDER = \"R-1001\"\n\n\ndef gate(pack, node_name, samples, agree):\n \"\"\"Dial one node's gate to a chosen setting.\n\n graph.yaml already asks for samples: 3 / agree: 2 on `approve`, so calling this with\n those numbers changes nothing — it stays so the demo can vary them. It used to build a\n `Node` subclass, because `samples:` and `agree:` were not loader keys and a pack could\n not spell its own gate.\n \"\"\"\n pack.nodes[node_name] = dataclasses.replace(\n pack.nodes[node_name], samples=samples, agree=agree)\n return pack\n\n\ndef model_for(approve_draws):\n \"\"\"The scripted desk, with `approve` answering a list of draws in order.\"\"\"\n return FakeModel({\n \"Refund desk / classify / order %s\" % ORDER: '{\"kind\": \"refund\"}',\n \"Refund desk / assess / order %s\" % ORDER:\n '{\"justified\": true, \"grounds\": \"Delivered 3 days ago and arrived damaged.\"}',\n \"Refund desk / approve / order %s\" % ORDER: list(approve_draws),\n })\n\n\n# stepmold is a library and logs nothing until an application switches it on. This script is\n# the application, and the gate's own lines -- node.agreed, node.unsure, and the\n# node.samples.blind warning below -- are most of what there is to see.\nLOG = io.StringIO()\nconfigure(level=\"info\", stream=LOG)\n\nGATE_EVENTS = (\"node.samples.blind\", \"node.agreed\", \"node.unsure\", \"edge.on_unsure\")\n\n\ndef gate_log():\n \"\"\"The lines this attempt wrote about the gate, with the timestamp trimmed off.\"\"\"\n lines = LOG.getvalue().splitlines()\n LOG.seek(0)\n LOG.truncate(0)\n return [line.split(\" \", 1)[1] for line in lines\n if any(name in line for name in GATE_EVENTS)]\n\n\ndef attempt(label, approve_draws):\n desk = RefundDesk()\n pack = gate(load_pack(HERE), \"approve\", samples=3, agree=2)\n result = run(\n pack,\n model_for(approve_draws),\n {\"message\": \"The mug arrived smashed in three pieces.\", \"order_id\": ORDER},\n tools=desk.registry(),\n )\n print(\"%s\" % label)\n print(\" draws %s\" % \", \".join(\n json.dumps(json.loads(draw)[\"approved\"]) for draw in approve_draws))\n for line in gate_log():\n print(\" log %s\" % line)\n print(\" path %s\" % \" -> \".join(result.path))\n print(\" end node %s\" % result.end_node)\n print(\" ledger %r\" % (desk.ledger,))\n print(\" refunded? %s\" % desk.is_refunded(ORDER))\n print()\n\n\nAGREE = '{\"approved\": true, \"rationale\": \"Damage three days after delivery is ours.\"}'\nDISSENT = '{\"approved\": false, \"rationale\": \"The customer may have dropped it.\"}'\nAGREE_OTHER_WORDS = '{\"approved\": true, \"rationale\": \"Cheaper to refund than to argue.\"}'\nAGREE_THIRD_WORDS = '{\"approved\": true, \"rationale\": \"The photo shows a clean break.\"}'\n\n\nif __name__ == \"__main__\":\n # Two of three draws match, so the gate opens on the second draw and never pays for\n # the third: `verify.run_node` short-circuits the moment the answer cannot change.\n # Read `generations=2` in the node.agreed line -- `samples: 3` is a ceiling, not a bill.\n attempt(\"AGREED (draw 1 == draw 2)\", [AGREE, AGREE, DISSENT])\n\n # Three valid answers, three different objects, no group of two. Every draw was a\n # legal answer -- that is why this is `Unsure` and not `NodeFailed`, and why it takes\n # `on_unsure` rather than `on_fail`.\n attempt(\"UNSURE (a real disagreement)\", [AGREE, DISSENT, AGREE_OTHER_WORDS])\n\n # The one that will surprise you, and the reason this script prints three attempts.\n # All three draws say `approved: true`. The gate still calls it unsure, because it\n # compares the whole object it would commit (`verify._canonical`) and the rationale\n # differs three ways. Look at `distinct=3` in the node.unsure line.\n #\n # This is not a bug to route around; it is the cost of a wide node. A node whose\n # gate should be about the decision alone must commit the decision alone -- move\n # `rationale` to a node of its own, or drop it from the grammar.\n attempt(\"UNSURE (same decision, three wordings)\",\n [AGREE, AGREE_OTHER_WORDS, AGREE_THIRD_WORDS])\n", "examples/refund_desk/grammars/approve.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"approved\": {\"type\": \"boolean\"},\n \"rationale\": {\"type\": \"string\"}\n },\n \"required\": [\"approved\", \"rationale\"],\n \"additionalProperties\": false\n}\n", "examples/refund_desk/grammars/assess.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"justified\": {\"type\": \"boolean\"},\n \"grounds\": {\"type\": \"string\"}\n },\n \"required\": [\"justified\", \"grounds\"],\n \"additionalProperties\": false\n}\n", "examples/refund_desk/grammars/classify.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"type\": \"string\",\n \"enum\": [\"refund\", \"question\", \"complaint\"]\n }\n },\n \"required\": [\"kind\"],\n \"additionalProperties\": false\n}\n", "examples/refund_desk/graph.yaml": "# classify -> lookup (tool) -> assess -> approve -> refund (tool) -> done\n# | | \n# +-> needs_human <---------+\n#\n# Two things here are worth reading slowly.\n#\n# 1. The order of the last three nodes. `approve` is the judgement call and\n# `refund` is the irreversible one, and the judgement is spent BEFORE the\n# action, never after it. There is no edge that reaches `refund` except the\n# one `approve` takes when it is sure; every other way out of `approve`\n# lands somewhere a human can still say no.\n#\n# 2. `on_unsure:` on `approve`. That edge is the confidence gate's exit: when a\n# node draws several independent samples and they do not agree, the run is\n# routed here instead of committing an answer nobody stands behind.\n#\n# The gate's entrance is `samples:` and `agree:` on the node below. `approve`\n# draws three independent times and needs two to match before the answer is\n# committed; three different answers route here instead. The money is the\n# reason: an irreversible action should cost more than one opinion.\n#\n# A pack that writes `on_unsure:` without `samples:` is now refused at load,\n# because that edge could never be taken — see `stepmold.pack._check_gates`.\n# gate_demo.py in this directory shows the split verdict happening.\n\nmax_steps: 12\n\nnodes:\n classify:\n type: generate\n # What kind of message is this at all? A question or a complaint is not a\n # refund request, and nothing below it should run for one.\n max_tokens: 32\n\n lookup:\n type: tool\n # `fetch_order` reads `order_id` and merges the order into state. Declared\n # idempotent by the host, so it is never written into the checkpoint and a\n # resumed run simply reads again — which is the correct trade for a read.\n tool: fetch_order\n # An order id that is not in the store raises out of the tool. A tool node\n # has no retry ladder on purpose (`retries:` is refused on one), so the\n # only answer to a failed call is this edge.\n on_fail: needs_human\n\n assess:\n type: generate\n # The claim, weighed against what the store actually said. This node sees\n # the order total, its status, and how long ago it was delivered, so the\n # judgement below is made on facts rather than on the customer's summary.\n max_tokens: 128\n\n approve:\n type: generate\n max_tokens: 128\n # Three draws, two must agree. The third is only paid for when the first two\n # differ, so agreement costs two calls and only a genuine disagreement costs\n # three. Agreement is on the whole committed object, not on `approved` alone.\n samples: 3\n agree: 2\n # The deterministic half of the gate, checked before anything is committed:\n # a refund that `assess` found unjustified cannot be approved, whatever the\n # model says. `assert` catches a contradiction; `on_unsure` catches a\n # coin flip. They are different failures and they have different edges.\n assert: justified or not approved\n on_fail: needs_human\n on_unsure: needs_human\n\n refund:\n type: tool\n # The only node in any example pack that changes something outside the run.\n # `issue_refund` is NOT idempotent, so the walker records the call and its\n # result in the checkpoint before committing, and a resumed run replays the\n # record instead of moving the money twice.\n tool: issue_refund\n on_fail: needs_human\n\n done:\n type: end\n # `refund_id` and `refund_amount` are absent from this projection whenever\n # the run reached `done` without passing through `refund` — an end node\n # projects the keys state has (`graph._project`), not the keys it names.\n output: [kind, order_status, justified, approved, refund_id, refund_amount]\n\n needs_human:\n type: end\n output: [kind, order_id]\n\nedges:\n - from: classify\n to: lookup\n when: {kind: refund}\n\n - from: classify\n to: needs_human\n\n - from: lookup\n to: assess\n\n - from: assess\n to: approve\n\n - from: approve\n to: refund\n when: {approved: true}\n\n - from: approve\n to: done\n\n - from: refund\n to: done\n", "examples/refund_desk/manifest.yaml": "name: refund_desk\nversion: 1\nentry: classify\nmodel: fake:fakes/script.json\ninputs: [message, order_id]\ndescription: >-\n The pack that acts. Seven nodes: classify, look the order up with a tool, assess\n the claim, decide, and — only when the decision holds up — issue the refund\n with a second tool.\n\n Two tools, and they are not the same kind of thing. `fetch_order` reads, is\n declared idempotent, and costs nothing to repeat. `issue_refund` moves money,\n is not idempotent, and is written into the checkpoint before it is committed so\n a run that dies mid-refund resumes without issuing a second one.\n\n The tools live in tools.py next to this manifest and must be handed to the\n runtime by the operator: `--tools examples/refund_desk/tools.py`. A pack names\n an action; it never contains one. Without that flag this pack does not run —\n see README.md, which prints the exact refusal.\n\n The model below is a scripted stand-in, so the evalset scores offline with no\n GPU and no network. Unlike the other example packs its script is keyed on the\n order id rather than on case order, so `stepmold run` of any single case answers\n that case. Point --model at a real backend to run real messages.\n", "examples/refund_desk/once_only.py": "\"\"\"Exactly-once, with the money in view.\n\nRun it:\n\n python3 examples/refund_desk/once_only.py\n\nThe run is killed inside the few microseconds that matter: after `issue_refund` has\nreturned and before the walk has left the `refund` node. Then it is resumed. The ledger\nhas one entry both times.\n\nCommitted state cannot answer \"did the money move?\" — it records what a call *returned*,\nnever that it *happened*, so a resumed run that trusted state alone would call again. What\nstops it is a row the walker writes before the commit (`stepmold/graph.py`, the `tool` branch:\n\"Written down before the commit and before the edge, with `next_node` still this node\nbecause the walk has not left it\"), carrying the node, the tool, the arguments it was\ngiven, and the result. The resume lands back on the node, finds the row, and replays it.\n\n`fetch_order` gets none of this, and does not want it: it is declared `idempotent=True`,\nso its checkpoint stays empty and a resumed run simply reads the order again. The\nbookkeeping is the price of not being repeatable, and only the tool that is not\nrepeatable pays it.\n\"\"\"\n\nimport os\nimport sys\n\nHERE = os.path.dirname(os.path.abspath(__file__))\nsys.path.insert(0, os.path.dirname(os.path.dirname(HERE)))\nsys.path.insert(0, HERE)\n\nfrom stepmold.cli import resolve_model # noqa: E402\nfrom stepmold.graph import run # noqa: E402\nfrom stepmold.pack import load_pack # noqa: E402\nfrom stepmold.state import Store, resume # noqa: E402\n\nfrom tools import RefundDesk # noqa: E402\n\nORDER = \"R-1001\"\nMESSAGE = {\"message\": \"The mug arrived smashed in three pieces.\", \"order_id\": ORDER}\n\n\nclass Crash(Exception):\n \"\"\"Not a stepmold error. The worker died; it did not fail, and nothing catches this.\"\"\"\n\n\nclass DyingStore(Store):\n \"\"\"A real store whose worker is killed at the save that would settle the refund.\n\n A checkpointed run cannot be interrupted convincingly from outside — the window is a\n few microseconds wide and the store is the only thing called inside it. Staging the\n kill from here leaves on disk exactly what a real crash would have left.\n \"\"\"\n\n def save(self, **checkpoint):\n if checkpoint.get(\"node\") == \"refund\" \\\n and checkpoint.get(\"next_node\") == \"done\":\n raise Crash(\"worker killed after the refund, before the edge\")\n return Store.save(self, **checkpoint)\n\n\ndef main():\n desk = RefundDesk()\n pack = load_pack(HERE, tools=desk.registry())\n model = resolve_model(None, pack)\n store = DyingStore(\":memory:\")\n\n try:\n run(pack, model, dict(MESSAGE), run_id=\"r\", store=store,\n tools=desk.registry())\n except Crash as exc:\n print(\"crashed:\", exc)\n\n checkpoint = store.latest(\"r\")\n print(\"ledger after the crash %r\" % (desk.ledger,))\n print(\"checkpoint next_node %s\" % checkpoint.next_node)\n print(\"checkpoint tool_calls %r\" % (checkpoint.tool_calls,))\n print()\n\n # The supervisor brings a live worker up against the same store.\n store.__class__ = Store\n result = resume(pack, model, \"r\", store, tools=desk.registry())\n\n print(\"resumed to %s\" % result.end_node)\n print(\"ledger after the resume %r\" % (desk.ledger,))\n print(\"refunds for %s %d\" % (ORDER, len(desk.refunds_for(ORDER))))\n print(\"output %r\" % (result.output,))\n store.close()\n\n\nif __name__ == \"__main__\":\n main()\n", "examples/refund_desk/prompts/approve.txt": "You are the approve step of a refund desk. This is the decision the money moves on.\n\nApprove the refund only when the assessment holds up. If the assessment found the\nclaim unjustified, do not approve it — a refund approved against the assessment is\nrefused before it is committed, and the case goes to a human.\n\nAnswer with the decision and one sentence of rationale.\n\nRefund justified: {justified}\nGrounds: {grounds}\nOrder total: {order_total}\nCustomer message: {message}\n\nRefund desk / approve / order {order_id}\n", "examples/refund_desk/prompts/assess.txt": "You are the assess step of a refund desk.\n\nThe order below came from the order store, not from the customer. Weigh the claim\nagainst it and say whether a refund is justified.\n\nA refund is justified when:\n - the order never arrived, or arrived damaged or wrong, or\n - the order was delivered within the last 30 days and the customer has a real\n fault to point at.\n\nA refund is not justified when:\n - the delivery was more than 30 days ago, or\n - nothing is wrong with the order and the customer has changed their mind, or\n - the order has not been delivered yet, so there is nothing to refund.\n\nGive one sentence of grounds, naming the fact you relied on.\n\nOrder total: {order_total}\nOrder status: {order_status}\nDays since delivery: {days_since_delivery}\nCustomer message: {message}\n\nRefund desk / assess / order {order_id}\n", "examples/refund_desk/prompts/classify.txt": "You are the classify step of a refund desk.\n\nDecide what the customer is actually asking for:\n refund - they want money back for an order\n question - they want information, not money\n complaint - they are unhappy and are not asking for a refund\n\nOnly a refund request goes on to the rest of the desk. Answer with the kind only.\n\nMessage: {message}\n\nRefund desk / classify / order {order_id}\n", "examples/refund_desk/tools.py": "\"\"\"The host half of the refund desk: an order store, and the two actions a pack may take.\n\nA pack is text and cannot contain code (`stepmold/tools.py`), so everything the desk can\nactually *do* lives here, in the host's own module, and is handed to the runtime per run:\n\n python3 -m stepmold eval examples/refund_desk --tools examples/refund_desk/tools.py\n\n`stepmold/cli.py:_load_registry` imports this file and looks for an attribute named `registry`\nor `REGISTRY`. Nothing in graph.yaml points here — the pack names `fetch_order` and\n`issue_refund` and the operator decides, on the command line, what those two names resolve\nto. That is the whole allowlist: a name this module never registered cannot be reached by\nany pack, and `stepmold.pack.check_tools` refuses the pack at load rather than at step four.\n\nThe two tools are deliberately not the same kind of thing, because that difference is what\nthe `idempotent=` flag is for:\n\n| tool | idempotent | recorded in the checkpoint | a resumed run |\n| --- | --- | --- | --- |\n| `fetch_order` | yes | no | reads again |\n| `issue_refund` | no | yes, before the commit | replays the recorded result |\n\n`issue_refund` mutates two things a reader (and a test) can watch: it appends to\n`RefundDesk.ledger`, one entry per *call*, and it flips the order's `refunded` flag. The\nledger counts calls rather than refunds on purpose — committed state records what a call\nreturned, never that it happened, so counting the entries is the only way to prove\nexactly-once from the outside.\n\"\"\"\n\nfrom stepmold.tools import ToolRegistry\n\n\nclass OrderNotFound(LookupError):\n \"\"\"No such order. Raised out of `fetch_order`, so the tool node's `on_fail` gets it.\n\n A plain exception, not a stepmold one: `Tool.invoke` wraps whatever the host's function\n raises in `ToolFailed`, and the walker routes that like any other node failure.\n \"\"\"\n\n\nclass AlreadyRefunded(RuntimeError):\n \"\"\"This order has been refunded once already.\n\n Here so that \"the refund went out twice\" is a loud failure rather than a quiet second\n row in the ledger. Nothing in the shipped evalset or in tests/test_example_refund.py\n ever triggers it — that is the point. If stepmold's exactly-once record ever stopped\n working, this is what a resumed run would hit.\n \"\"\"\n\n\n# The store. Eleven orders, one per evalset case; R-9999 is\n# deliberately absent, which is the case that exercises the `lookup` node's `on_fail`.\nSEED_ORDERS = {\n \"R-1001\": {\"total\": 49.99, \"status\": \"delivered\", \"days_since_delivery\": 3},\n \"R-1002\": {\"total\": 120.00, \"status\": \"delivered\", \"days_since_delivery\": 45},\n \"R-1004\": {\"total\": 32.00, \"status\": \"lost\", \"days_since_delivery\": 0},\n \"R-1005\": {\"total\": 18.50, \"status\": \"delivered\", \"days_since_delivery\": 1},\n \"R-1006\": {\"total\": 75.00, \"status\": \"delivered\", \"days_since_delivery\": 9},\n \"R-1007\": {\"total\": 210.00, \"status\": \"delivered\", \"days_since_delivery\": 60},\n \"R-1008\": {\"total\": 64.25, \"status\": \"delivered\", \"days_since_delivery\": 2},\n \"R-1009\": {\"total\": 15.00, \"status\": \"delivered\", \"days_since_delivery\": 6},\n \"R-1010\": {\"total\": 88.00, \"status\": \"delivered\", \"days_since_delivery\": 4},\n \"R-1011\": {\"total\": 42.00, \"status\": \"in_transit\", \"days_since_delivery\": 0},\n \"R-1012\": {\"total\": 149.99, \"status\": \"delivered\", \"days_since_delivery\": 2},\n}\n\n\nclass RefundDesk:\n \"\"\"The host's own state, and the registry that closes over it.\n\n A class rather than module-level dicts so a test can build a fresh desk per test and\n a reader can see where the state a tool touches actually lives. `registry()` returns a\n new `ToolRegistry` bound to *this* desk; two desks share nothing.\n \"\"\"\n\n def __init__(self, orders=None):\n self.orders = {\n order_id: dict(row)\n for order_id, row in (SEED_ORDERS if orders is None else orders).items()\n }\n # One entry per call to `issue_refund`, appended before anything else can fail.\n self.ledger = []\n\n # ------------------------------------------------------------------ the actions\n\n def fetch_order(self, order_id):\n \"\"\"Read one order out of the store. No side effect, so safe to repeat.\"\"\"\n order = self.orders.get(order_id)\n if order is None:\n raise OrderNotFound(\n \"no order %r in the store (%d known)\" % (order_id, len(self.orders))\n )\n return {\n \"order_total\": order[\"total\"],\n \"order_status\": order[\"status\"],\n \"days_since_delivery\": order[\"days_since_delivery\"],\n }\n\n def issue_refund(self, order_id, order_total):\n \"\"\"Move the money. The one thing in any example pack that is not reversible.\"\"\"\n order = self.orders.get(order_id)\n if order is None:\n raise OrderNotFound(\"no order %r in the store\" % order_id)\n if order.get(\"refunded\"):\n raise AlreadyRefunded(\n \"order %r was already refunded (%d call(s) in the ledger)\"\n % (order_id, len(self.refunds_for(order_id)))\n )\n refund_id = \"RF-%s\" % order_id\n self.ledger.append({\"order_id\": order_id, \"refund_id\": refund_id,\n \"amount\": order_total})\n order[\"refunded\"] = True\n return {\"refund_id\": refund_id, \"refund_amount\": order_total}\n\n # ------------------------------------------------------------------ observation\n\n def refunds_for(self, order_id):\n \"\"\"Every ledger entry for one order. Length is the exactly-once assertion.\"\"\"\n return [entry for entry in self.ledger if entry[\"order_id\"] == order_id]\n\n def is_refunded(self, order_id):\n return bool(self.orders.get(order_id, {}).get(\"refunded\"))\n\n # -------------------------------------------------------------------- the wiring\n\n def registry(self):\n \"\"\"Everything this host is willing to let a pack do, and nothing else.\n\n `reads` is the tool's whole argument list — a tool is called with exactly the\n state it declared and nothing else — and `writes` is the contract the graph is\n built around, checked on the way back out (`stepmold/tools.py:Tool._checked`). Both are\n declared rather than inferred here so `stepmold validate --tools ...` can catch a tool\n wired to a field this graph never produces, before a run has done half a job.\n \"\"\"\n registry = ToolRegistry()\n registry.add(\n \"fetch_order\", self.fetch_order,\n reads=[\"order_id\"],\n writes=[\"order_total\", \"order_status\", \"days_since_delivery\"],\n idempotent=True,\n description=\"Read one order from the order store.\",\n )\n registry.add(\n \"issue_refund\", self.issue_refund,\n reads=[\"order_id\", \"order_total\"],\n writes=[\"refund_id\", \"refund_amount\"],\n idempotent=False,\n description=\"Refund an order. Moves money; not repeatable.\",\n )\n return registry\n\n\n# What `--tools examples/refund_desk/tools.py` picks up. One desk per process, which is\n# what a CLI invocation wants; a test that needs isolation builds its own `RefundDesk`.\nDESK = RefundDesk()\nregistry = DESK.registry()\n", "examples/support_triage/evalset.jsonl": "{\"name\": \"I was charged twice for order A-1001, \", \"input\": {\"ticket\": \"I was charged twice for order A-1001, $49.99 both times.\"}, \"expect\": {\"category\": \"billing\", \"order_id\": \"A-1001\", \"amount_usd\": 49.99, \"sentiment\": \"frustrated\", \"priority\": \"p1\", \"queue\": \"billing-ops\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"The app crashes on launch every time s\", \"input\": {\"ticket\": \"The app crashes on launch every time since the update.\"}, \"expect\": {\"category\": \"technical\", \"order_id\": null, \"amount_usd\": null, \"sentiment\": \"frustrated\", \"priority\": \"p1\", \"queue\": \"eng-support\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"I can't log in to my account and the p\", \"input\": {\"ticket\": \"I can't log in to my account and the password reset email never arrives.\"}, \"expect\": {\"category\": \"account\", \"order_id\": null, \"amount_usd\": null, \"sentiment\": \"frustrated\", \"priority\": \"p1\", \"queue\": \"identity\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"Our entire production site is down and\", \"input\": {\"ticket\": \"Our entire production site is down and we are losing orders right now.\"}, \"expect\": {\"category\": \"technical\", \"order_id\": null, \"amount_usd\": null, \"sentiment\": \"angry\", \"priority\": \"p0\", \"queue\": \"eng-support\", \"escalate\": true}, \"end\": \"escalated\"}\n{\"name\": \"Please cancel order B-2002 and refund \", \"input\": {\"ticket\": \"Please cancel order B-2002 and refund the $120 when you get a chance.\"}, \"expect\": {\"category\": \"billing\", \"order_id\": \"B-2002\", \"amount_usd\": 120.0, \"sentiment\": \"calm\", \"priority\": \"p2\", \"queue\": \"billing-ops\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"How do I export my invoices for last y\", \"input\": {\"ticket\": \"How do I export my invoices for last year?\"}, \"expect\": {\"category\": \"other\", \"order_id\": null, \"amount_usd\": null, \"sentiment\": \"calm\", \"priority\": \"p3\", \"queue\": \"general\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"Payment failed three times for order C\", \"input\": {\"ticket\": \"Payment failed three times for order C-3003 ($15.00) and I don't know why.\"}, \"expect\": {\"category\": \"billing\", \"order_id\": \"C-3003\", \"amount_usd\": 15.0, \"sentiment\": \"frustrated\", \"priority\": \"p2\", \"queue\": \"billing-ops\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"Our whole team lost access after the S\", \"input\": {\"ticket\": \"Our whole team lost access after the SSO change this morning.\"}, \"expect\": {\"category\": \"account\", \"order_id\": null, \"amount_usd\": null, \"sentiment\": \"angry\", \"priority\": \"p0\", \"queue\": \"identity\", \"escalate\": true}, \"end\": \"escalated\"}\n{\"name\": \"The dashboard charts render blank in S\", \"input\": {\"ticket\": \"The dashboard charts render blank in Safari, they're fine in Chrome.\"}, \"expect\": {\"category\": \"technical\", \"order_id\": null, \"amount_usd\": null, \"sentiment\": \"calm\", \"priority\": \"p2\", \"queue\": \"eng-support\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"I was billed after cancelling. Order D\", \"input\": {\"ticket\": \"I was billed after cancelling. Order D-4004, $75.50. This is the second time.\"}, \"expect\": {\"category\": \"billing\", \"order_id\": \"D-4004\", \"amount_usd\": 75.5, \"sentiment\": \"angry\", \"priority\": \"p1\", \"queue\": \"billing-ops\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"Feature request: please add a dark mod\", \"input\": {\"ticket\": \"Feature request: please add a dark mode.\"}, \"expect\": {\"category\": \"other\", \"order_id\": null, \"amount_usd\": null, \"sentiment\": \"calm\", \"priority\": \"p3\", \"queue\": \"general\", \"escalate\": false}, \"end\": \"done\"}\n{\"name\": \"Our data export has been stuck for 6 h\", \"input\": {\"ticket\": \"Our data export has been stuck for 6 hours and it's blocking our audit.\"}, \"expect\": {\"category\": \"technical\", \"order_id\": null, \"amount_usd\": null, \"sentiment\": \"frustrated\", \"priority\": \"p1\", \"queue\": \"eng-support\", \"escalate\": false}, \"end\": \"done\"}\n", "examples/support_triage/fakes/script.json": "{\n \"classify step\": [\n \"{\\\"category\\\": \\\"billing\\\"}\",\n \"{\\\"category\\\": \\\"technical\\\"}\",\n \"{\\\"category\\\": \\\"account\\\"}\",\n \"{\\\"category\\\": \\\"technical\\\"}\",\n \"{\\\"category\\\": \\\"billing\\\"}\",\n \"{\\\"category\\\": \\\"other\\\"}\",\n \"{\\\"category\\\": \\\"billing\\\"}\",\n \"{\\\"category\\\": \\\"account\\\"}\",\n \"{\\\"category\\\": \\\"technical\\\"}\",\n \"{\\\"category\\\": \\\"billing\\\"}\",\n \"{\\\"category\\\": \\\"other\\\"}\",\n \"{\\\"category\\\": \\\"technical\\\"}\"\n ],\n \"extract step\": [\n \"{\\\"order_id\\\": \\\"A-1001\\\", \\\"amount_usd\\\": 49.99, \\\"sentiment\\\": \\\"frustrated\\\"}\",\n \"{\\\"order_id\\\": null, \\\"amount_usd\\\": null, \\\"sentiment\\\": \\\"frustrated\\\"}\",\n \"{\\\"order_id\\\": null, \\\"amount_usd\\\": null, \\\"sentiment\\\": \\\"frustrated\\\"}\",\n \"{\\\"order_id\\\": null, \\\"amount_usd\\\": null, \\\"sentiment\\\": \\\"angry\\\"}\",\n \"{\\\"order_id\\\": \\\"B-2002\\\", \\\"amount_usd\\\": 120.0, \\\"sentiment\\\": \\\"calm\\\"}\",\n \"{\\\"order_id\\\": null, \\\"amount_usd\\\": null, \\\"sentiment\\\": \\\"calm\\\"}\",\n \"{\\\"order_id\\\": \\\"C-3003\\\", \\\"amount_usd\\\": 15.0, \\\"sentiment\\\": \\\"frustrated\\\"}\",\n \"{\\\"order_id\\\": null, \\\"amount_usd\\\": null, \\\"sentiment\\\": \\\"angry\\\"}\",\n \"{\\\"order_id\\\": null, \\\"amount_usd\\\": null, \\\"sentiment\\\": \\\"calm\\\"}\",\n \"{\\\"order_id\\\": \\\"D-4004\\\", \\\"amount_usd\\\": 75.5, \\\"sentiment\\\": \\\"angry\\\"}\",\n \"{\\\"order_id\\\": null, \\\"amount_usd\\\": null, \\\"sentiment\\\": \\\"calm\\\"}\",\n \"{\\\"order_id\\\": null, \\\"amount_usd\\\": null, \\\"sentiment\\\": \\\"frustrated\\\"}\"\n ],\n \"priority reasoning step\": [\n \"One customer, money moved twice. Nothing is down, but a duplicate charge is real money and they noticed.\",\n \"The product does not start at all for this customer. One person blocked, no revenue at risk.\",\n \"They cannot get in and the recovery path is broken too, so they cannot fix it themselves.\",\n \"Their whole site is down and orders are failing. This is as urgent as tickets get.\",\n \"A refund is owed but they said 'when you get a chance'. Nobody is blocked.\",\n \"A question about a feature that already exists. No deadline, no impact.\",\n \"Repeated payment failures are annoying but the amount is small and nothing is down.\",\n \"Every person at the customer is locked out after a change we made. Whole team blocked.\",\n \"A genuine rendering bug, but only in one browser and they have another that works.\",\n \"Billed after cancelling, twice now. Money moved wrongly and trust is going.\",\n \"A request for something that does not exist yet. No impact on anything today.\",\n \"The export is stuck and it is blocking an audit, which is a deadline they cannot move.\"\n ],\n \"priority step\": [\n \"{\\\"priority\\\": \\\"p1\\\", \\\"reason\\\": \\\"The customer has been double-charged, so money has moved incorrectly.\\\"}\",\n \"{\\\"priority\\\": \\\"p1\\\", \\\"reason\\\": \\\"The customer cannot use the product at all after the update.\\\"}\",\n \"{\\\"priority\\\": \\\"p1\\\", \\\"reason\\\": \\\"The customer is locked out and the self-serve recovery path is broken.\\\"}\",\n \"{\\\"priority\\\": \\\"p0\\\", \\\"reason\\\": \\\"Production is down for the whole customer and revenue is being lost every minute.\\\"}\",\n \"{\\\"priority\\\": \\\"p2\\\", \\\"reason\\\": \\\"A refund is owed but the customer is calm and nothing is blocked.\\\"}\",\n \"{\\\"priority\\\": \\\"p3\\\", \\\"reason\\\": \\\"This is a how-to question with no deadline attached.\\\"}\",\n \"{\\\"priority\\\": \\\"p2\\\", \\\"reason\\\": \\\"Payment is failing repeatedly but the order is small and nothing is down.\\\"}\",\n \"{\\\"priority\\\": \\\"p0\\\", \\\"reason\\\": \\\"An entire team is locked out, so everyone at the customer is blocked.\\\"}\",\n \"{\\\"priority\\\": \\\"p2\\\", \\\"reason\\\": \\\"A real bug, but it is browser-specific and the customer has a workaround.\\\"}\",\n \"{\\\"priority\\\": \\\"p1\\\", \\\"reason\\\": \\\"The customer was charged after cancelling, and it has now happened twice.\\\"}\",\n \"{\\\"priority\\\": \\\"p3\\\", \\\"reason\\\": \\\"A feature request with no urgency and no one blocked.\\\"}\",\n \"{\\\"priority\\\": \\\"p1\\\", \\\"reason\\\": \\\"A stuck export is blocking a deadline the customer cannot move.\\\"}\"\n ],\n \"emit step\": [\n \"{\\\"queue\\\": \\\"billing-ops\\\", \\\"summary\\\": \\\"Customer double-charged $49.99 on order A-1001.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"eng-support\\\", \\\"summary\\\": \\\"App crashes on launch for this customer since the last update.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"identity\\\", \\\"summary\\\": \\\"Customer locked out; password reset email is not arriving.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"eng-support\\\", \\\"summary\\\": \\\"Customer production site is fully down and losing orders.\\\", \\\"escalate\\\": true}\",\n \"{\\\"queue\\\": \\\"billing-ops\\\", \\\"summary\\\": \\\"Cancel order B-2002 and refund $120.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"general\\\", \\\"summary\\\": \\\"Customer asks how to export last year's invoices.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"billing-ops\\\", \\\"summary\\\": \\\"Payment failing repeatedly on order C-3003 for $15.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"identity\\\", \\\"summary\\\": \\\"Whole team locked out following this morning's SSO change.\\\", \\\"escalate\\\": true}\",\n \"{\\\"queue\\\": \\\"eng-support\\\", \\\"summary\\\": \\\"Dashboard charts render blank in Safari but work in Chrome.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"billing-ops\\\", \\\"summary\\\": \\\"Customer billed $75.50 on order D-4004 after cancelling.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"general\\\", \\\"summary\\\": \\\"Feature request for a dark mode.\\\", \\\"escalate\\\": false}\",\n \"{\\\"queue\\\": \\\"eng-support\\\", \\\"summary\\\": \\\"Data export stuck for six hours, blocking the customer's audit.\\\", \\\"escalate\\\": false}\"\n ]\n}\n", "examples/support_triage/grammars/classify.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"category\": {\n \"type\": \"string\",\n \"enum\": [\"billing\", \"technical\", \"account\", \"other\"]\n }\n },\n \"required\": [\"category\"],\n \"additionalProperties\": false\n}\n", "examples/support_triage/grammars/emit.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"queue\": {\n \"type\": \"string\",\n \"enum\": [\"billing-ops\", \"eng-support\", \"identity\", \"general\"]\n },\n \"summary\": {\"type\": \"string\"},\n \"escalate\": {\"type\": \"boolean\"}\n },\n \"required\": [\"queue\", \"summary\", \"escalate\"],\n \"additionalProperties\": false\n}\n", "examples/support_triage/grammars/extract.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"order_id\": {\"type\": [\"string\", \"null\"]},\n \"amount_usd\": {\"type\": [\"number\", \"null\"]},\n \"sentiment\": {\"type\": \"string\", \"enum\": [\"calm\", \"frustrated\", \"angry\"]}\n },\n \"required\": [\"order_id\", \"amount_usd\", \"sentiment\"],\n \"additionalProperties\": false\n}\n", "examples/support_triage/grammars/priority.json": "{\n \"type\": \"object\",\n \"properties\": {\n \"priority\": {\"type\": \"string\", \"enum\": [\"p0\", \"p1\", \"p2\", \"p3\"]},\n \"reason\": {\"type\": \"string\"}\n },\n \"required\": [\"priority\", \"reason\"],\n \"additionalProperties\": false\n}\n", "examples/support_triage/graph.yaml": "# classify -> extract -> priority -> emit -> (escalated | done)\n#\n# Each node has one narrow job and one grammar. That is the whole trick: no node\n# ever has to plan, so no node needs a large model to be reliable.\n\nmax_steps: 12\n\nnodes:\n classify:\n type: generate\n max_tokens: 32\n\n extract:\n type: generate\n max_tokens: 96\n\n priority:\n type: generate\n # The one node with a judgement call in it, so it gets an unconstrained\n # think pass before the constrained emit (docs/ARCHITECTURE.md, Bug 2).\n two_stage: true\n think_max_tokens: 128\n max_tokens: 96\n\n emit:\n type: generate\n max_tokens: 128\n # Deterministic invariant, checked before anything is committed: the ticket\n # may only be flagged for escalation when the priority actually says p0.\n assert: escalate == (priority == \"p0\")\n on_fail: needs_human\n\n escalated:\n type: end\n output: [category, order_id, amount_usd, sentiment, priority, queue, escalate]\n\n done:\n type: end\n output: [category, order_id, amount_usd, sentiment, priority, queue, escalate]\n\n needs_human:\n type: end\n output: [category, priority]\n\nedges:\n - from: classify\n to: extract\n\n - from: extract\n to: priority\n\n - from: priority\n to: emit\n\n - from: emit\n to: escalated\n when: {priority: p0}\n\n - from: emit\n to: done\n", "examples/support_triage/manifest.yaml": "name: support_triage\nversion: 1\nentry: classify\nmodel: fake:fakes/script.json\ndescription: >-\n Four-node support-ticket triage: classify, extract fields, decide priority,\n emit the routed ticket.\n\n The model below is a scripted stand-in, so the evalset scores offline with no\n GPU and no network. It replays the twelve evalset cases in order and does not\n read the ticket, so a `stepmold run` of anything other than the first case will\n answer the first case. Point --model at a real backend to run real tickets.\n", "examples/support_triage/prompts/classify.txt": "You are the classify step of a support-ticket triage workflow.\n\nChoose exactly one category for the ticket:\n billing - charges, refunds, invoices, payment failures\n technical - crashes, bugs, outages, things not working\n account - login, passwords, access, permissions, SSO\n other - anything else, including questions and requests\n\nAnswer with the category only.\n\nTicket: {ticket}\n", "examples/support_triage/prompts/emit.txt": "You are the emit step of a support-ticket triage workflow.\n\nProduce the routed ticket:\n queue - billing-ops, eng-support, identity, or general\n summary - one sentence, plain, no more than 20 words\n escalate - true only when the priority is p0\n\nCategory: {category}\nPriority: {priority}\nReason: {reason}\nTicket: {ticket}\n", "examples/support_triage/prompts/extract.txt": "You are the extract step of a support-ticket triage workflow.\n\nPull these fields out of the ticket. Do not guess: if the ticket does not state\na value, use null.\n order_id - the order reference exactly as written, or null\n amount_usd - the dollar amount as a number, or null\n sentiment - calm, frustrated, or angry\n\nThe ticket has already been classified as: {category}\n\nTicket: {ticket}\n", "examples/support_triage/prompts/priority.think.txt": "You are the priority reasoning step of a support-ticket triage workflow.\n\nIn two or three sentences, weigh how urgent this ticket is. Consider how many\npeople are blocked, whether money is at stake, and whether the customer is\nalready angry. Do not decide the priority yet and do not answer in JSON.\n\nCategory: {category}\nSentiment: {sentiment}\nTicket: {ticket}\n", "examples/support_triage/prompts/priority.txt": "You are the priority step of a support-ticket triage workflow.\n\nAssign a priority:\n p0 - production is down or an entire team is blocked\n p1 - one customer is blocked or money moved incorrectly\n p2 - broken but survivable, or a refund the customer is calm about\n p3 - questions, requests, and anything with no deadline\n\nGive a one-sentence reason.\n\nCategory: {category}\nSentiment: {sentiment}\nTicket: {ticket}\n", "stepmold/__init__.py": "\"\"\"stepmold — compile an agent once with a frontier model, run it forever on a small one.\n\nStandard library only, by design: the runtime is meant to be droppable onto a client\nbox with nothing installed. See docs/ARCHITECTURE.md.\n\"\"\"\n\n__version__ = \"0.0.1\"\n", "stepmold/__main__.py": "import sys\n\nfrom .cli import main\n\nsys.exit(main())\n", "stepmold/backends/__init__.py": "\"\"\"Adapters from stepmold's `Model` protocol to a real inference server.\n\nNothing in here is exercised by the test suite against a live server — the whole suite\nruns offline against `FakeModel`, and these modules are tested with the HTTP layer\nmocked. See NIGHT-LOG.md, T11.\n\"\"\"\n", "stepmold/backends/openai_compat.py": "\"\"\"An OpenAI-compatible `/v1/chat/completions` client, in `urllib`.\n\nThis is the adapter that points stepmold at a real small model. The same wire format is\nspoken by llama.cpp-server, vLLM and SGLang, which is exactly the point: ARCHITECTURE.md §2's\n\"one base model, many packs\" only works if swapping the server is a URL change.\n\nWritten but **never executed against a live server in this repo** — the test suite mocks\nthe HTTP layer and makes no network call, per TASKS.md T11. Treat it as unverified\nagainst real servers until someone runs it against one.\n\nGrammar handling differs per backend, so it is a flag rather than a guess:\n\n response_format vLLM, SGLang, OpenAI -> response_format.json_schema.schema\n json_schema llama.cpp-server -> a top-level \"json_schema\" field\n json_object any server with only -> response_format {\"type\": \"json_object\"},\n loose JSON mode schema appended to the prompt as text\n none no server-side constraint at all\n\nEven with `none`, stepmold still validates every output before committing it (see\n`stepmold.verify`) — constrained decoding is an optimisation here, not the safety net.\n\"\"\"\n\nimport datetime\nimport email.utils\nimport http.client\nimport json\nimport socket\nimport os\nimport time\nimport urllib.error\nimport urllib.parse\nimport urllib.request\nfrom dataclasses import dataclass, field\nfrom typing import Any, Callable, Dict, Optional\n\nfrom ..errors import BackendError\nfrom ..log import (BEARER, DEBUG, ERROR, INFO, KEY_SHAPED, WARNING, event,\n get_logger, redact)\n\n__all__ = [\n \"DEFAULT_OPENER\",\n \"GRAMMAR_MODES\",\n \"NoCrossOriginRedirect\",\n \"OpenAICompatModel\",\n]\n\n_log = get_logger(\"backend\")\n\nGRAMMAR_MODES = (\"response_format\", \"json_schema\", \"json_object\", \"none\")\nAPI_KEY_VARIABLES = (\"STEPMOLD_API_KEY\", \"OPENAI_API_KEY\")\nRETRY_STATUSES = (408, 429, 500, 502, 503, 504)\nDEFAULT_PORTS = {\"http\": 80, \"https\": 443}\n\n# The payload fields each grammar mode writes itself. `extra_body` is merged last, so a\n# key in here coming from a caller would delete the constraint the mode just applied and\n# say nothing about it — \"a constraint you think you have and don't\", which is the exact\n# failure stepmold/grammar.py exists to prevent. Refused at construction instead.\nGRAMMAR_FIELDS = {\n \"response_format\": (\"messages\", \"response_format\"),\n \"json_schema\": (\"messages\", \"json_schema\"),\n \"json_object\": (\"messages\", \"response_format\"),\n \"none\": (\"messages\",),\n}\n\n# A provider that answers `Retry-After: 3600` is telling the truth, but a run must not\n# disappear into an hour-long sleep inside one node. Honour the instruction up to here.\nRETRY_AFTER_CEILING = 60.0\n\n# Credentials, as they appear in text somebody else wrote: a header a gateway echoed back\n# at us, or a key pasted into an upstream error message. The patterns and the filter moved\n# to `stepmold.log` when logging arrived — the same text now goes to two places, and one filter\n# in front of both is the only version of this that stays true. Re-exported here because\n# this module is where the redaction rule was written and where readers look for it.\n_redact = redact\n\n\nclass NoCrossOriginRedirect(urllib.request.HTTPRedirectHandler):\n \"\"\"Follow a redirect only while it stays on the origin the operator chose.\n\n urllib's stock handler copies the request headers onto the next hop, so the\n `Authorization: Bearer ...` this client attaches is delivered to whatever host the\n endpoint names in a `Location` — verified here for a 302, which urllib follows as a\n GET carrying the header. The endpoint is not necessarily trusted with the operator's\n key: `base_url` can come from a shared config or a proxy someone stood up. Chat\n completions needs no cross-origin hop, so refuse it by name rather than follow it\n silently and return the other host's reply as if it were the model's.\n \"\"\"\n\n def redirect_request(self, req, fp, code, msg, headers, newurl):\n here, there = _origin(req.full_url), _origin(newurl)\n if here != there:\n # Raised, not returned as None: returning None makes urllib hand the caller\n # the redirect response as if it were an answer, which reads like a\n # malformed reply instead of a refusal.\n raise BackendError(\n \"refusing to follow an HTTP %s redirect from %s to %s: the request \"\n \"carries your API key, and a redirect must not move it to another \"\n \"origin\" % (code, _text(here), _text(there))\n )\n return urllib.request.HTTPRedirectHandler.redirect_request(\n self, req, fp, code, msg, headers, newurl\n )\n\n\ndef _origin(url):\n \"\"\"(scheme, host, port) — what a redirect must keep identical.\"\"\"\n parts = urllib.parse.urlsplit(url)\n scheme = parts.scheme.lower()\n try:\n port = parts.port\n except ValueError: # a Location with a nonsense port is not an origin we can match\n port = None\n return scheme, (parts.hostname or \"\").lower(), port or DEFAULT_PORTS.get(scheme)\n\n\ndef _text(origin):\n scheme, host, port = origin\n return \"%s://%s:%s\" % (scheme, host, port)\n\n\n# Built once at import; constructing an opener performs no IO.\nDEFAULT_OPENER = urllib.request.build_opener(NoCrossOriginRedirect)\n\n\n@dataclass\nclass OpenAICompatModel:\n \"\"\"A `Model` backed by an OpenAI-compatible chat completions endpoint.\n\n `opener` and `sleeper` exist so the HTTP layer can be replaced in a test. Nothing\n else in stepmold should ever need them. The default opener is not bare `urlopen`: it\n refuses cross-origin redirects so the API key cannot be walked off the chosen host\n (see `NoCrossOriginRedirect`).\n \"\"\"\n\n base_url: str\n model: str\n # repr=False so the generated __repr__ cannot print it. The explicit __repr__ below\n # takes over anyway, but a model is exactly the object that lands in\n # logging.debug(\"%r\", model), in a failed assertion's diff and in a crash reporter\n # walking locals, so the credential is hidden at the field as well as at the method.\n api_key: Optional[str] = field(default=None, repr=False)\n grammar_mode: str = \"response_format\"\n user_agent: str = \"stepmold/%s\" % __import__(\"stepmold\").__version__\n reasoning_reserve: int = 0\n temperature: float = 0.0\n timeout: float = 60.0\n max_retries: int = 2\n schema_name: str = \"stepmold_node\"\n extra_body: Dict[str, Any] = field(default_factory=dict)\n opener: Callable = DEFAULT_OPENER.open\n sleeper: Callable = time.sleep\n\n def __post_init__(self):\n if self.grammar_mode not in GRAMMAR_MODES:\n raise ValueError(\n \"unknown grammar_mode %r (known: %s)\"\n % (self.grammar_mode, \", \".join(GRAMMAR_MODES))\n )\n _refuse_grammar_collisions(self.grammar_mode, self.extra_body)\n self.url = _completions_url(self.base_url)\n if self.api_key is None:\n self.api_key = _api_key_from_environment()\n\n def __repr__(self):\n \"\"\"Identify the model without printing the credential it carries.\n\n A dataclass repr prints every field, and a model is an ordinary object: it ends\n up in logs, tracebacks and pdb frames. The fingerprint is enough to tell \"the\n wrong key is loaded\" from \"no key is loaded\" and far too little to authenticate\n with. `opener` and `sleeper` are left out for the same reason a repr exists at\n all — they are noise at the point where somebody is reading one.\n \"\"\"\n return \"OpenAICompatModel(base_url=%r, model=%r, grammar_mode=%r, api_key=%s)\" % (\n self.base_url, self.model, self.grammar_mode, _fingerprint(self.api_key)\n )\n\n # ------------------------------------------------------------------ Model protocol\n\n def generate(self, prompt, grammar=None, max_tokens=512, sampling=None):\n \"\"\"Complete `prompt`, constrained by `grammar` in whichever way this server wants.\"\"\"\n payload = self.build_payload(prompt, grammar, max_tokens, sampling=sampling)\n return _content(self._post(payload))\n\n # ------------------------------------------------------------------------ internals\n\n def build_payload(self, prompt, grammar, max_tokens, sampling=None):\n schema = _schema_of(grammar)\n payload = {\n \"model\": self.model,\n \"messages\": [{\"role\": \"user\", \"content\": prompt}],\n # A pack's max_tokens budgets the ANSWER, because a pack is portable and\n # cannot know which model will run it. A reasoning model bills its private\n # chain of thought against the same ceiling, so the model-specific headroom\n # is added here, in the backend that knows what it is talking to. Without\n # it, a node with a tight budget spends the whole allowance thinking and\n # returns finish_reason=length with content=None.\n \"max_tokens\": max_tokens + self.reasoning_reserve,\n \"temperature\": self.temperature,\n }\n # An independent draw is the whole point of a re-sample and of the agreement gate.\n # Without honouring this hint every extra draw is a byte-identical request, the\n # draws agree by construction, and the gate reports full confidence on a single\n # sample — which is worse than no gate, because it is confidence that was never\n # earned. `seed` matters as much as temperature: a server pinned to greedy\n # decoding is deterministic in its stream but still varies on seed.\n if sampling is not None:\n payload[\"temperature\"] = sampling.temperature\n if sampling.seed is not None:\n payload[\"seed\"] = sampling.seed\n if schema is not None:\n if self.grammar_mode == \"response_format\":\n payload[\"response_format\"] = {\n \"type\": \"json_schema\",\n \"json_schema\": {\n \"name\": self.schema_name,\n \"schema\": schema,\n # Claimed only when it is true of this schema — see\n # `_strict_ready`. Claiming it unconditionally gets the whole\n # request refused with a 400 that no ladder can absorb.\n \"strict\": _strict_ready(schema),\n },\n }\n elif self.grammar_mode == \"json_schema\":\n payload[\"json_schema\"] = schema\n elif self.grammar_mode == \"json_object\":\n payload[\"response_format\"] = {\"type\": \"json_object\"}\n payload[\"messages\"][0][\"content\"] = (\n prompt\n + \"\\n\\nReply with JSON matching this schema:\\n\"\n + json.dumps(schema, sort_keys=True)\n )\n payload.update(self.extra_body)\n return payload\n\n def _post(self, payload):\n body = json.dumps(payload).encode(\"utf-8\")\n # An explicit User-Agent is not cosmetic. urllib defaults to \"Python-urllib/X.Y\",\n # which Cloudflare-fronted inference providers (Cerebras among them) reject with\n # HTTP 403 error 1010 — a browser-signature ban, before the request ever reaches\n # the model. Found by running this adapter against a real endpoint for the first\n # time; no mocked test could have caught it.\n headers = {\"Content-Type\": \"application/json\", \"User-Agent\": self.user_agent}\n if self.api_key:\n headers[\"Authorization\"] = \"Bearer %s\" % self.api_key\n\n last = None\n for attempt in range(self.max_retries + 1):\n request = urllib.request.Request(\n self.url, data=body, headers=headers, method=\"POST\"\n )\n asked_for = 0.0\n # One clock read per HTTP attempt, next to a call that is about to block on a\n # GPU for a fifth of a second. The cost of always taking it is not worth the\n # branch it would take to avoid it.\n started = time.monotonic()\n event(_log, DEBUG, \"backend.request\", model=self.model, endpoint=self.url,\n attempt=attempt + 1, of=self.max_retries + 1,\n grammar_mode=self.grammar_mode,\n max_tokens=payload.get(\"max_tokens\"), body_bytes=len(body))\n try:\n with self.opener(request, timeout=self.timeout) as response:\n # The read stays inside the try: a body shorter than its\n # Content-Length fails here, not at the opener.\n decoded = _decode(response.read(), self.url, _content_type(response))\n status = getattr(response, \"status\", None) or 200\n except urllib.error.HTTPError as exc:\n detail = _read_error(exc, self.api_key)\n last = BackendError(\n \"%s returned HTTP %s: %s\" % (self.url, exc.code, detail)\n )\n retryable = exc.code in RETRY_STATUSES\n # `detail` has already been through `_read_error`, which strips the key\n # we sent and anything else key-shaped out of somebody else's error body.\n event(_log, WARNING, \"backend.http_error\", model=self.model,\n endpoint=self.url, status=exc.code, attempt=attempt + 1,\n retryable=retryable, duration_ms=_ms(started), detail=detail)\n if not retryable:\n raise last\n asked_for = _retry_after(exc)\n except urllib.error.URLError as exc:\n last = BackendError(\n \"could not reach %s: %s\" % (self.url, _redact(str(exc.reason)))\n )\n event(_log, WARNING, \"backend.transport_error\", model=self.model,\n endpoint=self.url, attempt=attempt + 1, error=\"URLError\",\n duration_ms=_ms(started), detail=_redact(str(exc.reason)))\n except (OSError, http.client.HTTPException) as exc:\n # urllib wraps only what HTTPConnection.request() raises. Everything from\n # getresponse() and response.read() — a peer that hangs up, a truncated\n # body, a read that outlives the timeout — used to escape stepmold raw: not a\n # StepmoldError, never retried, and a bare traceback out of `stepmold run`. These\n # are the most transient failures stepmold can meet, so they ride the same\n # ladder as a 503.\n last = _transport_error(self.url, self.timeout, exc)\n event(_log, WARNING, \"backend.transport_error\", model=self.model,\n endpoint=self.url, attempt=attempt + 1,\n error=type(exc).__name__, duration_ms=_ms(started),\n detail=_redact(str(exc)))\n else:\n # An `else` rather than a `return` inside the `try`, so the accounting\n # below runs on a request that actually completed without widening what\n # the except clauses above are watching.\n if _log.isEnabledFor(INFO):\n # `_usage` walks the response, so it is built only when something is\n # listening. This is the line that answers \"what did that cost\".\n event(_log, INFO, \"backend.response\", model=self.model,\n endpoint=self.url, status=status, attempt=attempt + 1,\n retries=attempt, duration_ms=_ms(started), **_usage(decoded))\n return decoded\n if attempt < self.max_retries:\n # The provider's instruction wins when it is longer than our own backoff;\n # our backoff wins when the provider said nothing.\n delay = max(0.5 * (2 ** attempt), asked_for)\n # The slept seconds, not the schedule: a run that spent nine seconds\n # inside one node spent them here, and only the actual number says so.\n event(_log, INFO, \"backend.backoff\", endpoint=self.url,\n attempt=attempt + 1, retry_after=asked_for, slept_s=round(delay, 3))\n self.sleeper(delay)\n event(_log, ERROR, \"backend.failed\", model=self.model, endpoint=self.url,\n attempts=self.max_retries + 1, detail=str(last))\n raise last\n\n\ndef _completions_url(base_url):\n \"\"\"Accept a host, a `/v1`, or the full endpoint — all three are what people paste.\"\"\"\n trimmed = (base_url or \"\").rstrip(\"/\")\n if not trimmed:\n raise ValueError(\"base_url is required, e.g. http://localhost:8000\")\n if trimmed.endswith(\"/chat/completions\"):\n return trimmed\n if trimmed.endswith(\"/v1\"):\n return trimmed + \"/chat/completions\"\n return trimmed + \"/v1/chat/completions\"\n\n\ndef _api_key_from_environment():\n for name in API_KEY_VARIABLES:\n value = os.environ.get(name)\n if value:\n return value\n return None\n\n\ndef _fingerprint(key):\n \"\"\"A key you can recognise but not use.\"\"\"\n if not key:\n return \"None\"\n if len(key) < 12:\n # Too short for a prefix and a suffix to leave anything unguessable behind.\n return \"''\"\n return \"'%s...%s'\" % (key[:3], key[-3:])\n\n\ndef _refuse_grammar_collisions(grammar_mode, extra_body):\n \"\"\"Refuse an `extra_body` key that the chosen grammar mode owns.\n\n `extra_body` is merged last so an operator can reach a server knob stepmold has no field\n for. Merged last also means it wins, and the fields the grammar mode writes are\n exactly the ones that must not be quietly lost: the request still succeeds, the model\n answers unconstrained, and nothing anywhere says the node lost its grammar. Refusing\n at construction is the same bargain `grammar_mode` itself already makes — say no\n before the first request rather than send a wrong one forever.\n \"\"\"\n owned = GRAMMAR_FIELDS[grammar_mode]\n clashing = sorted(key for key in (extra_body or {}) if key in owned)\n if clashing:\n raise ValueError(\n \"extra_body may not set %s: grammar_mode %r builds those fields itself, and \"\n \"extra_body is merged last, so the constraint would be overwritten with no \"\n \"error at all. Drop the key, or choose the grammar_mode that sends what you \"\n \"want (known: %s).\"\n % (\", \".join(repr(key) for key in clashing), grammar_mode,\n \", \".join(GRAMMAR_MODES))\n )\n\n\ndef _strict_ready(schema):\n \"\"\"True when `schema` satisfies OpenAI-family strict structured output.\n\n Strict mode is not a superset of JSON Schema: every object must set\n `additionalProperties: false` and name every declared property in `required`.\n `stepmold.grammar.check_schema` requires neither — optional properties are a deliberate\n part of stepmold's subset — so a pack that validates, evals green against a FakeModel and\n ships could still be refused with an HTTP 400 that no ladder absorbs (400 is not\n retryable, and `BackendError` is not `NodeFailed`, so `on_fail` never fires either).\n\n Claiming strictness only when it holds, rather than normalising the schema into it,\n is the choice made here for two reasons: closing an object and marking every property\n required changes the contract the pack declared (an optional field becomes one the\n model must emit), and doing it safely would mean copying the pack's grammar dict on\n every call to avoid editing it in place. Nothing is lost by not claiming it — the\n schema still goes on the wire, servers that constrain decoding still use it, and\n `stepmold.verify` checks the output against the pack's schema either way.\n \"\"\"\n if not isinstance(schema, dict):\n return True\n declared = schema.get(\"type\")\n types = [declared] if isinstance(declared, str) else list(declared or [])\n if \"object\" in types:\n if schema.get(\"additionalProperties\") is not False:\n return False\n properties = schema.get(\"properties\") or {}\n if set(properties) - set(schema.get(\"required\") or []):\n return False\n if not all(_strict_ready(sub) for sub in properties.values()):\n return False\n if \"array\" in types and isinstance(schema.get(\"items\"), dict):\n return _strict_ready(schema[\"items\"])\n return True\n\n\ndef _retry_after(exc):\n \"\"\"How long the provider asked us to wait, in seconds, or 0.0 if it did not.\n\n A 429 backing off on stepmold's own schedule is a provider instruction being ignored: the\n first retry goes out at 0.5s when the header said 1s, and a `Retry-After: 60` still\n gets three requests inside 1.5 seconds — which is how an account gets banned rather\n than rate limited.\n \"\"\"\n headers = getattr(exc, \"headers\", None)\n value = headers.get(\"Retry-After\") if headers is not None else None\n seconds = _delta_seconds(value.strip()) if value else None\n if seconds is None:\n return 0.0\n return max(0.0, min(seconds, RETRY_AFTER_CEILING))\n\n\ndef _delta_seconds(value):\n \"\"\"Both spellings RFC 7231 allows: `120`, and `Wed, 21 Oct 2015 07:28:00 GMT`.\"\"\"\n try:\n return float(int(value))\n except ValueError:\n pass\n try:\n when = email.utils.parsedate_to_datetime(value)\n except (TypeError, ValueError):\n return None\n if when is None:\n return None\n if when.tzinfo is None: # a date with no zone is UTC, per the spec\n when = when.replace(tzinfo=datetime.timezone.utc)\n return (when - datetime.datetime.now(datetime.timezone.utc)).total_seconds()\n\n\ndef _transport_error(url, timeout, exc):\n \"\"\"Name a socket-level failure the way an HTTP status is named.\n\n \"RemoteDisconnected\" on its own tells an operator nothing about which endpoint died\n or what to change; `_no_content_reason` sets the standard for the rest of this file.\n \"\"\"\n # socket.timeout only became an alias of TimeoutError in Python 3.10; on 3.9 it is a\n # plain OSError, so checking TimeoutError alone let a read timeout fall through to the\n # generic message and lose the one number the operator needs — the timeout itself.\n if isinstance(exc, (TimeoutError, socket.timeout)):\n return BackendError(\n \"%s did not answer within the %ss timeout. Raise the backend's `timeout` if \"\n \"the model is simply slow to start emitting tokens.\" % (url, timeout)\n )\n if isinstance(exc, http.client.IncompleteRead):\n # `expected` counts the bytes still OUTSTANDING, not the whole body, so the\n # Content-Length the server promised is the sum of the two.\n arrived = len(exc.partial)\n promised = \"%d\" % (arrived + exc.expected) if exc.expected is not None else \"more\"\n return BackendError(\n \"%s sent a truncated response body: %d bytes arrived of the %s it promised \"\n \"in Content-Length, then the connection closed.\"\n % (url, arrived, promised)\n )\n return BackendError(\n \"the connection to %s failed before a complete response arrived (%s: %s)\"\n % (url, type(exc).__name__, _redact(str(exc)) or \"no detail\")\n )\n\n\ndef _content_type(response):\n \"\"\"The response's Content-Type, if this response object has headers at all.\"\"\"\n headers = getattr(response, \"headers\", None)\n return headers.get(\"Content-Type\") if headers is not None else None\n\n\ndef _schema_of(grammar):\n \"\"\"Unwrap `stepmold.grammar.schema_to_grammar`'s struct, or take a bare schema.\"\"\"\n if grammar is None:\n return None\n if isinstance(grammar, dict) and \"schema\" in grammar:\n return grammar[\"schema\"]\n return grammar\n\n\ndef _decode(raw, url=None, content_type=None):\n \"\"\"Parse a completion body, and say enough about a body that is not one.\n\n The old message was `\"not JSON (Expecting value: line 1 column 1 (char 0))\"`, which\n names neither the endpoint nor a byte of what arrived — an operator cannot tell a\n proxy's HTML 502 page from a model that returned an empty string. Both are HTTP 200\n here, and only the body says which.\n \"\"\"\n text = raw.decode(\"utf-8\", \"replace\") if isinstance(raw, bytes) else raw\n try:\n return json.loads(text)\n except ValueError as exc:\n raise BackendError(\n \"%s returned a body that is not JSON (%s). Content-Type was %s; the body \"\n \"began: %s\"\n % (url or \"the backend\", exc, content_type or \"not stated\",\n _clip(_redact(text)))\n )\n\n\ndef _clip(text, limit=200):\n stripped = (text or \"\").strip()\n if not stripped:\n return \"\"\n return repr(stripped[:limit] + (\"...\" if len(stripped) > limit else \"\"))\n\n\ndef _content(response):\n choices = response.get(\"choices\") if isinstance(response, dict) else None\n if not choices:\n raise _empty(\n \"backend returned no choices: %s\" % _clip(_redact(json.dumps(response)))\n )\n choice = choices[0]\n message = choice.get(\"message\") or {}\n content = message.get(\"content\")\n if content is None:\n content = choice.get(\"text\")\n if not isinstance(content, str):\n raise _empty(_no_content_reason(response, choice, message))\n return content\n\n\ndef _empty(detail):\n \"\"\"A 200 that carried no text: a bad draw, not an endpoint that is down.\n\n `verify.run_node` reads `empty_content` and turns such an error into a rejection that\n spends one rung of the ladder, so a node with an `on_fail` edge diverts instead of\n aborting the run. `verify.EmptyCompletion` documents that contract and names this\n module as marking its errors — which this module did not actually do, so the shipped\n backend aborted on the first content-less answer while the docs promised a retry.\n Found by audit. The diagnostic is kept verbatim: it is what an operator needs, and\n `_no_content_reason` is the part that says a reasoning model ate its own budget.\n \"\"\"\n error = BackendError(detail)\n error.empty_content = True\n return error\n\n\ndef _no_content_reason(response, choice, message):\n \"\"\"Say *why* a choice carried no text, not merely that it did not.\n\n The common cause on a reasoning model is a budget the private chain of thought ate\n before any answer was emitted: finish_reason \"length\", a populated `reasoning`\n field, and `content` null. Diagnosing that from \"no text content\" costs an hour, so\n name it and say what to change.\n \"\"\"\n finish = choice.get(\"finish_reason\")\n usage = response.get(\"usage\") or {}\n detail = usage.get(\"completion_tokens_details\") or {}\n thought = detail.get(\"reasoning_tokens\")\n reasoning = message.get(\"reasoning\")\n if finish == \"length\" and (thought or reasoning):\n return (\n \"the model spent its whole token budget reasoning and emitted no answer \"\n \"(finish_reason=length, %s reasoning tokens, content=null). This is a \"\n \"reasoning model: its private chain of thought is billed against the same \"\n \"ceiling as the answer. Raise the backend's reasoning_reserve (or the \"\n \"node's max_tokens) and run again.\"\n % (thought if thought is not None else \"some\")\n )\n if finish == \"length\":\n return (\n \"the model hit its token ceiling before emitting content \"\n \"(finish_reason=length). Raise the node's max_tokens.\"\n )\n if reasoning:\n return (\n \"the backend returned reasoning but no content (finish_reason=%r). Some \"\n \"reasoning models only fill `message.reasoning` when they stop early.\"\n % finish\n )\n return \"backend returned a choice with no text content (finish_reason=%r)\" % finish\n\n\ndef _read_error(exc, api_key=None):\n \"\"\"The upstream's own words about the failure, with the credentials taken out.\n\n An error body is written by somebody else and read by our logs, so it is filtered\n before it is quoted: the key we sent (a gateway may echo the request back), plus\n anything else bearer- or key-shaped that was already in there.\n \"\"\"\n try:\n body = exc.read().decode(\"utf-8\", \"replace\")\n except Exception:\n return exc.reason if getattr(exc, \"reason\", None) else \"\"\n if api_key:\n body = body.replace(api_key, \"\")\n return _clip(_redact(body))\n\n\ndef _ms(started):\n \"\"\"Milliseconds since `started`, at a resolution a log line can hold.\"\"\"\n return round((time.monotonic() - started) * 1000.0, 1)\n\n\ndef _usage(response):\n \"\"\"What this call cost, from the provider's own accounting.\n\n Every field is optional on the wire — llama.cpp-server omits the reasoning breakdown\n that Cerebras fills in — so a missing number is reported as None rather than guessed\n at or dropped. A stable set of field names is what makes a day of these lines\n summable; a field that vanishes when it is zero is not.\n \"\"\"\n usage = response.get(\"usage\") or {} if isinstance(response, dict) else {}\n detail = usage.get(\"completion_tokens_details\") or {}\n choices = response.get(\"choices\") if isinstance(response, dict) else None\n first = choices[0] if choices else {}\n return {\n \"prompt_tokens\": usage.get(\"prompt_tokens\"),\n \"completion_tokens\": usage.get(\"completion_tokens\"),\n \"reasoning_tokens\": detail.get(\"reasoning_tokens\"),\n \"total_tokens\": usage.get(\"total_tokens\"),\n \"finish_reason\": first.get(\"finish_reason\") if isinstance(first, dict) else None,\n }\n", "stepmold/cli.py": "\"\"\"`python3 -m stepmold` — run a pack, score it, or check it.\n\nThree commands, because a pack has exactly three things you do to it:\n\n stepmold validate is this pack well-formed?\n stepmold run --input '' execute it once\n stepmold eval score it against its contract\n\nExit codes are the contract with CI: **0** success, **1** the thing failed (invalid pack,\nfailed run, evalset not fully passed), **2** you called it wrong (argparse's own code).\n`stepmold eval` exiting 1 on a single failed case is the point — that is what makes an evalset\na gate rather than a report.\n\nargparse only, per the stdlib rule. ARCHITECTURE.md §7 names Typer + Rich; both are dependencies,\nso the help text here is plain and the report text is plain.\n\"\"\"\n\nimport argparse\nimport json\nimport os\nimport sys\n\nfrom . import __version__, log\nfrom .errors import StepmoldError\nfrom .eval import evaluate\nfrom .grammar import ValidationError\nfrom .pack import PackError, _resolve_inside, load_pack\n\n__all__ = [\"main\", \"resolve_model\"]\n\nMODEL_SCHEMES = (\"fake\", \"openai\")\nLOG_FORMATS = (\"text\", \"json\")\n\n\ndef main(argv=None):\n \"\"\"Run the CLI. Returns an exit code rather than calling sys.exit, so it is testable.\"\"\"\n parser = build_parser()\n args = parser.parse_args(argv)\n _start_logging(args)\n try:\n return args.handler(args)\n except PackError as exc:\n return _fail(\"pack error: %s\" % exc)\n except _build_error() as exc:\n return _fail(\"build error: %s\" % exc)\n except StepmoldError as exc:\n return _fail(\"%s: %s\" % (type(exc).__name__, exc))\n except (ValidationError, ValueError) as exc:\n return _fail(str(exc))\n except TypeError as exc:\n # A tool is free to return a datetime, a Decimal or an ORM row; JSON is not. The\n # value travels as far as the store or stdout before json refuses it, and the\n # refusal is a TypeError — the one error shape this handler did not name, so it\n # arrived as a raw traceback full of stepmold frames. Found by audit.\n #\n # Only that TypeError. json states its own case in a recognisable way, and a\n # TypeError from anywhere else is a bug that deserves its traceback rather than a\n # confident, wrong explanation about tool return values.\n if \"JSON serializable\" not in str(exc):\n raise\n return _fail(\"a value in state cannot be written as JSON: %s. A tool must return \"\n \"JSON-shaped values — str, int, float, bool, None, list or dict.\" % exc)\n\n\ndef _as_json(payload):\n \"\"\"Serialise for stdout the way the store already serialises for disk.\n\n Python writes NaN and Infinity by default; RFC 8259 has no such tokens, so jq, Go and\n most non-Python readers reject them. `stepmold run --store` refused those values already\n while the same run printed them to stdout and exited 0 — one invocation disagreeing\n with itself about whether a value was writable. Found by audit.\n \"\"\"\n return json.dumps(payload, sort_keys=True, allow_nan=False)\n\n\ndef _build_error():\n \"\"\"BuildError, or a class that never matches when the compiler is not installed.\n\n Importing stepmold.build from the top of this module would defeat the separation the\n compiler is built around, so the exception type is fetched only when it is needed.\n \"\"\"\n try:\n from .build.spec import BuildError\n except Exception: # pragma: no cover - the runtime may ship without stepmold.build\n class BuildError(Exception):\n pass\n return BuildError\n\n\ndef build_parser():\n parser = argparse.ArgumentParser(\n prog=\"stepmold\",\n description=\"Compile your agent once with a frontier model. \"\n \"Run it forever on a small one.\",\n )\n parser.add_argument(\"--version\", action=\"version\", version=\"stepmold %s\" % __version__)\n commands = parser.add_subparsers(dest=\"command\")\n observability = _observability_options()\n\n validate = commands.add_parser(\"validate\", parents=[observability],\n help=\"check that a pack is well-formed\")\n validate.add_argument(\"pack\", help=\"path to the pack directory\")\n _add_tools_option(validate)\n validate.set_defaults(handler=command_validate)\n\n run = commands.add_parser(\"run\", parents=[observability], help=\"execute a pack once\")\n run.add_argument(\"pack\", help=\"path to the pack directory\")\n run.add_argument(\"--input\", default=\"{}\", help=\"run inputs as a JSON object\")\n run.add_argument(\"--model\", help=\"model spec (default: the pack manifest's)\")\n run.add_argument(\"--allow-pack-model\", dest=\"allow_pack_model\", action=\"store_true\",\n help=\"accept a network endpoint chosen by the pack's manifest\")\n run.add_argument(\"--run-id\", dest=\"run_id\", help=\"name this run\")\n run.add_argument(\"--store\", help=\"SQLite file to checkpoint into\")\n run.add_argument(\"--resume\", help=\"continue a previous run id (needs --store)\")\n run.add_argument(\"--state\", action=\"store_true\",\n help=\"print the whole final state, not the end node's projection\")\n _add_tools_option(run)\n run.set_defaults(handler=command_run)\n\n build = commands.add_parser(\n \"build\", help=\"compile a pack from a task description and gold examples\")\n build.add_argument(\"spec\", help=\"directory holding task.md and examples.jsonl\")\n build.add_argument(\"-o\", \"--out\", required=True, help=\"where to write the pack\")\n build.add_argument(\"--model\", required=True,\n help=\"the planning model, e.g. openai:https://host/v1#model\")\n build.add_argument(\"--name\", help=\"pack name (default: the output directory's name)\")\n build.add_argument(\"--attempts\", type=int, default=3,\n help=\"how many times to re-plan on a failing eval (default: 3)\")\n build.add_argument(\"--overwrite\", action=\"store_true\",\n help=\"replace the output directory if it already exists\")\n build.set_defaults(handler=command_build)\n\n evaluate_command = commands.add_parser(\n \"eval\", parents=[observability],\n help=\"score a pack against its evalset (exit 1 if any case fails)\"\n )\n evaluate_command.add_argument(\"pack\", help=\"path to the pack directory\")\n evaluate_command.add_argument(\"--model\", help=\"model spec (default: the manifest's)\")\n evaluate_command.add_argument(\"--json\", action=\"store_true\",\n help=\"emit the report as JSON\")\n evaluate_command.add_argument(\n \"--tiers\", action=\"store_true\",\n help=\"also print the auto/escalated/failed split and the accuracy within \"\n \"the auto tier\",\n )\n _add_tools_option(evaluate_command)\n evaluate_command.set_defaults(handler=command_eval)\n\n parser.set_defaults(handler=lambda args: _usage(parser))\n return parser\n\n\ndef _add_tools_option(command):\n \"\"\"`--tools`, on the two subcommands that execute a pack.\n\n An operator-only flag, and that is the whole security model of `stepmold.tools` expressed\n at the command line: a pack *names* the actions it wants and the host *supplies*\n them. There is deliberately no manifest key for this — a pack you did not write must\n not be able to choose which code its tool names resolve to.\n \"\"\"\n command.add_argument(\n \"--tools\", metavar=\"MODULE[:ATTR]\",\n help=\"python module (or ./path.py) defining a ToolRegistry the pack may call; \"\n \"the registry is looked up as 'registry' or 'REGISTRY' unless :ATTR names it\",\n )\n\n\ndef _observability_options():\n \"\"\"`--log-level` / `--log-format`, shared by every subcommand.\n\n A parent parser rather than three copies, and rather than options on the top-level\n parser: argparse only accepts a top-level option *before* the subcommand, and nobody\n types `stepmold --log-level info run pack`.\n\n The default is `off`, and that is the contract: with no flag, stepmold configures no\n handler, sets no level, and prints exactly what it printed before this existed.\n Logging is an operator's explicit request, not a thing that happens to them.\n \"\"\"\n shared = argparse.ArgumentParser(add_help=False)\n shared.add_argument(\n \"--log-level\", dest=\"log_level\", default=\"off\", choices=log.LEVELS,\n help=\"emit run events on stderr at this level (default: off)\",\n )\n shared.add_argument(\n \"--log-format\", dest=\"log_format\", default=\"text\", choices=LOG_FORMATS,\n help=\"'text' for a terminal, 'json' for one JSON object per line\",\n )\n return shared\n\n\ndef _start_logging(args):\n \"\"\"Turn logging on if this invocation asked for it. Only an application may.\n\n stderr, always. `stepmold run` prints its result as JSON on stdout and callers pipe it\n onward; a log line there would corrupt the output instead of describing it.\n \"\"\"\n level = getattr(args, \"log_level\", \"off\")\n if not level or level == \"off\":\n return\n log.configure(level=level, fmt=getattr(args, \"log_format\", \"text\"),\n stream=sys.stderr)\n\n\n# ------------------------------------------------------------------------ commands\n\n\ndef _load_checked(args):\n \"\"\"Load the pack, checking its tool wiring whenever a registry is available.\n\n `load_pack` skips the tool check when given no registry, which is right for a pack\n whose tools live in another process. But every command called it that way, so the check\n was unreachable from the CLI: a pack naming a tool nobody registered validated clean,\n exit 0, and then died at the step that would have called it — exactly the failure the\n check exists to prevent, and exactly what the documentation claimed was prevented.\n \"\"\"\n if getattr(args, \"tools\", None):\n return load_pack(args.pack, tools=_tool_registry(args, None))\n return load_pack(args.pack)\n\n\ndef command_validate(args):\n pack = _load_checked(args)\n _check_output_shapes(pack)\n # Say when the tool wiring was checked. Without this the flag is invisible: passing\n # --tools printed exactly what omitting it printed, so a reader had no way to tell\n # whether the stricter check had run, and a CI log could not show that it had.\n checked = \"\"\n if getattr(args, \"tools\", None):\n wired = sorted({node.tool for node in pack.nodes.values() if node.tool})\n checked = \", %s checked\" % _count(len(wired), \"tool\")\n print(\n \"%s v%s: %s, %s, %s, entry %r%s\"\n % (\n pack.name,\n pack.version,\n _count(len(pack.nodes), \"node\"),\n _count(len(pack.edges), \"edge\"),\n _count(len(pack.evalset), \"evalset case\"),\n pack.entry,\n checked,\n )\n )\n return 0\n\n\ndef _count(number, noun):\n return \"%d %s%s\" % (number, noun, \"\" if number == 1 else \"s\")\n\n\ndef command_run(args):\n from .graph import run as run_pack\n from .state import Store, resume\n\n pack = _load_checked(args)\n _check_output_shapes(pack)\n if args.resume and not args.store:\n return _fail(\"--resume needs --store: checkpoints live in the store\")\n\n tools = _tool_registry(args, resume if args.resume else run_pack)\n # Only when the operator asked for tools: a walker that takes no `tools` keyword must\n # keep running every pack that needs none, which is every pack written so far.\n extra = {\"tools\": tools} if tools is not None else {}\n\n store = Store(args.store) if args.store else None\n try:\n if args.resume:\n result = resume(pack, resolve_model(args.model, pack, _allow(args)),\n args.resume, store, **extra)\n else:\n result = run_pack(\n pack,\n resolve_model(args.model, pack, _allow(args)),\n _parse_input(args.input),\n run_id=args.run_id,\n store=store,\n **extra\n )\n finally:\n if store is not None:\n store.close()\n\n payload = result.state if args.state else result.output\n if not args.state and not payload and result.state:\n # `{}` printed on stdout with exit 0 reads as \"the run produced nothing\", when\n # what happened is that the end node projected nothing out of a state that has\n # content. Say which, rather than let a caller pipe an empty result onward.\n return _fail(\n \"end node %r projected nothing: its 'output' names no key that exists in \"\n \"state (state has: %s). Fix the node's 'output', or pass --state to print \"\n \"the whole state.\" % (result.end_node, \", \".join(sorted(result.state)))\n )\n print(_as_json(payload))\n return 0\n\n\ndef command_eval(args):\n from .graph import run as run_pack\n\n pack = _load_checked(args)\n _check_output_shapes(pack)\n tools = _tool_registry(args, run_pack)\n report = evaluate(pack, resolve_model(args.model, pack, _allow(args)), tools=tools)\n if args.json:\n # The JSON report carries the tier split unconditionally. It is a machine\n # surface, an added key breaks nothing that reads the old ones, and an automation\n # rate that only appears behind a flag is one a deployment review can miss.\n print(_as_json(_report_json(report)))\n else:\n # The text report is unchanged, always. Existing scripts grep it and the README's\n # transcripts are executed as tests; `--tiers` adds a block, it rewrites nothing.\n print(report.summary())\n if args.tiers:\n print(report.tier_summary())\n return 0 if report.passed_all else 1\n\n\ndef _check_output_shapes(pack):\n \"\"\"Refuse a pack that uses `output:` in the shape the other node type wants.\n\n One word, two meanings: on a `generate` node `output` is the single state key to\n commit the result under, on an `end` node it is the list of keys to project. Nothing\n checks which one was written — `output: ticket` on an end node makes the projection\n iterate the *string*, match no state key, and return an empty object while the state\n still holds the data. That belongs in `pack.load_pack` at load time; until it lives\n there, the CLI refuses the pack instead of running it and printing the silence.\n \"\"\"\n problems = []\n for name in sorted(pack.nodes):\n node = pack.nodes[name]\n if node.output is None:\n continue\n if node.type == \"end\" and not _is_key_list(node.output):\n hint = \"\"\n if isinstance(node.output, str):\n hint = \" — write 'output: [%s]' if you meant that one key\" % node.output\n problems.append(\n \"graph.yaml: end node %r: 'output' must be a list of state keys to \"\n \"project, got %r%s\" % (name, node.output, hint)\n )\n elif node.type == \"generate\" and not isinstance(node.output, str):\n problems.append(\n \"graph.yaml: generate node %r: 'output' must be a single state key to \"\n \"commit the result under (a string), got %r\" % (name, node.output)\n )\n if problems:\n raise ValueError(\"\\n \".join(problems))\n\n\ndef _is_key_list(output):\n return isinstance(output, list) and all(isinstance(key, str) for key in output)\n\n\n# -------------------------------------------------------------------------- models\n\n\ndef _allow(args):\n \"\"\"Whether this invocation accepts a network endpoint chosen by the pack.\"\"\"\n return bool(getattr(args, \"allow_pack_model\", False))\n\n\ndef command_build(args):\n \"\"\"Compile a pack. The only subcommand that needs a model at all times.\n\n stepmold.build is imported here rather than at module scope on purpose: the runtime ships\n to a client box and must not carry the compiler, and a test asserts that importing\n stepmold.cli does not pull stepmold.build in behind it.\n \"\"\"\n from .build.compile import compile_pack, load_build_spec\n\n description, cases = load_build_spec(args.spec)\n\n # A build model is always given explicitly. There is no pack to read a default from,\n # and a compile is the one moment where quietly choosing a model for someone would be\n # the wrong kind of helpful.\n model = _build_model(args.model)\n\n result = compile_pack(\n args.out, description, cases, model,\n name=args.name, attempts=args.attempts, overwrite=args.overwrite,\n on_event=lambda message: print(message, file=sys.stderr),\n )\n print(result.directory)\n return 0\n\n\ndef _build_model(spec):\n \"\"\"Resolve --model for a build. Same spec grammar as `run`, minus the pack.\"\"\"\n scheme, _, rest = spec.partition(\":\")\n if scheme == \"openai\":\n return _openai_model(rest)\n if scheme == \"fake\":\n from .model import FakeModel\n\n full = os.path.abspath(rest)\n if not os.path.isfile(full):\n raise ValueError(\"fake: no such script %r\" % full)\n with open(full) as handle:\n return FakeModel(json.load(handle))\n raise ValueError(\n \"unknown model scheme %r for build (known: openai, fake)\" % scheme\n )\n\n\ndef resolve_model(spec, pack, allow_pack_model=False):\n \"\"\"Turn a model spec into a `Model`.\n\n Two schemes:\n\n fake: a scripted FakeModel from JSON — a list of\n responses, or an object keyed by prompt\n substring. A relative path resolves inside the\n pack, which is what lets a pack ship its own\n offline model so CI needs no GPU.\n openai:#[#[#]]\n an OpenAI-compatible server (llama.cpp-server,\n vLLM, SGLang). Constructing it opens no\n connection; the first generate does.\n \"\"\"\n from_pack = not spec\n spec = spec or pack.model\n if not spec:\n raise ValueError(\n \"no model: pass --model or set 'model:' in the pack manifest\"\n )\n scheme, _, rest = spec.partition(\":\")\n if scheme == \"fake\":\n return _fake_model(rest, pack)\n if scheme == \"openai\":\n # A pack must not be able to aim a credentialed client at a host it names: the\n # request carries the rendered prompt and the ambient API key. `fake:` is exempt\n # because it is local and contained (see _fake_model), which is what lets a pack\n # ship its own offline model for CI.\n if from_pack and not allow_pack_model:\n raise ValueError(\n \"this pack's manifest selects a network endpoint (%r). Pass --model to \"\n \"choose the endpoint yourself, or --allow-pack-model to accept the \"\n \"pack's choice.\" % spec\n )\n return _openai_model(rest)\n raise ValueError(\n \"unknown model scheme %r in %r (known: %s)\"\n % (scheme, spec, \", \".join(MODEL_SCHEMES))\n )\n\n\ndef _openai_model(rest):\n from .backends.openai_compat import OpenAICompatModel\n\n parts = rest.split(\"#\")\n base_url = parts[0].strip()\n name = parts[1].strip() if len(parts) > 1 else \"\"\n if not base_url or not name:\n raise ValueError(\n \"openai: needs a base url and a model name, \"\n \"e.g. openai:http://localhost:8000#qwen3-8b\"\n )\n options = {\"base_url\": base_url, \"model\": name}\n if len(parts) > 2 and parts[2].strip():\n options[\"grammar_mode\"] = parts[2].strip()\n if len(parts) > 3 and parts[3].strip():\n # Reasoning headroom belongs to the backend, not the pack: a pack budgets the\n # answer and stays portable, while this says how much extra THIS model needs to\n # think. See openai_compat.build_payload.\n try:\n options[\"reasoning_reserve\"] = int(parts[3].strip())\n except ValueError:\n raise ValueError(\n \"openai: reasoning reserve must be an integer, got %r\" % parts[3].strip()\n )\n return OpenAICompatModel(**options)\n\n\ndef _fake_model(path, pack):\n from .model import FakeModel\n\n if not path:\n raise ValueError(\"fake: needs a path to a JSON script, e.g. fake:fakes/script.json\")\n try:\n full = _resolve_inside(pack.path, path)\n except PackError as exc:\n raise ValueError(\"fake: %s\" % exc)\n if not os.path.isfile(full):\n raise ValueError(\"fake model script not found: %s\" % full)\n with open(full, \"r\") as handle:\n try:\n return FakeModel(json.load(handle))\n except ValueError as exc:\n raise ValueError(\"%s is not valid JSON (%s)\" % (full, exc))\n\n\n# ---------------------------------------------------------------------------- tools\n\n\nREGISTRY_NAMES = (\"registry\", \"REGISTRY\")\n\n\ndef _tool_registry(args, entry_point):\n \"\"\"Resolve `--tools`, or `None` when this invocation did not ask for tools.\n\n `entry_point` is the function about to be called with the registry. It is checked\n rather than assumed: a runtime whose walker predates tool nodes would otherwise\n answer `--tools` with `TypeError: run() got an unexpected keyword argument`, which\n says nothing about what the operator should do instead.\n \"\"\"\n spec = getattr(args, \"tools\", None)\n if not spec:\n return None\n # `entry_point` is None when the registry is wanted only to CHECK a pack's wiring at\n # load time, not to run it. There is nothing to be compatible with in that case, so\n # the capability check does not apply — `stepmold validate --tools` must work on a runtime\n # whose walker predates tool nodes, since checking is exactly what such a runtime can\n # still usefully do.\n if entry_point is not None and not _accepts_tools(entry_point):\n raise ValueError(\n \"--tools: this stepmold runtime cannot run tools — %s.%s takes no 'tools' \"\n \"argument. Upgrade stepmold, or drop the flag.\"\n % (entry_point.__module__, entry_point.__name__)\n )\n return _load_registry(spec)\n\n\ndef _accepts_tools(function):\n \"\"\"Whether `function` will accept a `tools=` keyword.\n\n The same question `graph._save_accepts_attempts` asks of a store, asked for the same\n reason: these are seams between a version of stepmold and code written against another\n one, and a clear refusal beats a keyword error from three frames down.\n \"\"\"\n import inspect\n\n try:\n parameters = inspect.signature(function).parameters.values()\n except (TypeError, ValueError): # a builtin, or something without a signature\n return False\n kinds = (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)\n return any(\n parameter.kind is inspect.Parameter.VAR_KEYWORD\n or (parameter.name == \"tools\" and parameter.kind in kinds)\n for parameter in parameters\n )\n\n\ndef _load_registry(spec):\n \"\"\"`module[:attribute]` or `./path.py[:attribute]` -> the host's `ToolRegistry`.\n\n Importing it runs the operator's own code, which is exactly the point: the tools are\n the host's, written by the host, and this is how the host hands them over. Nothing in\n the pack reaches this function — see `_add_tools_option`.\n\n importlib is imported here rather than at module scope, like every other thing the\n CLI can reach into: `import stepmold.cli` must stay as cheap as the runtime that never\n passes this flag. Nothing here imports `stepmold.tools` either — the registry is\n duck-typed, so a host may hand over its own wrapper.\n \"\"\"\n import importlib\n\n target, _, attribute = spec.partition(\":\")\n target = target.strip()\n if not target:\n raise ValueError(\n \"--tools: needs a module or file, e.g. --tools mytools or \"\n \"--tools ./mytools.py:registry\"\n )\n if target.endswith(\".py\") or os.sep in target:\n module = _module_from_file(target)\n else:\n try:\n module = importlib.import_module(target)\n except ModuleNotFoundError as exc:\n if exc.name != target:\n raise # the module is there; something IT imports is not. Let it speak.\n raise ValueError(\n \"--tools: no module named %r on sys.path. Give a file path \"\n \"(--tools ./mytools.py), or set PYTHONPATH.\" % target\n )\n return _registry_from(module, attribute.strip(), spec)\n\n\ndef _module_from_file(path):\n \"\"\"Load a .py file as a module without putting its directory on sys.path.\n\n A host's tool module usually sits next to the pack rather than in site-packages, and\n prepending its directory to sys.path would change what every later import in the\n process resolves to.\n \"\"\"\n import importlib.util\n\n full = os.path.abspath(path)\n if not os.path.isfile(full):\n raise ValueError(\"--tools: no such file %s\" % full)\n name = \"_stepmold_tools_%s\" % os.path.splitext(os.path.basename(full))[0]\n spec = importlib.util.spec_from_file_location(name, full)\n if spec is None or spec.loader is None:\n raise ValueError(\"--tools: %s is not importable as a Python module\" % full)\n module = importlib.util.module_from_spec(spec)\n spec.loader.exec_module(module)\n return module\n\n\ndef _registry_from(module, attribute, spec):\n \"\"\"Find the registry inside a loaded module, and check it is one.\"\"\"\n names = [attribute] if attribute else list(REGISTRY_NAMES)\n found = None\n for name in names:\n found = getattr(module, name, None)\n if found is not None:\n break\n if found is None:\n raise ValueError(\n \"--tools: %s defines no %s. Name it explicitly with %s:, or \"\n \"assign your ToolRegistry to one of those names.\"\n % (getattr(module, \"__name__\", spec), \" or \".join(repr(n) for n in names),\n spec.partition(\":\")[0])\n )\n if callable(found) and not _looks_like_registry(found):\n # A factory is allowed — `def registry(): ...` returning a fresh registry is the\n # natural shape when the tools need a database handle to close over.\n found = found()\n if not _looks_like_registry(found):\n raise ValueError(\n \"--tools: %s is a %s, not a ToolRegistry (see stepmold.tools)\"\n % (spec, type(found).__name__)\n )\n return found\n\n\ndef _looks_like_registry(value):\n \"\"\"Duck-typed rather than isinstance: a host may wrap or subclass its registry.\"\"\"\n return all(hasattr(value, name) for name in (\"get\", \"has\", \"names\"))\n\n\n# --------------------------------------------------------------------------- output\n\n\ndef _report_json(report):\n return {\n \"pack\": report.pack,\n \"passed\": report.passed,\n \"failed\": report.failed,\n \"total\": report.total,\n \"by_node\": report.by_node,\n # Rates are fractions, not percentages, and `auto_accuracy` is null rather than\n # zero when nothing was automated: a report that is read by a script should hand\n # over the measurement, not a rounded rendering of it, and should never hand over\n # a number nobody measured.\n \"tiers\": {\n \"counts\": dict(report.tier_counts),\n \"automation_rate\": report.automation_rate,\n \"escalation_rate\": report.escalation_rate,\n \"failure_rate\": report.failure_rate,\n \"auto_accuracy\": report.auto_accuracy,\n \"auto_passed\": report.auto_passed,\n \"auto_total\": len(report.auto_cases),\n \"escalated_by\": dict(report.escalated_by),\n \"failed_by\": dict(report.failed_by),\n },\n \"cases\": [\n {\n \"name\": case.name,\n \"passed\": case.passed,\n \"node\": case.node,\n \"error\": case.error,\n \"tier\": case.tier,\n \"escalations\": [\n {\n \"node\": escalation.node,\n \"kind\": escalation.kind,\n \"reason\": escalation.reason,\n }\n for escalation in case.escalations\n ],\n \"expected\": case.expected,\n \"actual\": case.actual,\n \"mismatches\": [\n {\n \"field\": mismatch.field,\n \"expected\": mismatch.expected,\n \"actual\": mismatch.actual,\n \"node\": mismatch.node,\n \"note\": mismatch.note,\n }\n for mismatch in case.mismatches\n ],\n }\n for case in report.cases\n ],\n }\n\n\ndef _parse_input(text):\n try:\n value = json.loads(text)\n except ValueError as exc:\n raise ValueError(\"--input is not valid JSON (%s)\" % exc)\n if not isinstance(value, dict):\n raise ValueError(\"--input must be a JSON object, got %s\" % type(value).__name__)\n return value\n\n\ndef _usage(parser):\n parser.print_usage(sys.stderr)\n sys.stderr.write(\"stepmold: a command is required (run, eval, validate)\\n\")\n return 2\n\n\ndef _fail(message):\n sys.stderr.write(\"stepmold: %s\\n\" % message)\n return 1\n", "stepmold/codegen.py": "\"\"\"How one node's output gets generated: think -> emit, or just emit.\n\nThis is the fix for the constraint tax (docs/ARCHITECTURE.md §2, Bug 2): forcing a model to\ncommit to a schema on its first token costs quality, and the known remedy is to separate\nthe reasoning from the formatting. So a `two_stage: true` node runs twice —\n\n 1. `think` unconstrained, token-capped, output kept in a scratchpad\n 2. `emit` constrained by the node's grammar, conditioned on that scratchpad\n\n— and the scratchpad is **returned to the caller, never committed to state**. That is not\na detail: state is what downstream prompts see, and letting a model's own loose reasoning\nback into its later context is the self-conditioning decay this whole design exists to\navoid. `Attempt` carries the scratchpad; `graph.commit` writes only `Attempt.text`.\n\nSingle-stage nodes skip straight to emit, so trivial nodes stay one call cheap.\n\nThis module is also where the `Model` protocol's *optional* per-call sampling hint is\nspent (`Sampling`). The retry ladder decides what to ask for; `_generate` decides whether\nthe model in front of it can hear the question. A model whose `generate` does not declare\na `sampling` parameter is called exactly as before, which is what keeps every existing\n`Model` — `FakeModel`, the production harness's `FlakyModel`, `OpenAICompatModel` — a\nvalid `Model` without a line of change. See `verify.run_node` for why a re-sample needs\nthe hint at all.\n\"\"\"\n\nimport inspect\nfrom dataclasses import dataclass\nfrom functools import lru_cache\nfrom typing import Optional\n\nfrom .errors import BackendError\nfrom .grammar import schema_to_grammar\nfrom .log import DEBUG, event, get_logger\nfrom .render import render\n\n_log = get_logger(\"codegen\")\n\n__all__ = [\n \"Attempt\",\n \"SCRATCHPAD\",\n \"Sampling\",\n \"accepts_sampling\",\n \"generate_once\",\n \"think\",\n \"emit\",\n]\n\nSCRATCHPAD = \"scratchpad\"\nSAMPLING = \"sampling\"\n\nDEFAULT_THINK_SUFFIX = (\n \"\\n\\nThink this through in a few short sentences. \"\n \"Do not answer in JSON yet — notes only.\"\n)\nSCRATCHPAD_BLOCK = \"\\n\\nYour notes from thinking this through:\\n%s\"\nERROR_BLOCK = (\n \"\\n\\nYour previous answer was rejected: %s\\n\"\n \"Return corrected output that satisfies the schema.\"\n)\n\n\n@dataclass(frozen=True)\nclass Sampling:\n \"\"\"What the ladder asks a backend for when it wants a *different* draw.\n\n A hint, not a command: it is the one thing this layer can change that makes a\n re-sample an independent draw rather than the identical request twice. Backends that\n cannot vary their sampling ignore it, and the ladder still has its feedback rung.\n\n `seed` is here because a server pinned to temperature 0 is deterministic in its\n *stream*, not in its arithmetic: llama.cpp, vLLM and SGLang all accept a per-request\n seed, and changing it is the only knob a greedy server has.\n \"\"\"\n\n temperature: float\n seed: Optional[int] = None\n\n\n@dataclass\nclass Attempt:\n \"\"\"One pass at a node's output. `text` is what gets verified and committed.\"\"\"\n\n text: str\n scratchpad: Optional[str] = None\n calls: int = 0\n\n\ndef generate_once(node, state, model, error=None, scratchpad=None, sampling=None):\n \"\"\"Produce one candidate output for `node`.\n\n `error` is the previous rejection, appended so a re-sample can correct itself\n (T6's ladder). `scratchpad` reuses an earlier think stage instead of paying for\n another one; the caller decides whether reusing it is honest — see\n `verify.run_node`, which throws it away whenever the reasoning behind it is what got\n rejected. `sampling` is the ladder's request for a different draw, and it applies to\n *both* stages: re-thinking at the same temperature as the notes that were just\n discarded would reproduce them.\n \"\"\"\n calls = 0\n if node.two_stage and scratchpad is None:\n scratchpad = think(node, state, model, sampling=sampling)\n calls += 1\n try:\n text = emit(node, state, model, scratchpad=scratchpad, error=error,\n sampling=sampling)\n except BackendError as exc:\n # The notes survive the failure they were not part of. A backend that returned\n # nothing has said nothing about the reasoning, and a ladder that re-samples on\n # it should not pay for a second think stage — see `verify.run_node`.\n exc.scratchpad = scratchpad\n raise\n return Attempt(text=text, scratchpad=scratchpad, calls=calls + 1)\n\n\ndef think(node, state, model, sampling=None):\n \"\"\"The unconstrained first stage. Its output never leaves the scratchpad.\"\"\"\n template = node.think_prompt or (node.prompt + DEFAULT_THINK_SUFFIX)\n # The default template is the emit prompt, which may itself hold a {scratchpad}\n # placeholder. There are no notes yet, so it renders empty rather than exploding.\n scope = dict(state)\n scope.setdefault(SCRATCHPAD, \"\")\n prompt = render(template, scope)\n # The size of a prompt, never the prompt. A rendered prompt holds whatever the caller\n # put into state — a whole support ticket, a customer's name — and the point of\n # logging it would be to see it. Bytes tell an operator what they actually came for:\n # whether a prompt is the size they think it is, and where a token bill went.\n if _log.isEnabledFor(DEBUG):\n # Guarded at the call site, not just inside `event`. This fires once per\n # generation and the long-horizon suite makes hundreds of thousands of them, so\n # even building the keyword dict for an event nobody is listening to is a cost\n # worth not paying. The check itself is one bound-method call returning False.\n event(_log, DEBUG, \"node.think\", node=node.name, prompt_bytes=len(prompt),\n max_tokens=node.think_max_tokens)\n return _generate(model, prompt, None, node.think_max_tokens, sampling)\n\n\ndef emit(node, state, model, scratchpad=None, error=None, sampling=None):\n \"\"\"The constrained stage: the only output that can ever be committed.\"\"\"\n prompt = build_prompt(node, state, scratchpad=scratchpad, error=error)\n if _log.isEnabledFor(DEBUG):\n event(_log, DEBUG, \"node.emit\", node=node.name, prompt_bytes=len(prompt),\n grammar=bool(node.grammar), max_tokens=node.max_tokens,\n scratchpad_bytes=len(scratchpad) if scratchpad is not None else None,\n corrected=bool(error))\n return _generate(\n model,\n prompt,\n schema_to_grammar(node.grammar) if node.grammar else None,\n node.max_tokens,\n sampling,\n )\n\n\ndef _generate(model, prompt, grammar, max_tokens, sampling):\n \"\"\"Call the model, passing the sampling hint only to a model that declares one.\n\n The hint is optional in the protocol, so it cannot be sent unconditionally: a model\n written against the three-argument signature would raise `TypeError` on a keyword it\n never asked for, and stepmold would have broken every existing backend to gain a knob most\n of them ignore anyway.\n \"\"\"\n if sampling is None or not accepts_sampling(model):\n return model.generate(prompt, grammar=grammar, max_tokens=max_tokens)\n return model.generate(\n prompt, grammar=grammar, max_tokens=max_tokens, sampling=sampling\n )\n\n\ndef accepts_sampling(model):\n \"\"\"True when `model.generate` declares the optional `sampling` keyword.\"\"\"\n return _accepts_sampling(type(model))\n\n\n@lru_cache(maxsize=None)\ndef _accepts_sampling(model_type):\n # Cached on the type, not the instance: the signature belongs to the class, and a\n # ladder asks this question once per generation.\n generate = getattr(model_type, \"generate\", None)\n if generate is None:\n return False\n try:\n parameters = inspect.signature(generate).parameters.values()\n except (TypeError, ValueError): # a builtin or C-level callable has no signature\n return False\n kinds = (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)\n for parameter in parameters:\n if parameter.kind is inspect.Parameter.VAR_KEYWORD:\n return True\n if parameter.name == SAMPLING and parameter.kind in kinds:\n return True\n return False\n\n\ndef build_prompt(node, state, scratchpad=None, error=None):\n \"\"\"Assemble the emit prompt.\n\n Volatile content goes last. That is a prefix-cache decision, not a style one:\n ARCHITECTURE.md §2 wants every prompt ordered most-stable-first so the KV cache hit rate is\n engineered rather than accidental. The node template is stable, the scratchpad\n changes every call, and a correction changes every retry.\n \"\"\"\n placeholder = \"{%s}\" % SCRATCHPAD\n if scratchpad is not None and placeholder in node.prompt:\n prompt = render(node.prompt, dict(state, **{SCRATCHPAD: scratchpad}))\n else:\n prompt = render(node.prompt, state)\n if scratchpad is not None:\n prompt += SCRATCHPAD_BLOCK % scratchpad\n if error:\n prompt += ERROR_BLOCK % error\n return prompt\n", "stepmold/errors.py": "\"\"\"Every error a *run* can raise, in one place.\n\nThe walker, the codegen, the verifier and the eval runner all raise these, and several\nof them import each other. Keeping the hierarchy in a leaf module is what stops that from\nbecoming an import cycle. Pack-loading errors are different — they belong to `stepmold.pack`,\nbecause they happen before a run exists.\n\"\"\"\n\n__all__ = [\n \"AssertFailed\",\n \"BackendError\",\n \"DanglingEdge\",\n \"DeadEnd\",\n \"ExprError\",\n \"StepmoldError\",\n \"MaxStepsExceeded\",\n \"MissingVariable\",\n \"NodeFailed\",\n \"RunError\",\n \"RunIdInUse\",\n \"UnknownRun\",\n]\n\n\nclass StepmoldError(Exception):\n \"\"\"Base class for everything stepmold raises at run time.\"\"\"\n\n\nclass RunError(StepmoldError):\n \"\"\"A run could not continue.\"\"\"\n\n\nclass MissingVariable(RunError):\n \"\"\"A prompt referenced a state variable that is not there.\"\"\"\n\n\nclass ExprError(RunError):\n \"\"\"An assert expression is unsupported, or references something missing.\"\"\"\n\n\nclass DeadEnd(RunError):\n \"\"\"No outgoing edge matched the current state.\"\"\"\n\n\nclass DanglingEdge(RunError):\n \"\"\"An edge points at a node that does not exist.\"\"\"\n\n\nclass MaxStepsExceeded(RunError):\n \"\"\"The walk ran longer than the graph's step budget — probably an unbroken loop.\"\"\"\n\n\nclass NodeFailed(RunError):\n \"\"\"A node exhausted its retry ladder and has no `on_fail` edge.\n\n `node` is the node name, `attempts` the number of generations spent, and `reason`\n the last verification failure.\n\n `feedback` is the *safe half* of that reason — `verify.Rejected.feedback`, which says\n what was wrong without quoting what the model said. It exists because this exception\n is now read by two audiences with different rights: an operator debugging a pack, who\n gets `reason` in `RunResult.failures`, in the checkpoint and in a DEBUG log line; and\n a default-level log line, which an operator may ship to a collector and which must\n therefore carry no model output at all. Optional, and None when nobody supplied one —\n the walker says \"detail at DEBUG\" rather than guessing which half it is holding.\n \"\"\"\n\n def __init__(self, node, reason, attempts=0, feedback=None):\n self.node = node\n self.reason = reason\n self.attempts = attempts\n self.feedback = feedback\n RunError.__init__(\n self, \"node %r failed after %d attempt(s): %s\" % (node, attempts, reason)\n )\n\n\nclass AssertFailed(RunError):\n \"\"\"An `assert` node's expression was false and the node has no `on_fail`.\"\"\"\n\n def __init__(self, node, expression):\n self.node = node\n self.expression = expression\n RunError.__init__(self, \"assert node %r failed: %s\" % (node, expression))\n\n\nclass RunIdInUse(RunError):\n \"\"\"A fresh run was started under a run id that already has checkpoints.\n\n Welding two runs into one chain lets `resume` hand back the earlier run's output —\n one caller's data returned as another's, with a zero exit code. Refuse instead.\n \"\"\"\n\n\nclass UnknownRun(RunError):\n \"\"\"A run id with no checkpoint behind it.\"\"\"\n\n\nclass BackendError(RunError):\n \"\"\"A real inference backend could not be reached, or answered with nonsense.\"\"\"\n", "stepmold/eval.py": "\"\"\"Scoring a pack against its evalset.\n\nThe evalset is the contract (docs/ARCHITECTURE.md §1): prompts, grammars and graphs are all\nregenerable build outputs, but the gold examples are the hand-maintained asset, and\n\"v3 passes 50/50\" is the sentence a regulated buyer can actually audit.\n\nWhat makes this more than a test runner is **attribution**. DSPy's known limitation is\nthat optimisation is end-to-end and a failure is a black box; because a stepmold graph gives\nevery node its own input/output contract and the walker records which node wrote which\nstate key, a failed case can name the node that caused it. `Report.by_node` is that\nper-node signal — the thing a future `stepmold build` would optimise against.\n\nThe second thing it reports is **the tier split**. A single pass rate is the wrong number\nto ship on: it averages the cases the pack answered on its own together with the cases it\nhanded to a human, and those two populations are not comparable. What a buyer is owed\nbefore anything is deployed is three numbers — how much ran automatically, how much went\nto a person, and how right the automatic part was — because a pack that automates 60% at\n99.9% is worth more than one that automates 95% at 92%, and one pass rate hides which is\nwhich. So every case is classified:\n\n auto the run finished with no node unsure and nothing diverted\n escalated a node was unsure or ran out of ladder, and the pack routed it\n failed nothing routed it; the run could not finish at all\n\nand `Report.auto_accuracy` is scored over the auto bucket alone. The accuracy of the\nescalated bucket is not the pack's claim to make — a human answers those.\n\"\"\"\n\nfrom collections import OrderedDict\nfrom dataclasses import dataclass, field\nfrom typing import Any, Dict, List, Optional\n\nfrom .errors import NodeFailed\nfrom .graph import run\n\n__all__ = [\n \"CaseResult\",\n \"Escalation\",\n \"Mismatch\",\n \"Report\",\n \"TIERS\",\n \"TIER_AUTO\",\n \"TIER_ESCALATED\",\n \"TIER_FAILED\",\n \"evaluate\",\n]\n\n_MISSING = object()\nUNKNOWN_NODE = \"\"\n\n# The three tiers, in the order a report reads them: what the pack did by itself, what it\n# handed over, and what it could not finish. They are strings rather than an enum because\n# they cross into JSON and into a text report, and both want the word.\nTIER_AUTO = \"auto\"\nTIER_ESCALATED = \"escalated\"\nTIER_FAILED = \"failed\"\nTIERS = (TIER_AUTO, TIER_ESCALATED, TIER_FAILED)\n\n\n@dataclass\nclass Mismatch:\n \"\"\"One expected field that did not come back as promised.\"\"\"\n\n field: str\n expected: Any\n actual: Any\n node: Optional[str] = None\n note: str = \"\"\n\n\n@dataclass\nclass Escalation:\n \"\"\"A node that handed its case to a human instead of answering it.\n\n `kind` is which signal did it: `\"unsure\"` for the confidence gate, `\"failed\"` for a\n node that ran out of retry ladder and took `on_fail`. Both end the same way — a\n person finishes the case — but an operator fixes them differently, so the report\n keeps them apart.\n \"\"\"\n\n node: str\n kind: str\n reason: str = \"\"\n\n\n@dataclass\nclass CaseResult:\n \"\"\"One evalset case, run.\"\"\"\n\n name: str\n passed: bool\n input: Dict[str, Any]\n expected: Dict[str, Any]\n actual: Dict[str, Any] = field(default_factory=dict)\n mismatches: List[Mismatch] = field(default_factory=list)\n node: Optional[str] = None\n error: Optional[str] = None\n run_id: Optional[str] = None\n escalations: List[Escalation] = field(default_factory=list)\n # Defaulting to `failed` is not pessimism, it is the value the early returns want: a\n # case whose run raised never reaches the line that classifies it, and a run that did\n # not finish is exactly what this tier means. Nothing may be counted as automated\n # without a completed run to say so.\n tier: str = TIER_FAILED\n\n @property\n def escalated_by(self):\n \"\"\"The node that escalated this case — the earliest one the walk reached.\"\"\"\n return self.escalations[0].node if self.escalations else None\n\n\n@dataclass\nclass Report:\n \"\"\"The score, plus enough detail to act on it.\"\"\"\n\n pack: str\n cases: List[CaseResult] = field(default_factory=list)\n by_node: Dict[str, int] = field(default_factory=dict)\n\n @property\n def total(self):\n return len(self.cases)\n\n @property\n def passed(self):\n return sum(1 for case in self.cases if case.passed)\n\n @property\n def failed(self):\n return self.total - self.passed\n\n @property\n def passed_all(self):\n return self.failed == 0 and self.total > 0\n\n # ------------------------------------------------------------------ the tier split\n #\n # Derived from the cases rather than tallied alongside them: there is then one place\n # a tier can be decided (`_run_case`), and a report assembled by hand — a subset\n # rerun, a report rebuilt from JSON — reports the same numbers as one `evaluate`\n # produced.\n\n @property\n def tier_counts(self):\n \"\"\"How many cases landed in each tier. Always all three keys.\n\n A missing key reads as \"not measured\", and zero escalations is a result worth\n printing, not a gap.\n \"\"\"\n counts = OrderedDict((tier, 0) for tier in TIERS)\n for case in self.cases:\n counts[case.tier] = counts.get(case.tier, 0) + 1\n return counts\n\n @property\n def auto_cases(self):\n \"\"\"The cases the pack answered on its own — the only ones it may claim.\"\"\"\n return [case for case in self.cases if case.tier == TIER_AUTO]\n\n @property\n def auto_passed(self):\n return sum(1 for case in self.auto_cases if case.passed)\n\n @property\n def auto_accuracy(self):\n \"\"\"Correctness inside the auto bucket, as a fraction — the number that matters.\n\n `None` when nothing was automated, rather than 0.0 or 1.0: a rate over an empty\n bucket is not a low score, it is an absent one, and either digit would be a claim\n nobody measured.\n\n Escalated cases are deliberately not scored here even when they pass. A `rescued`\n case passing means the pack routed it as promised, not that it answered it — the\n human on the other end of that edge is the one who answers it.\n \"\"\"\n cases = self.auto_cases\n if not cases:\n return None\n return sum(1 for case in cases if case.passed) / float(len(cases))\n\n @property\n def automation_rate(self):\n \"\"\"The share of cases that went end to end with nobody's help. `None` if empty.\"\"\"\n return self._rate(TIER_AUTO)\n\n @property\n def escalation_rate(self):\n return self._rate(TIER_ESCALATED)\n\n @property\n def failure_rate(self):\n return self._rate(TIER_FAILED)\n\n def _rate(self, tier):\n if not self.cases:\n return None\n return self.tier_counts[tier] / float(len(self.cases))\n\n @property\n def escalated_by(self):\n \"\"\"Which node handed each escalated case over, tallied.\n\n This is the line an operator acts on: it names where to put the next `assert`, or\n which node's prompt is costing the automation rate.\n \"\"\"\n return self._tally(\n TIER_ESCALATED, lambda case: case.escalated_by or UNKNOWN_NODE\n )\n\n @property\n def failed_by(self):\n \"\"\"Which node the runs that could not finish died on.\n\n Distinct from `by_node`, which tallies *wrong answers* per node. A node here has\n no route out — it needs an `on_fail` (or an `on_unsure`) before this pack ships.\n \"\"\"\n return self._tally(TIER_FAILED, lambda case: case.node or UNKNOWN_NODE)\n\n def _tally(self, tier, name_of):\n counts = OrderedDict()\n for case in self.cases:\n if case.tier != tier:\n continue\n node = name_of(case)\n counts[node] = counts.get(node, 0) + 1\n return counts\n\n def summary(self):\n \"\"\"A short human report — what the CLI prints.\"\"\"\n lines = [\"%s: %d/%d cases passed\" % (self.pack, self.passed, self.total)]\n for case in self.cases:\n if case.passed:\n continue\n lines.append(\" FAIL %s [%s]\" % (case.name, case.node or UNKNOWN_NODE))\n if case.error:\n lines.append(\" error: %s\" % case.error)\n for mismatch in case.mismatches:\n lines.append(\n \" %s: expected %r, got %s\"\n % (\n mismatch.field,\n mismatch.expected,\n mismatch.note or repr(mismatch.actual),\n )\n )\n if self.by_node:\n lines.append(\n \" failures by node: %s\"\n % \", \".join(\"%s=%d\" % item for item in sorted(self.by_node.items()))\n )\n return \"\\n\".join(lines)\n\n def tier_summary(self):\n \"\"\"The automation rate, as three lines, printed by `stepmold eval --tiers`.\n\n Separate from `summary()` on purpose. `summary()` is what every existing script\n and transcript already parses, and it does not change; this is an operator asking\n one more question of the same report.\n \"\"\"\n if not self.cases:\n return \"%s: no cases\" % self.pack\n counts = self.tier_counts\n return \"\\n\".join([\n \"%s: %d case%s — %d auto, %d escalated, %d failed\"\n % (self.pack, self.total, \"\" if self.total == 1 else \"s\",\n counts[TIER_AUTO], counts[TIER_ESCALATED], counts[TIER_FAILED]),\n \" auto %s %s\" % (_percent(self.automation_rate), self._accuracy()),\n \" escalated %s%s\" % (_percent(self.escalation_rate),\n _blamed(self.escalated_by)),\n \" failed %s%s\" % (_percent(self.failure_rate), _blamed(self.failed_by)),\n ])\n\n def _accuracy(self):\n \"\"\"The auto bucket's own score, spelled out so it cannot be read as the total.\"\"\"\n accuracy = self.auto_accuracy\n if accuracy is None:\n return \"accuracy n/a — no case ran without escalating\"\n return \"accuracy %s (%d/%d correct)\" % (\n _percent(accuracy).strip(), self.auto_passed, len(self.auto_cases)\n )\n\n\ndef evaluate(pack, model, cases=None, tools=None):\n \"\"\"Run every evalset case through `pack` and score it.\n\n `model` is either a `Model` or a zero-argument factory returning one — a factory\n gives each case a fresh model, which is how an ordered `FakeModel` script stays\n readable across a dozen cases.\n\n `tools` is the host's `ToolRegistry` (see `stepmold.tools`), for a pack whose graph has\n `tool` nodes. It is handed to the walker only when it was given, so a pack with no\n tools — and a runtime whose walker predates them — scores exactly as it did before.\n \"\"\"\n cases = list(pack.evalset if cases is None else cases)\n if not cases:\n raise ValueError(\n \"pack %r has no evalset cases to run — an empty evalset is not a pass\"\n % pack.name\n )\n\n report = Report(pack=pack.name)\n counts = OrderedDict()\n for index, case in enumerate(cases, start=1):\n result = _run_case(pack, model, case, index, tools)\n report.cases.append(result)\n if not result.passed:\n node = result.node or UNKNOWN_NODE\n counts[node] = counts.get(node, 0) + 1\n report.by_node = dict(counts)\n return report\n\n\ndef _run_case(pack, model, case, index, tools=None):\n name = case.name or \"case %d\" % index\n result = CaseResult(\n name=name, passed=False, input=dict(case.input), expected=dict(case.expect)\n )\n trace = _Trace(pack.entry)\n # Passed through only when there is something to pass. A walker that takes no `tools`\n # keyword must still run every pack that needs none, which is all of them today.\n extra = {\"tools\": tools} if tools is not None else {}\n try:\n run_result = run(pack, _model_for(model), dict(case.input), store=trace, **extra)\n except NodeFailed as exc:\n result.node, result.error = exc.node, str(exc)\n return result\n except Exception as exc: # a backend that falls over fails its case, not the suite\n result.node = trace.pending\n result.error = \"%s: %s\" % (type(exc).__name__, exc)\n return result\n\n result.run_id = run_result.run_id\n result.actual = dict(run_result.output)\n\n # The run finished, so this case is the pack's to claim or to hand over. Conservative\n # on purpose: `auto` requires that nothing in the run hesitated. An unsure node the\n # pack chose not to route still ran unsupervised — but the auto bucket is a promise\n # about answers nobody checked, and an answer the node itself would not stand behind\n # does not belong in it. Anything short of certain leaves the bucket.\n result.escalations = _escalations(run_result)\n result.tier = TIER_ESCALATED if result.escalations else TIER_AUTO\n result.mismatches = _compare(case.expect, run_result)\n result.mismatches.extend(_compare_ending(case, run_result))\n diverted = run_result.failures[0] if run_result.failures else None\n\n # `rescued` says this case is meant to burn a ladder and take an on_fail edge. It is\n # checked in both directions: an undeclared failure still fails the case, and a case\n # that claims a rescue but sailed through is not testing what it says it tests — so\n # it cannot be used to silence a real failure.\n if case.rescued and diverted is None:\n result.node = run_result.end_node\n result.error = (\n \"case declares rescued: true but the run completed with no failure — \"\n \"either the rescue path is not being exercised, or the flag is wrong\"\n )\n return result\n unexpected = diverted is not None and not case.rescued\n\n if not result.mismatches and not unexpected:\n result.passed = True\n if diverted is not None:\n # Passing, but say which node needed rescuing: an operator reading a green\n # report should still see where the ladder was spent.\n result.node = diverted.node\n return result\n if unexpected:\n # A node that burned its ladder and was diverted is the cause, even when the\n # projected output happens to look right.\n result.node = diverted.node\n result.error = diverted.reason\n else:\n result.node = _earliest_node(result.mismatches, run_result.path)\n return result\n\n\ndef _compare_ending(case, run_result):\n \"\"\"The branch a run took, as part of the contract.\n\n `expect` compares fields, and the ending is not a field — so a pack whose branches\n project the same shape could have its routing inverted and still score full marks.\n Naming the ending is what closes that.\n \"\"\"\n if case.end is None:\n return []\n if run_result.end_node == case.end:\n return []\n return [\n Mismatch(\n field=\"\",\n expected=case.end,\n actual=run_result.end_node,\n node=run_result.path[-2] if len(run_result.path) > 1 else None,\n # No note: the renderer substitutes a note FOR the actual value, and here the\n # actual ending is the whole point. \"\" already says what the field is.\n )\n ]\n\n\ndef _earliest_node(mismatches, path):\n \"\"\"Blame the node the walker reached first, not the field listed first.\n\n `expect` is a JSON object typed by hand, so its key order carries no meaning; the\n run's visit order does. When two nodes both produced a wrong field, the earlier one\n is the one to fix — the later node consumed its mistake. A node can be visited more\n than once in a loop, so its first visit is what ranks it.\n \"\"\"\n rank = _rank(path)\n\n best = None\n for mismatch in mismatches:\n if mismatch.node is None:\n continue # an expectation on an input field: nobody wrote it\n if mismatch.node not in rank:\n continue # provenance from outside this run's path; cannot be ordered\n if best is None or rank[mismatch.node] < rank[best]:\n best = mismatch.node\n if best is not None:\n return best\n return mismatches[0].node\n\n\ndef _rank(path):\n \"\"\"Each node's position at its *first* visit — the order blame is decided in.\n\n Shared by the two things that have to agree about which node comes first: the wrong\n field a case is blamed on, and the node an escalation is attributed to. A node\n entered twice in a loop is ranked by the first time the walk reached it.\n \"\"\"\n rank = {}\n for position, node in enumerate(path):\n rank.setdefault(node, position)\n return rank\n\n\ndef _escalations(run_result):\n \"\"\"Everything in this run that put a human in the loop, earliest node first.\n\n Two signals, produced at two layers. `failures` is the walker's own record of a node\n that ran out of retry ladder and was diverted by `on_fail` — the walker only records\n one when there was somewhere to divert to, so a failure here always means the case\n was routed rather than dropped. `unsure` is the confidence gate's record of a node\n that produced an answer it could not stand behind.\n \"\"\"\n records = [\n Escalation(node=failure.node, kind=\"failed\",\n reason=getattr(failure, \"reason\", \"\") or \"\")\n for failure in getattr(run_result, \"failures\", None) or ()\n ]\n records.extend(_unsure(run_result))\n # The same rule that blames a wrong field: the walk's order decides, not the order\n # two separate lists happen to be in. The sort is stable, so a node's own records\n # keep the order the run recorded them in.\n rank = _rank(getattr(run_result, \"path\", None) or [])\n records.sort(key=lambda record: rank.get(record.node, len(rank)))\n return records\n\n\ndef _unsure(run_result):\n \"\"\"This run's confidence-gate records, if the runtime it ran on has a gate.\n\n Read with `getattr` and shaped loosely on purpose. The gate lives in the walker; a\n `RunResult` replayed from a checkpoint written before it existed has no such field,\n and a pack that sets no tiers leaves it empty. None of those may stop a report being\n scored. All eval needs from a record is the node's name, so a dataclass, a mapping\n and a bare node name are all accepted — whatever the walker publishes is readable.\n\n A record naming no node is still an escalation: it is counted, and attributed to\n ``. Losing the attribution is a smaller error than quietly counting the case\n as automated.\n \"\"\"\n for record in getattr(run_result, \"unsure\", None) or ():\n yield Escalation(\n node=str(_record_field(record, \"node\") or UNKNOWN_NODE),\n kind=\"unsure\",\n reason=str(_record_field(record, \"reason\") or \"\"),\n )\n\n\ndef _record_field(record, name):\n if isinstance(record, str):\n return record if name == \"node\" else \"\"\n if isinstance(record, dict):\n return record.get(name)\n return getattr(record, name, None)\n\n\ndef _compare(expect, run_result):\n \"\"\"Exact match on the declared fields, each blamed on whoever wrote it.\"\"\"\n mismatches = []\n for name, expected in expect.items():\n actual = _actual(name, run_result)\n if actual is _MISSING:\n mismatches.append(\n Mismatch(\n field=name,\n expected=expected,\n actual=None,\n node=run_result.provenance.get(name),\n note=\"missing from output\",\n )\n )\n elif actual != expected:\n mismatches.append(\n Mismatch(\n field=name,\n expected=expected,\n actual=actual,\n node=run_result.provenance.get(name),\n )\n )\n return mismatches\n\n\ndef _actual(name, run_result):\n \"\"\"Look in the projected output first, then the full state.\n\n An `end` node that projects a subset should not stop an evalset from asserting on an\n intermediate field — per-node expectations are exactly the signal we want.\n \"\"\"\n if name in run_result.output:\n return run_result.output[name]\n if name in run_result.state:\n return run_result.state[name]\n return _MISSING\n\n\ndef _percent(rate):\n \"\"\"A rate as a right-aligned percentage, so the three tier lines form a column.\"\"\"\n if rate is None:\n return \" n/a\"\n return \"%5.1f%%\" % (rate * 100.0)\n\n\ndef _blamed(counts):\n \"\"\"` at classify=2, confirm=1`, or nothing at all when the tier is empty.\n\n Sorted by how many cases each node cost, not alphabetically: this list exists to be\n read top-down by someone deciding where the next `assert` goes.\n \"\"\"\n if not counts:\n return \"\"\n ordered = sorted(counts.items(), key=lambda item: (-item[1], item[0]))\n return \" at %s\" % \", \".join(\"%s=%d\" % item for item in ordered)\n\n\ndef _model_for(model):\n if hasattr(model, \"generate\"):\n return model\n if callable(model):\n return model()\n raise TypeError(\n \"evaluate() needs a Model or a factory returning one, got %s\"\n % type(model).__name__\n )\n\n\nclass _Trace:\n \"\"\"A store that keeps only the last checkpoint, to blame the right node on a crash.\"\"\"\n\n def __init__(self, entry):\n self.pending = entry\n\n def save(self, **checkpoint):\n self.pending = checkpoint.get(\"next_node\")\n", "stepmold/expr.py": "\"\"\"The expression language `assert` nodes and node-level `assert:` are written in.\n\nThis exists because a pack is data: an assert has to travel inside `graph.yaml` as a\nstring, and a string that gets `eval()`-ed is a remote code execution hole in something\ndesigned to run untrusted, compiler-generated packs. So expressions are parsed with\n`ast.parse` and walked against a whitelist — anything not on the list is refused by name.\n\nThe language is deliberately boring: names from state, dotted lookup into mappings,\ncomparisons, `and`/`or`/`not`, `in`, arithmetic, indexing, literals, and a fixed set of\nhelper functions. No attribute access on non-mappings, no method calls, no lambdas, no\ncomprehensions, no assignment. If an assert needs more than this, it wants to be a\ndeterministic node in the graph, not a one-liner in YAML.\n\nThe other half of the contract is that *every* way an expression can fail arrives as\n`ExprError`. `verify._check_assert` catches `ExprError` and turns it into a `Rejected`,\nwhich the retry ladder and `on_fail` edges know how to route; anything else — a raw\n`TypeError` from a bad operand, a `RecursionError` from a deeply nested expression, a\n`MemoryError` from a huge repetition — escapes that handler and kills the whole run. So\nthe walker converts what it can and refuses, up front, what it cannot survive: nesting\npast `_MAX_DEPTH` and sequence repetition past `_MAX_REPEAT`.\n\nThere is a third rule, and it is about *what those errors say*. An assert exists to read\nthe candidate object, so every failure here happens with model-authored values in hand —\n`_check_assert` puts `str(exc)` straight into a `Rejected`, whose feedback is shown to\nthe model on the next rung. So `str(exc)` is built only from text the pack wrote (the\nexpression, a helper name, a type name); the offending values live on `exc.detail`, for\nlogs and for a caller that asks. See `_error`.\n\"\"\"\n\nimport ast\nimport operator\n\nfrom .errors import ExprError\n\n__all__ = [\"evaluate\", \"is_true\"]\n\n_LITERALS = {\"true\": True, \"false\": False, \"null\": None, \"none\": None}\n\n# How much of a value a *diagnostic* may show. A ticket is a megabyte often enough that\n# an unclipped repr is a real hazard, and nothing here needs more than a glimpse.\n_SHOW_LIMIT = 120\n\n# How deep a single expression may nest. `_eval` recurses once per AST level, so without\n# a ceiling `1+1+1+...` walks straight into CPython's own recursion limit and raises a\n# RecursionError the caller is not expecting. The ceiling is far above anything a\n# readable one-line assert reaches, and well under the interpreter's own.\n_MAX_DEPTH = 100\n\n# How long a sequence `*` may produce. `\"a\" * n * n` is the one operator here that can\n# amplify a small expression into gigabytes, and MemoryError is not an ExprError. The\n# limit is a refusal threshold, not a measurement: anything a sane assert compares\n# against is orders of magnitude below it.\n_MAX_REPEAT = 1_000_000\n\n_HELPERS = {\n \"len\": len,\n \"abs\": abs,\n \"min\": min,\n \"max\": max,\n \"sum\": sum,\n \"round\": round,\n \"sorted\": sorted,\n \"any\": any,\n \"all\": all,\n \"str\": str,\n \"int\": int,\n \"float\": float,\n \"bool\": bool,\n \"lower\": lambda value: str(value).lower(),\n \"upper\": lambda value: str(value).upper(),\n \"strip\": lambda value: str(value).strip(),\n \"startswith\": lambda value, prefix: str(value).startswith(prefix),\n \"endswith\": lambda value, suffix: str(value).endswith(suffix),\n \"contains\": lambda haystack, needle: needle in haystack,\n}\n\n_BINARY = {\n ast.Add: operator.add,\n ast.Sub: operator.sub,\n ast.Mult: operator.mul,\n ast.Div: operator.truediv,\n ast.FloorDiv: operator.floordiv,\n ast.Mod: operator.mod,\n}\n\n_COMPARE = {\n ast.Eq: operator.eq,\n ast.NotEq: operator.ne,\n ast.Lt: operator.lt,\n ast.LtE: operator.le,\n ast.Gt: operator.gt,\n ast.GtE: operator.ge,\n ast.In: lambda a, b: a in b,\n ast.NotIn: lambda a, b: a not in b,\n ast.Is: operator.is_,\n ast.IsNot: operator.is_not,\n}\n\n\ndef _error(safe, detail=None):\n \"\"\"An `ExprError` whose message is safe to put in front of the model.\n\n `verify._check_assert` turns `str(exc)` into the `Rejected` a retry prompt is built\n from, and an assert reads exactly the values that were just rejected — so a message\n quoting one would carry the rejected generation into the next prompt, which is the\n self-conditioning spiral stepmold is designed around (docs/ARCHITECTURE.md §3). `str(exc)` is\n therefore pack-authored text only; `exc.detail` keeps the whole story for the\n operator, because bytes in a log cannot condition anything.\n \"\"\"\n exc = ExprError(safe)\n exc.detail = safe if detail is None else detail\n return exc\n\n\ndef _show(value):\n \"\"\"A value, rendered for `detail` only — bounded, because the value is not ours.\"\"\"\n return _bound(repr(value))\n\n\ndef _why(exc):\n \"\"\"A builtin's own message, bounded: several of them quote the whole operand.\"\"\"\n return _bound(str(exc))\n\n\ndef _bound(text):\n text = \" \".join(text.split())\n return text if len(text) <= _SHOW_LIMIT else text[:_SHOW_LIMIT] + \"...\"\n\n\ndef evaluate(expression, state):\n \"\"\"Evaluate `expression` against `state`. Raises `ExprError` on anything unsafe.\"\"\"\n if not isinstance(expression, str) or not expression.strip():\n raise _error(\"expression is empty\")\n try:\n tree = ast.parse(expression.strip(), mode=\"eval\")\n except SyntaxError as exc:\n raise _error(\"could not parse expression %r (%s)\" % (expression, exc.msg))\n except RecursionError:\n # Which inputs exhaust the parser rather than the walker is a CPython detail that\n # moves between versions, so cover it here too rather than assume a version.\n raise _error(\"expression %r is nested too deeply to parse\" % expression)\n return _eval(tree.body, state, expression, 0)\n\n\ndef is_true(expression, state):\n \"\"\"Evaluate `expression` and coerce the result to a bool.\"\"\"\n return bool(evaluate(expression, state))\n\n\ndef _eval(node, state, source, depth):\n \"\"\"Walk one AST node. `depth` is how many levels of expression are already open.\"\"\"\n if depth > _MAX_DEPTH:\n raise _error(\n \"expression %r is nested more than %d levels deep, which stepmold refuses to \"\n \"evaluate\" % (source, _MAX_DEPTH)\n )\n inner = depth + 1\n if isinstance(node, ast.Constant):\n return node.value\n if isinstance(node, ast.Name):\n return _name(node.id, state)\n if isinstance(node, ast.Attribute):\n return _attribute(node, state, source)\n if isinstance(node, ast.Subscript):\n return _subscript(node, state, source, inner)\n if isinstance(node, ast.BoolOp):\n return _bool_op(node, state, source, inner)\n if isinstance(node, ast.UnaryOp):\n return _unary(node, state, source, inner)\n if isinstance(node, ast.BinOp):\n return _binary(node, state, source, inner)\n if isinstance(node, ast.Compare):\n return _compare(node, state, source, inner)\n if isinstance(node, ast.Call):\n return _call(node, state, source, inner)\n if isinstance(node, (ast.List, ast.Tuple, ast.Set)):\n return [_eval(item, state, source, inner) for item in node.elts]\n if isinstance(node, ast.Dict):\n return _dict(node, state, source, inner)\n if isinstance(node, ast.IfExp):\n if _eval(node.test, state, source, inner):\n return _eval(node.body, state, source, inner)\n return _eval(node.orelse, state, source, inner)\n raise _error(_refuse(node, source))\n\n\ndef _refuse(node, source):\n name = type(node).__name__\n if name in (\"ListComp\", \"SetComp\", \"DictComp\", \"GeneratorExp\"):\n name = \"Comprehension\"\n return \"%s is not allowed in a stepmold expression (in %r)\" % (name, source)\n\n\ndef _name(identifier, state):\n if identifier in _LITERALS:\n return _LITERALS[identifier]\n if identifier.startswith(\"__\"):\n raise _error(\"name %r is not allowed in a stepmold expression\" % identifier)\n if identifier in state:\n return state[identifier]\n if identifier in _HELPERS:\n return _HELPERS[identifier]\n # The key list is diagnostics only: in merge mode the candidate's own property names\n # *are* state keys, so listing them to the model would echo the rejected output back.\n raise _error(\n \"expression references %r, which is not in state\" % identifier,\n detail=\"expression references %r, which is not in state (state has: %s)\"\n % (identifier, _bound(\", \".join(sorted(state))) or \"nothing\"),\n )\n\n\ndef _path(node):\n \"\"\"Flatten `a.b.c` into \"a.b.c\", or return None if it is not a plain path.\"\"\"\n parts = []\n while isinstance(node, ast.Attribute):\n parts.append(node.attr)\n node = node.value\n if not isinstance(node, ast.Name):\n return None\n parts.append(node.id)\n return \".\".join(reversed(parts))\n\n\ndef _attribute(node, state, source):\n path = _path(node)\n if path is None:\n raise _error(_refuse(node, source))\n if path.startswith(\"__\") or \".__\" in path:\n raise _error(\"name %r is not allowed in a stepmold expression\" % path)\n parts = path.split(\".\")\n current = _name(parts[0], state)\n for part in parts[1:]:\n if not isinstance(current, dict) or part not in current:\n raise _error(\n \"expression references %r, which is not a mapping key in state\" % path\n )\n current = current[part]\n return current\n\n\ndef _subscript(node, state, source, depth):\n container = _eval(node.value, state, source, depth)\n key = _eval(node.slice, state, source, depth)\n try:\n return container[key]\n except (KeyError, IndexError, TypeError) as exc:\n # The key is routinely a value out of the candidate — `queues[category]` is the\n # shape every routing assert takes — so it belongs in `detail`, never in `str`.\n raise _error(\n \"cannot index by the value %r asks for\" % source,\n detail=\"cannot index %s in %r (%s)\" % (_show(key), source, _why(exc)),\n )\n\n\ndef _dict(node, state, source, depth):\n result = {}\n for key_node, value_node in zip(node.keys, node.values):\n if key_node is None:\n # `{**other}`. ast puts a None key there; refuse it by name rather than let\n # the walker report the placeholder's type.\n raise _error(\n \"** unpacking is not allowed in a stepmold expression (in %r)\" % source\n )\n key = _eval(key_node, state, source, depth)\n value = _eval(value_node, state, source, depth)\n try:\n result[key] = value\n except TypeError as exc:\n raise _error(\n \"cannot use that value as a dict key in %r\" % source,\n detail=\"cannot use %s as a dict key in %r (%s)\"\n % (_show(key), source, _why(exc)),\n )\n return result\n\n\ndef _bool_op(node, state, source, depth):\n \"\"\"`and` / `or`, short-circuiting exactly like Python.\n\n Evaluating every operand up front would break the one idiom pack authors reach for\n most — `x is not null and len(x) > 2` — by running the guarded half against the\n value the guard exists to exclude. So stop at the first operand that decides the\n result and never look at the rest.\n \"\"\"\n wants_truthy = isinstance(node.op, ast.And)\n result = None\n for value_node in node.values:\n result = _eval(value_node, state, source, depth)\n if bool(result) is not wants_truthy:\n return result\n # Every operand agreed; Python yields the last one, whatever its type.\n return result\n\n\ndef _unary(node, state, source, depth):\n value = _eval(node.operand, state, source, depth)\n if isinstance(node.op, ast.Not):\n return not value\n if not isinstance(node.op, (ast.USub, ast.UAdd)):\n raise _error(_refuse(node.op, source))\n try:\n return -value if isinstance(node.op, ast.USub) else +value\n except TypeError as exc:\n # `-\"text\"`: a mis-written assert, and the caller only handles ExprError.\n raise _error(\n \"cannot evaluate %r against this value\" % source,\n detail=\"cannot evaluate %r (%s)\" % (source, _why(exc)),\n )\n\n\ndef _binary(node, state, source, depth):\n handler = _BINARY.get(type(node.op))\n if handler is None:\n raise _error(_refuse(node.op, source))\n left = _eval(node.left, state, source, depth)\n right = _eval(node.right, state, source, depth)\n if isinstance(node.op, ast.Mult):\n _check_repeat(left, right, source)\n try:\n return handler(left, right)\n except (TypeError, ZeroDivisionError) as exc:\n raise _error(\n \"cannot evaluate %r against these values\" % source,\n detail=\"cannot evaluate %r (%s)\" % (source, _why(exc)),\n )\n\n\ndef _check_repeat(left, right, source):\n \"\"\"Refuse `sequence * n` before it allocates, if the result would be huge.\n\n Sequence repetition is the only whitelisted operator that turns a short expression\n into an arbitrarily large object, and the MemoryError it would raise is not an\n ExprError, so it would escape the caller's handler instead of failing the node.\n \"\"\"\n for sequence, count in ((left, right), (right, left)):\n if not isinstance(sequence, (str, bytes, list, tuple)):\n continue\n if not isinstance(count, int):\n continue\n if len(sequence) * count > _MAX_REPEAT:\n raise _error(\n \"repetition in %r would build a sequence that is too large (limit %d)\"\n % (source, _MAX_REPEAT),\n detail=\"repetition in %r would build a sequence of %d items, which is \"\n \"too large (limit %d)\"\n % (source, len(sequence) * count, _MAX_REPEAT),\n )\n\n\ndef _compare(node, state, source, depth):\n left = _eval(node.left, state, source, depth)\n for op, comparator in zip(node.ops, node.comparators):\n handler = _COMPARE.get(type(op))\n if handler is None:\n raise _error(_refuse(op, source))\n right = _eval(comparator, state, source, depth)\n try:\n if not handler(left, right):\n return False\n except TypeError as exc:\n raise _error(\n \"cannot compare these values in %r\" % source,\n detail=\"cannot compare in %r (%s)\" % (source, _why(exc)),\n )\n left = right\n return True\n\n\ndef _call(node, state, source, depth):\n if not isinstance(node.func, ast.Name) or node.func.id not in _HELPERS:\n called = getattr(node.func, \"id\", None) or _path(node.func) or \"\"\n raise _error(\n \"%r is not a stepmold expression helper (allowed: %s)\"\n % (called, \", \".join(sorted(_HELPERS)))\n )\n if node.keywords:\n raise _error(\"stepmold expression helpers take positional arguments only\")\n arguments = [_eval(argument, state, source, depth) for argument in node.args]\n try:\n return _HELPERS[node.func.id](*arguments)\n except Exception as exc:\n # `int(\"\")` puts the whole argument in the ValueError it raises, so the\n # builtin's own message is exactly the thing that must not reach a prompt.\n raise _error(\n \"helper %s() failed in %r\" % (node.func.id, source),\n detail=\"helper %s() failed in %r (%s)\"\n % (node.func.id, source, _why(exc)),\n )\n", "stepmold/grammar.py": "\"\"\"The node contract: a JSON Schema subset, validated by hand.\n\nTwo jobs, and they are deliberately separate:\n\n* `schema_to_grammar` turns a node's schema into the backend-neutral struct that gets\n handed to `Model.generate`. It is a pass-through today — real backends (T11) translate\n it into `response_format` / `grammar` on the way out. It also *checks* the schema, so a\n typo in a pack fails at `stepmold validate` time rather than at 3am in production.\n* `validate_against` is the runtime half of verify-before-commit (docs/ARCHITECTURE.md §3): even\n with a constrained decoder, stepmold never trusts output it has not checked itself. It also\n refuses what `json.loads` accepts but JSON does not have — NaN, Infinity, and nesting\n deep enough to exhaust the interpreter — because every one of those is fatal *after*\n the commit, where no retry and no `on_fail` edge can reach it.\n\nThe supported subset is `type`, `properties`, `required`, `enum`, `items`, and\n`additionalProperties: false` — enough to express every node contract in the example\npacks, small enough to read in one sitting. Anything outside it raises `SchemaError`\nrather than being quietly ignored, because a silently-ignored constraint is a\nconstraint you think you have and don't.\n\"\"\"\n\nimport copy\nimport math\n\n__all__ = [\n \"SchemaError\",\n \"ValidationError\",\n \"schema_to_grammar\",\n \"validate_against\",\n]\n\nGRAMMAR_KIND = \"json_schema\"\n\n# How deep a candidate value may nest before stepmold refuses it. `json.loads` will happily\n# build a structure thousands of levels deep, and everything downstream of the commit\n# walks it recursively — `state._check`, `json.dumps`, the checkpoint — so a deep enough\n# object dies with a `RecursionError`, which is not a `StepmoldError`, is not caught by the\n# CLI, and does not take the node's `on_fail` edge. The ceiling is far above any node\n# contract a pack expresses and far below the interpreter's own limit.\n_MAX_DEPTH = 64\n\n_TYPES = {\n \"object\": dict,\n \"array\": list,\n \"string\": str,\n \"integer\": int,\n \"number\": (int, float),\n \"boolean\": bool,\n \"null\": type(None),\n}\n_KEYWORDS = {\n \"type\", \"properties\", \"required\", \"enum\", \"items\", \"additionalProperties\",\n \"description\", \"title\",\n}\n\n\nclass SchemaError(ValueError):\n \"\"\"The schema itself is not something stepmold can enforce.\"\"\"\n\n\nclass ValidationError(ValueError):\n \"\"\"An object does not satisfy its node's schema.\n\n `path` is the dotted location of the offending value (`\"\"` for the root), so\n callers can attribute a failure without parsing the message.\n \"\"\"\n\n def __init__(self, path, message, safe=None, safe_path=None):\n self.path = path\n self.message = message\n # `safe` is the model-facing half of the message. It may describe the constraint\n # (which comes from the pack's own schema) but never the offending value (which\n # came from the model). Quoting a rejected value back into a retry prompt is the\n # self-conditioning spiral stepmold/verify.py exists to prevent.\n self.safe = message if safe is None else safe\n # The *location* is model-authored text too, whenever the last segment is a key\n # the model invented: `additionalProperties: false` names the offending property,\n # and so does any check that walks a value the schema never declared. Those\n # errors pass their own safe location — the nearest one built from the pack's own\n # names — instead of letting `path` carry a smuggled instruction into a prompt.\n self.safe_path = path if safe_path is None else safe_path\n self.safe_text = \"%s: %s\" % (_clip(self.safe_path) or \"\", self.safe)\n ValueError.__init__(self, \"%s: %s\" % (_clip(path) or \"\", message))\n\n\ndef schema_to_grammar(schema):\n \"\"\"Wrap a validated schema in the struct a backend knows how to translate.\"\"\"\n check_schema(schema)\n return {\"kind\": GRAMMAR_KIND, \"schema\": copy.deepcopy(schema)}\n\n\ndef check_schema(schema, path=\"\"):\n \"\"\"Raise `SchemaError` unless `schema` uses only the supported subset.\"\"\"\n if not isinstance(schema, dict):\n raise SchemaError(\n \"%s: schema must be a mapping, got %s\"\n % (path or \"\", type(schema).__name__)\n )\n unknown = set(schema) - _KEYWORDS\n if unknown:\n raise SchemaError(\n \"%s: unsupported schema keyword(s): %s\"\n % (path or \"\", \", \".join(sorted(unknown)))\n )\n for name in _declared_types(schema, path):\n if name not in _TYPES:\n raise SchemaError(\"%s: unknown type %r\" % (path or \"\", name))\n\n properties = schema.get(\"properties\")\n if properties is not None:\n if not isinstance(properties, dict):\n raise SchemaError(\"%s: 'properties' must be a mapping\" % (path or \"\"))\n for key, sub in properties.items():\n check_schema(sub, _join(path, key))\n\n required = schema.get(\"required\")\n if required is not None:\n if not isinstance(required, list) or not all(\n isinstance(item, str) for item in required\n ):\n raise SchemaError(\n \"%s: 'required' must be a list of property names\" % (path or \"\")\n )\n\n enum = schema.get(\"enum\")\n if enum is not None and (not isinstance(enum, list) or not enum):\n raise SchemaError(\"%s: 'enum' must be a non-empty list\" % (path or \"\"))\n\n items = schema.get(\"items\")\n if items is not None:\n check_schema(items, path + \"[]\")\n\n extra = schema.get(\"additionalProperties\")\n if extra is not None and not isinstance(extra, bool):\n raise SchemaError(\n \"%s: 'additionalProperties' must be true or false\" % (path or \"\")\n )\n\n\ndef validate_against(schema, obj, path=\"\"):\n \"\"\"Return None if `obj` satisfies `schema`; raise `ValidationError` otherwise.\"\"\"\n # Shape before schema. `json.loads` hands back two things that are not JSON — NaN /\n # Infinity, and nesting deep enough to exhaust the interpreter — and both are lethal\n # *after* the commit, where no retry and no `on_fail` edge can reach them. Checking\n # them where the value first enters makes them ordinary rejections.\n _check_shape(obj, path, 0)\n return _validate(schema, obj, path)\n\n\ndef _check_shape(value, path, depth):\n \"\"\"Refuse a value that is JSON-shaped but not JSON, whatever the schema says.\n\n Walks the whole candidate, not just the parts the schema declares: the schema a\n compiler emits for a free-form field is `{\"type\": \"object\"}`, which pins nothing, and\n a NaN or a 3000-deep array under such a field is exactly the case that gets past\n validation and dies at checkpoint time.\n \"\"\"\n if depth > _MAX_DEPTH:\n raise ValidationError(\n path,\n \"value nests more than %d levels deep, which stepmold refuses to commit\"\n % _MAX_DEPTH,\n safe=\"value nests more than %d levels deep\" % _MAX_DEPTH,\n # Every segment past the root here may be a key the model invented.\n safe_path=\"\",\n )\n if isinstance(value, float) and not math.isfinite(value):\n raise ValidationError(\n path,\n \"%s is not a JSON number — strict JSON has no NaN or Infinity\" % _show(value),\n safe=\"value is not a JSON number — JSON has no NaN or Infinity\",\n safe_path=\"\",\n )\n if isinstance(value, dict):\n for key, item in value.items():\n _check_shape(item, _join(path, key), depth + 1)\n elif isinstance(value, list):\n for index, item in enumerate(value):\n _check_shape(item, \"%s[%d]\" % (path, index), depth + 1)\n\n\ndef _validate(schema, obj, path):\n if not isinstance(schema, dict):\n raise SchemaError(\"%s: schema must be a mapping\" % (path or \"\"))\n\n declared = _declared_types(schema, path)\n if declared and not any(_is_type(obj, name) for name in declared):\n raise ValidationError(\n path,\n \"expected %s, got %s\"\n % (\" or \".join(declared), type(obj).__name__),\n )\n\n if \"enum\" in schema and obj not in schema[\"enum\"]:\n choices = \", \".join(repr(choice) for choice in schema[\"enum\"])\n raise ValidationError(\n path,\n \"%s is not one of %s\" % (_show(obj), choices),\n safe=\"value is not one of %s\" % choices,\n )\n\n if isinstance(obj, dict):\n _validate_object(schema, obj, path)\n elif isinstance(obj, list) and schema.get(\"items\") is not None:\n for index, item in enumerate(obj):\n _validate(schema[\"items\"], item, \"%s[%d]\" % (path, index))\n return None\n\n\ndef _validate_object(schema, obj, path):\n properties = schema.get(\"properties\") or {}\n for name in schema.get(\"required\") or []:\n if name not in obj:\n raise ValidationError(_join(path, name), \"required property is missing\")\n if schema.get(\"additionalProperties\") is False:\n for name in obj:\n if name not in properties:\n allowed = \", \".join(sorted(properties)) or \"none\"\n raise ValidationError(\n _join(path, name),\n \"unexpected property (schema sets additionalProperties: false)\",\n safe=\"unexpected property; the schema declares only: %s\" % allowed,\n # `name` came from the model, so the model-facing half locates the\n # failure at the object instead of quoting the invented key.\n safe_path=path,\n )\n for name, subschema in properties.items():\n if name in obj:\n _validate(subschema, obj[name], _join(path, name))\n\n\ndef _declared_types(schema, path):\n declared = schema.get(\"type\")\n if declared is None:\n return []\n if isinstance(declared, str):\n return [declared]\n if isinstance(declared, list) and declared and all(\n isinstance(name, str) for name in declared\n ):\n return list(declared)\n raise SchemaError(\n \"%s: 'type' must be a name or a list of names\" % (path or \"\")\n )\n\n\ndef _is_type(obj, name):\n expected = _TYPES.get(name)\n if expected is None:\n raise SchemaError(\"unknown type %r\" % name)\n if name in (\"integer\", \"number\") and isinstance(obj, bool):\n return False # JSON says booleans are not numbers; Python disagrees\n return isinstance(obj, expected)\n\n\ndef _join(path, name):\n return \"%s.%s\" % (path, name) if path else name\n\n\ndef _show(value):\n \"\"\"A value, rendered for a *diagnostic* — bounded, because the value is not ours.\"\"\"\n return _clip(repr(value))\n\n\ndef _clip(text, limit=120):\n \"\"\"Keep a message bounded. A megabyte of ticket must not become a megabyte of log.\"\"\"\n text = \" \".join(str(text).split())\n return text if len(text) <= limit else text[:limit] + \"...\"\n", "stepmold/graph.py": "\"\"\"The graph walker — stepmold's runtime.\n\nThis is the whole \"the small model never plans\" idea in one loop (docs/ARCHITECTURE.md §3): the\nwalker decides what happens next, the model only ever fills one node's slot. Nothing here\nasks a model where to go; edges are data.\n\n state = inputs\n node = entry\n loop: execute node -> commit its output to state -> pick the next edge\n\nFour node types. `generate` renders a prompt from state, generates under the node's\ngrammar, and commits the result — but only once `stepmold.verify` has accepted it, so a\nrejected output never lands here. `tool` calls one of the actions the host registered\n(`stepmold.tools`) and commits what it returns by exactly the same rules — no prompt, no\ngrammar and no retry ladder, because a tool is deterministic: same state in, same call\nout, and a re-sample of a function is just the same call again. `assert` evaluates a\ndeterministic expression and either continues or diverts to `on_fail`. `end` stops and\nreturns.\n\nA tool call is the one thing in a run that retrying cannot undo, so the walker writes it\ndown before it commits it. The moment a call returns, the node, the arguments it was\nhanded and what it gave back go into the checkpoint with the walk still standing on the\nnode; only once the node has been walked out of is the record cleared. A resumed run that\nlands back on that node finds the record and replays it instead of calling. That is what\nmakes \"the email is sent exactly once\" true across a crash rather than merely likely —\ncommitted state cannot say it, because state records what a call *returned* and never\nthat it *happened*. A tool declared `idempotent=True` skips the bookkeeping and is simply\ncalled again, which is what declaring it means.\n\nFailure routing is uniform, and that is deliberate: everything that stops a node\nproducing a verified output — a spent retry ladder, a prompt that cannot be rendered, an\nexpression that cannot be evaluated, a tool that raised or broke its own contract — takes\nthe node's declared `on_fail` edge, and only escapes as an exception when the node\ndeclares none. A database being down therefore takes the same path a model failing does.\nA node's failure edge is a promise in the pack; the walker keeps it whatever the node\nfailed on.\n\nOne failure is routed apart from the rest, because it is not the same claim. `Unsure` —\n`stepmold.verify`'s outcome for a node whose independent samples disagreed — means the model\nanswered without the engine being able to believe it, which is a different thing from\nthe model not answering at all. A node may declare `on_unsure:` to send it somewhere a\nperson is waiting; if it does not, it falls back to `on_fail`, and with neither the run\naborts. Confidence is routed before it is acted on, which is why this landed before tool\nnodes did rather than after.\n\nThe walk is also where a run's story gets written down (`stepmold.log`): `run.start`,\n`node.ok` per node with the generations it spent and the milliseconds it took,\n`edge.on_fail` when a node is diverted, `run.end` with the whole run's totals, and\n`run.error` when it stops short. Names and counts only — the caller's data is reported as\na size and a digest, and a node failure carries the model-safe half of its reason (see\n`_safe_reason`), with the full detail at DEBUG.\n\"\"\"\n\nimport inspect\nimport json\nimport time\nimport uuid\nfrom dataclasses import asdict, dataclass, field\nfrom functools import lru_cache\nfrom typing import Any, Dict, List, Optional\n\nfrom .errors import (\n AssertFailed,\n DanglingEdge,\n DeadEnd,\n ExprError,\n MaxStepsExceeded,\n MissingVariable,\n NodeFailed,\n RunError,\n RunIdInUse,\n)\nfrom .expr import is_true\nfrom .log import DEBUG, ERROR, INFO, WARNING, digest, event, get_logger, size_of\nfrom .tools import ToolContract, ToolError, ToolFailed\nfrom .verify import run_node\n\ntry:\n from .verify import Unsure\nexcept ImportError: # pragma: no cover - until stepmold.verify grows the signal\n class Unsure(NodeFailed):\n \"\"\"Independent samples of one node disagreed, so no answer is trustworthy.\n\n `stepmold.verify` owns this outcome; the walker owns where it goes. Until the two land\n together this stands in for it, so `on_unsure` routing is real and tested rather\n than written against a name and hoped for. It subclasses `NodeFailed` because a\n node nobody can believe did not produce a verified output either — a walker that\n somehow met one without knowing about `on_unsure` would still take `on_fail`,\n which is the conservative half of the rule.\n \"\"\"\n\n\n__all__ = [\"Failure\", \"RunResult\", \"StateCollision\", \"ToolsNotAvailable\",\n \"ToolReplayMismatch\", \"Unsure\", \"replay\", \"run\"]\n\n_log = get_logger(\"graph\")\n\n\nclass StateCollision(RunError):\n \"\"\"A node's commit would have overwritten one of the run's inputs.\n\n Merge-mode commit (a node with no `output:` key) drops its fields straight into run\n state, and run state is what every later prompt and every edge condition reads. Two\n kinds of collision can happen there, and they are not the same kind of accident:\n\n * **Node over node** is *recorded, not refused.* The graph author wrote two nodes\n that emit the same field, `provenance` names whichever wrote it last, and the\n earlier value is still in that node's checkpoint — nothing is lost.\n * **Node over a run input** is refused, because nothing records it. The caller's\n value is simply gone, and from then on the prompts and edge conditions that meant\n to read the caller's input read model output instead. Refusing is the same call\n `stepmold.verify` makes about a bad generation: nothing lands until it is safe.\n\n This one lives with the walker rather than in `stepmold.errors` because it is a rule about\n committing, which is the walker's own job; it still subclasses `RunError`, so every\n caller that already handles run errors handles it.\n \"\"\"\n\n\nclass ToolsNotAvailable(ToolError):\n \"\"\"A pack reached a `tool` node and this run was handed no registry.\n\n Lives here rather than in `stepmold.tools` because it is a fact about the *call* — the\n host started a run without the thing the pack needs — and not about any tool. It is\n raised the moment the node is entered rather than swallowed into `on_fail`: a pack\n that cannot act at all is a wiring mistake in the caller, not a runtime condition the\n graph author wrote a rescue path for, and diverting it would quietly finish a\n workflow with the acting half missing.\n \"\"\"\n\n\nclass ToolReplayMismatch(ToolError):\n \"\"\"A recorded call is being resumed into state that would ask a different question.\n\n A replayed result is only the answer to the arguments it was computed from, so the\n walker compares them. They cannot differ on a faithful resume — the checkpoint the\n call was written into is the same one the state was restored from — so a difference\n means the record and the run have come apart. Neither choice left is safe on its own:\n calling again risks the second side effect the record exists to prevent, and\n committing the old result puts an answer to the wrong question into state. So the run\n stops and says which arguments moved.\n \"\"\"\n\n\n@dataclass\nclass Failure:\n \"\"\"A node that could not produce a verified output and was diverted by `on_fail`.\n\n `attempts` is how many generations were spent getting there — zero when the node's\n prompt could not even be rendered, since that failure costs no model call.\n \"\"\"\n\n node: str\n reason: str\n attempts: int\n\n\n@dataclass\nclass RunResult:\n \"\"\"What a finished run leaves behind.\n\n `attempts` counts the generations each `generate` node spent, so a run that was\n rescued is distinguishable from one that never needed rescuing. `failures` records\n only the nodes that ran out of ladder; a node that was rejected twice and got there\n on the third rung leaves no failure and used to leave no trace at all — which is\n exactly the run an operator wants to see *before* the next one fails. A node absent\n from the map spent one generation or none; a node at `retries + 1` was one rung from\n diverting.\n \"\"\"\n\n run_id: str\n output: Dict[str, Any]\n state: Dict[str, Any]\n path: List[str] = field(default_factory=list)\n steps: int = 0\n provenance: Dict[str, str] = field(default_factory=dict)\n end_node: Optional[str] = None\n failures: List[\"Failure\"] = field(default_factory=list)\n attempts: Dict[str, int] = field(default_factory=dict)\n\n\ndef run(pack, model, inputs=None, run_id=None, max_steps=None, store=None,\n resume_from=None, tools=None):\n \"\"\"Walk `pack` from its entry node until an `end` node, and return a `RunResult`.\n\n `store` is anything with a `save(...)` method (see `stepmold.state.Store`); when given, a\n checkpoint is written after every node that completes. `resume_from` is a checkpoint\n to continue from instead of starting at the entry node — that is how `state.resume`\n picks a dead run back up without re-executing what already succeeded.\n\n `tools` is a `stepmold.tools.ToolRegistry`: the set of actions this host is willing to let\n this pack take, and the only thing a `tool` node can reach. It is per-run and has no\n default — a pack that can act does so because the caller said so on this call, not\n because a module-level registry happened to exist. A pack with no tool nodes never\n looks at it.\n\n Exactly-once for those calls needs `store` as well as `tools`. Without a store there\n is nothing to resume from, so nothing to repeat; with one, the walker records each\n call before committing it and a resumed run replays rather than re-calls.\n \"\"\"\n budget = max_steps if max_steps is not None else pack.max_steps\n\n if resume_from is None and store is not None and run_id is not None:\n # A fresh run must not inherit another run's checkpoint chain. Without this,\n # a reused id silently splices two runs and `resume` replays the older one's\n # output as if it belonged to this run.\n previous = getattr(store, \"latest\", None)\n if previous is not None and previous(run_id) is not None:\n raise RunIdInUse(\n \"run id %r already has checkpoints in this store; \"\n \"resume it, delete it, or choose another id\" % run_id\n )\n\n if resume_from is not None:\n run_id = run_id or resume_from.run_id\n state = dict(resume_from.state)\n provenance = dict(resume_from.provenance)\n path = list(resume_from.path)\n failures = [Failure(**record) for record in resume_from.failures]\n # A store older than per-node attempt counts has no column for them; the run\n # resumes with what it can and keeps counting from there.\n attempts = dict(getattr(resume_from, \"attempts\", None) or {})\n # The calls this run made but never finished leaving a node for. Normally empty;\n # one entry means a process died between a tool returning and its node being\n # walked out of, and that entry is what stops the call being made twice. A store\n # older than the column hands back nothing, exactly as one that recorded no call\n # would — see `_store_records_tool_calls` for why that is warned about loudly.\n pending_calls = [dict(record)\n for record in (getattr(resume_from, \"tool_calls\", None) or [])]\n steps = resume_from.step\n node = _node(pack, resume_from.next_node, \"resume point of run %r\" % run_id)\n else:\n state = dict(inputs or {})\n provenance = {}\n path = []\n failures = []\n attempts = {}\n pending_calls = []\n steps = 0\n node = _node(pack, pack.entry, \"entry node\")\n run_id = run_id or uuid.uuid4().hex\n # Said once per run rather than once per tool node: a store that cannot hold the\n # record is one fact about this run, and repeating it per node would bury it.\n warned_unrecorded = False\n\n # One clock read per run and one per node, taken unconditionally. Guarding them\n # behind `isEnabledFor` would save tens of nanoseconds next to a node that blocks for\n # a fifth of a second on a GPU, and would cost the thing this module is for: a\n # duration that is missing whenever the level changed halfway through a run.\n run_started = time.perf_counter()\n if _log.isEnabledFor(INFO):\n event(_log, INFO, \"run.start\", run_id=run_id, pack=pack.name,\n version=pack.version, entry=node.name, resumed=resume_from is not None,\n max_steps=budget, inputs=sorted(str(key) for key in state))\n if resume_from is not None:\n event(_log, INFO, \"run.resumed\", run_id=run_id, pack=pack.name,\n from_step=resume_from.step, next_node=node.name,\n done=len(path), failures=len(failures))\n\n try:\n while True:\n steps += 1\n if steps > budget:\n raise MaxStepsExceeded(\n \"run exceeded max_steps=%d at node %r — the graph is looping\"\n % (budget, node.name)\n )\n path.append(node.name)\n node_started = time.perf_counter()\n\n if node.type == \"end\":\n output = _project(node, state)\n _checkpoint(store, pack, run_id, steps, node.name, None, state, path,\n provenance, failures, attempts, output,\n tool_calls=pending_calls)\n if _log.isEnabledFor(INFO):\n # The line an operator greps for first: did it finish, where, how\n # many generations did it burn, and how long did the whole thing\n # take. Sizes, never contents — the output is the caller's data.\n event(_log, INFO, \"run.end\", run_id=run_id, pack=pack.name,\n end_node=node.name, steps=steps,\n generations=sum(attempts.values()), failures=len(failures),\n output_keys=len(output), output_bytes=size_of(output),\n duration_ms=_ms(run_started))\n return RunResult(\n run_id=run_id,\n output=output,\n state=state,\n path=path,\n steps=steps,\n provenance=provenance,\n end_node=node.name,\n failures=failures,\n attempts=attempts,\n )\n\n if node.type == \"generate\":\n # `attempts` is cumulative across visits (a node inside a loop is\n # entered more than once), so this visit's cost is the difference.\n before = attempts.get(node.name, 0)\n try:\n value = run_node(node, state, model, attempts=attempts)\n except Unsure as exc:\n # Ahead of the clause below on purpose: `Unsure` is a kind of\n # `NodeFailed`, and the whole point of it is that it does not go\n # where a plain failure goes. The model answered; independent samples\n # of it disagreed, so what the run has is an answer nobody can\n # believe rather than no answer at all — which is a person's problem,\n # not a rescue path's. `on_unsure` is where a pack says so. Falling\n # back to `on_fail` is the conservative reading of a pack that never\n # thought about it: somewhere declared is better than nowhere, and a\n # node with neither aborts rather than committing on a coin flip.\n target = getattr(node, \"on_unsure\", None) or node.on_fail\n _log_failed(run_id, node, exc,\n attempts.get(node.name, 0) - before, node_started)\n if not target:\n raise\n failures.append(_failure(node, exc))\n _checkpoint(store, pack, run_id, steps, node.name, target, state,\n path, provenance, failures, attempts,\n tool_calls=pending_calls)\n edge = (\"edge.on_unsure\" if getattr(node, \"on_unsure\", None)\n else \"edge.on_fail\")\n event(_log, INFO, edge, run_id=run_id, node=node.name, to=target)\n node = _node(pack, target, \"unsure route of %r\" % node.name)\n continue\n except (NodeFailed, MissingVariable) as exc:\n # The two ways a generate node can fail to produce a verified output,\n # and `on_fail` is the declared answer to both: a spent retry ladder,\n # and a prompt that never rendered because it names state nobody\n # wrote. The second one costs no generation — no re-sample can fix a\n # template — so the ladder is skipped, not silently bypassed. A\n # backend that is *down* is not the node's declared failure mode and\n # still stops the run, but a 200 that carried no text is a bad sample\n # rather than a dead endpoint: `verify.run_node` spends a rung on it,\n # so it arrives here as a NodeFailed and takes this edge like any\n # other. Either way the rejected output is dropped and never touches\n # state.\n _log_failed(run_id, node, exc,\n attempts.get(node.name, 0) - before, node_started)\n if not node.on_fail:\n raise\n failures.append(_failure(node, exc))\n _checkpoint(store, pack, run_id, steps, node.name, node.on_fail,\n state, path, provenance, failures, attempts,\n tool_calls=pending_calls)\n event(_log, INFO, \"edge.on_fail\", run_id=run_id, node=node.name,\n to=node.on_fail)\n node = _node(pack, node.on_fail, \"on_fail of %r\" % node.name)\n continue\n commit(node, value, state, provenance)\n if _log.isEnabledFor(INFO):\n event(_log, INFO, \"node.ok\", run_id=run_id, node=node.name,\n type=node.type,\n attempts=attempts.get(node.name, 0) - before,\n # \"merge\" is the walker's own word for a node with no\n # `output:` key, whose fields drop straight into state.\n output=node.output or \"merge\",\n duration_ms=_ms(node_started))\n # Nested rather than a second top-level check, and that is sound\n # rather than clever: levels are thresholds, so DEBUG being enabled\n # implies INFO is. The common case — logging off — asks once per\n # node instead of twice, and this is the innermost loop stepmold has.\n if _log.isEnabledFor(DEBUG):\n # A fingerprint, not the state: two runs that diverge did so at\n # the first node whose digest differs, and nobody reading the log\n # learns a byte of the caller's data.\n event(_log, DEBUG, \"state.committed\", run_id=run_id,\n node=node.name, keys=len(state),\n state_bytes=size_of(state), state_digest=digest(state))\n try:\n following = _next(pack, node, state)\n except DeadEnd:\n # The output is verified and already in state; only the routing\n # failed. Checkpoint before the DeadEnd escapes, or a node that\n # really did run leaves no record of what it committed. `next_node`\n # points back at this node because `None` is how a checkpoint says\n # the run finished (`state.Checkpoint.finished`) — this one did not,\n # and an operator who repairs the graph resumes by running this node\n # again.\n _checkpoint(store, pack, run_id, steps, node.name, node.name, state,\n path, provenance, failures, attempts,\n tool_calls=pending_calls)\n raise\n _checkpoint(store, pack, run_id, steps, node.name, following, state,\n path, provenance, failures, attempts,\n tool_calls=pending_calls)\n if _log.isEnabledFor(DEBUG):\n event(_log, DEBUG, \"edge.taken\", run_id=run_id, node=node.name,\n to=following)\n node = _node(pack, following, \"edge from %r\" % node.name)\n continue\n\n if node.type == \"tool\":\n tool = _tool_for(node, tools)\n # Read exactly as `Tool.invoke` will read them, because the arguments are\n # half of what makes a recorded call replayable: a result is only ever\n # the answer to the question it was asked. Missing reads are not filtered\n # out to be forgiving — `invoke` raises `ToolContract` on them, and this\n # dict is never used to call anything.\n arguments = {key: state[key] for key in tool.reads if key in state}\n recorded = _recorded_call(pending_calls, node.name)\n if recorded is not None:\n # This node already ran, in a process that died before it could\n # finish leaving it. Replaying is not an optimisation — it is the\n # entire promise: calling again is the second email.\n value = _replay_call(recorded, node, tool, arguments)\n else:\n try:\n value = tool.invoke(state, node.name)\n except (ToolFailed, ToolContract) as exc:\n # A database that is down and a retry ladder that is spent are\n # the same fact to the graph: this node produced no output. So a\n # tool failure takes the node's `on_fail` edge, and aborts the\n # run when the node declares none, exactly as a generation\n # failure does. `ToolContract` rides along with it for the same\n # reason `MissingVariable` rides with `NodeFailed` above: a tool\n # wired to state nobody wrote, or one that returned a shape the\n # graph was not built around, is a node that cannot produce a\n # verified output — not a new category of run-ending event.\n # `ToolNotRegistered` deliberately does not: a pack naming an\n # action the host never allowed is a fact about the pack, and an\n # `on_fail` edge must not quietly finish a workflow around it.\n _log_failed(run_id, node, exc, 0, node_started)\n if not node.on_fail:\n raise\n failures.append(_failure(node, exc))\n _checkpoint(store, pack, run_id, steps, node.name, node.on_fail,\n state, path, provenance, failures, attempts,\n tool_calls=pending_calls)\n event(_log, INFO, \"edge.on_fail\", run_id=run_id, node=node.name,\n to=node.on_fail)\n node = _node(pack, node.on_fail, \"on_fail of %r\" % node.name)\n continue\n if not tool.idempotent:\n pending_calls.append({\n \"node\": node.name,\n \"tool\": tool.name,\n \"args\": arguments,\n \"result\": value,\n })\n if store is not None and not warned_unrecorded \\\n and not _store_records_tool_calls(store):\n warned_unrecorded = True\n event(_log, WARNING, \"tool.unrecorded\", run_id=run_id,\n node=node.name, tool=tool.name,\n store=type(store).__name__,\n reason=\"store.save takes no tool_calls, so a resumed \"\n \"run cannot know this call already happened\")\n # Written down before the commit and before the edge, with\n # `next_node` still this node because the walk has not left it.\n # Everything after this line — the commit, the routing, the\n # process — may die, and the resume lands here and replays.\n _checkpoint(store, pack, run_id, steps, node.name, node.name,\n state, path, provenance, failures, attempts,\n tool_calls=pending_calls)\n # Whether this node's call is written down and still unsettled. It is\n # read after the commit, when `state` has already moved.\n pending = _recorded_call(pending_calls, node.name) is not None\n commit(node, value, state, provenance)\n if _log.isEnabledFor(INFO):\n # `node.ok` rather than an event of its own: an operator asking \"what\n # did this run do, in order\" wants one line per node whatever the\n # node was. `attempts` is zero because a tool spends no generations,\n # and that zero is the honest answer rather than a missing field.\n event(_log, INFO, \"node.ok\", run_id=run_id, node=node.name,\n type=node.type, attempts=0, tool=tool.name,\n replayed=recorded is not None,\n output=node.output or \"merge\",\n duration_ms=_ms(node_started))\n try:\n following = _next(pack, node, state)\n except DeadEnd:\n # Only the routing failed, so an operator who repairs the edge\n # resumes into this node — which must replay the call, not make it\n # again. When the call is written down, the row that says so is\n # already on disk from before the commit, and rewriting this step\n # with the committed state is exactly the wrong move: a tool that\n # reads a field it also writes would then be resumed against\n # arguments its own output had moved, and refused as a mismatch. The\n # pending row is the correct restart point, so it is left alone.\n if not pending:\n # Nothing was recorded — an idempotent tool — so the committed\n # state is the only trace this node ran, exactly as for a\n # `generate` node whose edge did not match.\n _checkpoint(store, pack, run_id, steps, node.name, node.name,\n state, path, provenance, failures, attempts,\n tool_calls=pending_calls)\n raise\n # The node has been left by an edge that exists, so the call is settled:\n # from here on the committed state is the record that it happened, and\n # resume will never re-enter this node. Clearing it is also what keeps a\n # loop honest — the next time round finds nothing and calls again, which\n # is what a tool inside a loop is for.\n pending_calls[:] = [record for record in pending_calls\n if record.get(\"node\") != node.name]\n _checkpoint(store, pack, run_id, steps, node.name, following, state,\n path, provenance, failures, attempts,\n tool_calls=pending_calls)\n if _log.isEnabledFor(DEBUG):\n event(_log, DEBUG, \"edge.taken\", run_id=run_id, node=node.name,\n to=following)\n node = _node(pack, following, \"edge from %r\" % node.name)\n continue\n\n if node.type == \"assert\":\n try:\n passed = is_true(node.expr, state)\n except ExprError:\n # An expression that cannot be evaluated is not a true one, and it is\n # what `on_fail` is for. `stepmold.verify` already downgrades the identical\n # call this way for a node's `assert:` (see `verify._check_assert`),\n # so both call sites route an unevaluable expression to the same\n # place. With nowhere to divert, the ExprError itself escapes rather\n # than an AssertFailed: it names the identifier that is missing, and\n # the expression was never false — it was unanswerable.\n if not node.on_fail:\n raise\n passed = False\n if passed:\n following = _next(pack, node, state)\n elif node.on_fail:\n following = node.on_fail\n else:\n event(_log, WARNING, \"node.failed\", run_id=run_id, node=node.name,\n type=node.type, attempts=0, error=\"AssertFailed\",\n reason=node.expr, on_fail=None,\n duration_ms=_ms(node_started))\n raise AssertFailed(node.name, node.expr)\n # The expression is pack-authored text, so it is safe to print whole —\n # it is the same string the graph author wrote in graph.yaml.\n event(_log, INFO if not passed else DEBUG, \"node.assert\", run_id=run_id,\n node=node.name, type=node.type, passed=passed, expr=node.expr,\n to=following, duration_ms=_ms(node_started))\n _checkpoint(store, pack, run_id, steps, node.name, following, state,\n path, provenance, failures, attempts,\n tool_calls=pending_calls)\n node = _node(pack, following, \"edge from %r\" % node.name)\n continue\n\n raise DeadEnd(\"node %r has unknown type %r\" % (node.name, node.type))\n except RunError as exc:\n # Every way a run can stop short passes through here on its way out — a spent\n # ladder with no `on_fail`, a dangling edge, an unbroken loop, a commit that\n # would have overwritten the caller's input. The exception was always raised;\n # until now it was never *recorded*, so a supervisor that swallowed it left\n # nothing behind saying which node the run died on.\n event(_log, ERROR, \"run.error\", run_id=run_id, pack=pack.name, node=node.name,\n step=steps, error=type(exc).__name__, reason=_safe_reason(exc),\n duration_ms=_ms(run_started))\n raise\n\n\ndef commit(node, value, state, provenance):\n \"\"\"Write a node's verified output into run state, recording who wrote what.\n\n A key already in state may be written again — a node inside a loop rewrites its own\n counter every time round, and a later node may deliberately restate an earlier one's\n field — and `provenance` records who wrote it last. The one collision that is refused\n is a key that came from the run's inputs, because that overwrite leaves no record at\n all; see `StateCollision`.\n\n Every key is checked before the first one is written, so a refused commit leaves\n state and provenance exactly as they were.\n \"\"\"\n keys = [node.output] if node.output else list(value)\n for key in keys:\n # In state but never committed by a node — so the caller supplied it.\n if key in state and key not in provenance:\n raise StateCollision(\n \"node %r would overwrite %r, which came from the run inputs; give the \"\n \"node its own `output:` key or rename the field in its grammar\"\n % (node.name, key)\n )\n if node.output:\n state[node.output] = value\n provenance[node.output] = node.name\n return\n for key, item in value.items():\n state[key] = item\n provenance[key] = node.name\n\n\ndef _ms(started):\n \"\"\"Milliseconds since `started`, rounded to something a log line can hold.\"\"\"\n return round((time.perf_counter() - started) * 1000.0, 1)\n\n\ndef _log_failed(run_id, node, exc, spent, node_started):\n \"\"\"The two lines a diverted node leaves behind, and the split between them.\n\n One event whatever failed, so `node.failed` is still the single thing to grep for.\n The default-level line carries only the half that may be shipped to a collector; the\n half that may quote a generation, or a tool's own exception text, is DEBUG-only. See\n `_safe_reason`.\n \"\"\"\n if _log.isEnabledFor(WARNING):\n event(_log, WARNING, \"node.failed\", run_id=run_id, node=node.name,\n type=node.type, attempts=spent, error=type(exc).__name__,\n reason=_safe_reason(exc), on_fail=node.on_fail,\n duration_ms=_ms(node_started))\n if _log.isEnabledFor(DEBUG):\n # The unsafe half, once, at the only level allowed to hold it.\n event(_log, DEBUG, \"node.failed.detail\", run_id=run_id, node=node.name,\n detail=str(exc))\n\n\ndef _safe_reason(exc):\n \"\"\"The half of a failure that may go into a default-level log line.\n\n `NodeFailed.reason` is the last rejection's full detail and may quote the generation\n verbatim — `verify.Rejected` keeps the two halves apart precisely so that the model\n never sees one of them, and a log an operator ships to a collector is the same kind\n of downstream. `feedback` is the sanitised half. When a NodeFailed was built without\n one, this says so rather than falling back to the detail: an empty log field is a\n smaller failure than a leaked one, and the detail is still there at DEBUG.\n\n `ToolFailed` gets the same treatment for a different reason. Its text is whatever the\n host's own function raised, and a tool raises about the thing it was given — \"no such\n customer alice@example.com\", the row it could not write. That is the caller's data\n arriving by a second door, so the default-level line names the tool and the type of\n what went wrong and stops there. `ToolContract` goes out whole: every value in it is\n a key name out of the pack or the tool's own declaration, never a value.\n\n Everything else here — a dangling edge, a step budget, an unevaluable expression —\n is stepmold's own words about the pack's own text, and goes out whole.\n \"\"\"\n if isinstance(exc, NodeFailed):\n return exc.feedback or \"rejected (detail at DEBUG)\"\n if isinstance(exc, ToolFailed):\n return \"tool %r raised %s (detail at DEBUG)\" % (\n exc.tool, type(exc.cause).__name__\n )\n return str(exc)\n\n\ndef _failure(node, exc):\n \"\"\"Record whichever way this node failed, for `RunResult.failures`.\n\n `getattr` rather than more isinstance branches: a failure that carries its own node\n and cost says so — `NodeFailed` and anything built on it — and one that does not is\n attributed to the node the walker was standing on, having spent nothing. That covers\n an unrenderable prompt, a tool that raised, and any outcome `stepmold.verify` grows later\n without this function needing to hear about it.\n \"\"\"\n if isinstance(exc, NodeFailed):\n return Failure(node=exc.node, reason=exc.reason, attempts=exc.attempts)\n # A tool that raised and a prompt that never rendered both cost no generation.\n return Failure(\n node=getattr(exc, \"node\", None) or node.name,\n reason=str(exc),\n attempts=getattr(exc, \"attempts\", 0) or 0,\n )\n\n\n# ----------------------------------------------------------------------------- tools\n\n\ndef _tool_for(node, tools):\n \"\"\"The registered action this node names, or a refusal that says what to change.\"\"\"\n if tools is None:\n raise ToolsNotAvailable(\n \"node %r is a tool node, and this run was given no tools: this pack needs \"\n \"tools; pass tools= to run()\" % node.name\n )\n name = getattr(node, \"tool\", None)\n if not name:\n raise ToolsNotAvailable(\n \"node %r is type 'tool' but names no tool to call — give it a `tool:` key \"\n \"naming one of the actions the host registered (%s)\"\n % (node.name, \", \".join(getattr(tools, \"names\", ())) or \"none\")\n )\n # A name the host never registered raises `ToolNotRegistered` out of here, and is not\n # caught anywhere in the walk: see the tool branch for why that is not an `on_fail`.\n return tools.get(name, node.name)\n\n\ndef _recorded_call(pending_calls, node_name):\n \"\"\"The unsettled call this node already made, if a previous process made it.\n\n Last first, because a record is only ever added by the node the walk is standing on\n and only ever removed once that node is left — so at most one is ever pending, and\n the newest is the one this node is resuming into.\n \"\"\"\n for record in reversed(pending_calls):\n if record.get(\"node\") == node_name:\n return record\n return None\n\n\ndef _replay_call(record, node, tool, arguments):\n \"\"\"The result a previous process already got, instead of calling again.\"\"\"\n moved = _moved_args(record.get(\"args\"), arguments)\n if moved:\n raise ToolReplayMismatch(\n \"run resumed into node %r holding a call to %r that already happened, but \"\n \"state no longer matches the arguments it was made with (%s differ). The \"\n \"recorded result answers a question this run is no longer asking, and \"\n \"calling again would repeat a side effect that already took place — so the \"\n \"run stops instead of choosing between them. Read the run's checkpoints \"\n \"before resuming it again.\"\n % (node.name, tool.name, \", \".join(moved))\n )\n result = record.get(\"result\")\n return dict(result) if isinstance(result, dict) else {}\n\n\ndef _canonical(value):\n \"\"\"A comparable form of an argument set.\n\n Canonical JSON rather than `==`, for the reason `state._dict_delta` gives: `True == 1`\n in Python, so two argument sets that a tool would treat as different compare equal.\n A value that is not JSON never came out of a checkpoint, so `repr` is the honest\n fallback rather than a reason to raise.\n \"\"\"\n try:\n return json.dumps(value, sort_keys=True, allow_nan=False)\n except (TypeError, ValueError):\n return repr(value)\n\n\ndef _moved_args(recorded, current):\n \"\"\"The argument names whose value changed, appeared or vanished. Names only.\n\n Names only, because this ends up in an exception message and an argument's value is\n the caller's data. Which argument moved is what an operator needs to find the cause;\n what it moved to is in the checkpoint, where it is already allowed to be.\n \"\"\"\n if not isinstance(recorded, dict):\n # A record with no argument set at all cannot be matched against anything, and\n # saying so beats silently accepting it.\n return [\"the recorded arguments (none were written down)\"]\n names = set(recorded) | set(current)\n return sorted(\n name for name in names\n if name not in recorded or name not in current\n or _canonical(recorded[name]) != _canonical(current[name])\n )\n\n\n# ------------------------------------------------------------------------ traversal\n\n\ndef _node(pack, name, why):\n if name not in pack.nodes:\n raise DanglingEdge(\"%s points at undefined node %r\" % (why, name))\n return pack.nodes[name]\n\n\ndef _next(pack, node, state):\n for edge in pack.edges_from(node.name):\n if _matches(edge.when, state):\n return edge.target\n raise DeadEnd(\n \"no outgoing edge from %r matched the current state\" % node.name\n )\n\n\ndef _matches(when, state):\n if not when:\n return True\n for path, expected in when.items():\n if _lookup(path, state) != expected:\n return False\n return True\n\n\n_MISSING = object()\n\n\ndef _lookup(path, state):\n current = state\n for part in str(path).split(\".\"):\n if not isinstance(current, dict) or part not in current:\n return _MISSING\n current = current[part]\n return current\n\n\ndef _project(node, state):\n if not node.output:\n return dict(state)\n return {key: state[key] for key in node.output if key in state}\n\n\ndef _checkpoint(store, pack, run_id, step, node, next_node, state, path, provenance,\n failures, attempts, output=None, tool_calls=None):\n \"\"\"Persist one completed node, if this run is being checkpointed at all.\"\"\"\n if store is None:\n return\n extra = {\"attempts\": dict(attempts)} if _store_records_attempts(store) else {}\n if _store_records_tool_calls(store):\n extra[\"tool_calls\"] = [dict(record) for record in (tool_calls or [])]\n store.save(\n run_id=run_id,\n step=step,\n node=node,\n next_node=next_node,\n state=state,\n path=path,\n provenance=provenance,\n failures=[asdict(failure) for failure in failures],\n output=output,\n # Hand over the pack itself, not just its name: the store records name AND\n # version, and `state.resume` needs both to catch a graph that moved on under\n # a run. Passing pack.name here threw the version away before the store saw it.\n pack=pack,\n **extra\n )\n\n\n@lru_cache(maxsize=None)\ndef _save_accepts(store_type, keyword):\n \"\"\"Whether this store's `save` will take `keyword`.\n\n `store` is documented as anything with a `save(...)` method, so anything the walker\n learned to record after that contract was written is offered rather than imposed: a\n store built against the older signature would raise `TypeError` on a keyword it never\n asked for, and losing the checkpoint entirely is a worse outcome than losing one\n field from it.\n \"\"\"\n save = getattr(store_type, \"save\", None)\n if save is None:\n return False\n try:\n parameters = inspect.signature(save).parameters.values()\n except (TypeError, ValueError):\n return False\n kinds = (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)\n return any(\n parameter.kind is inspect.Parameter.VAR_KEYWORD\n or (parameter.name == keyword and parameter.kind in kinds)\n for parameter in parameters\n )\n\n\ndef _store_records_attempts(store):\n return _save_accepts(type(store), \"attempts\")\n\n\ndef _store_records_tool_calls(store):\n \"\"\"Whether this store can hold the record that stops a tool firing twice.\n\n Losing a diagnostic to an old store is a shrug; losing this is a promise broken, so\n the walker says so out loud (`tool.unrecorded`) instead of degrading in silence. It\n still does not refuse the run: a run with no store at all has the same exposure and\n is perfectly legal, and a host that has chosen its own store has chosen this too.\n \"\"\"\n return _save_accepts(type(store), \"tool_calls\")\n\n\ndef replay(checkpoint):\n \"\"\"Rebuild the `RunResult` of a run that already finished, from its checkpoint.\"\"\"\n return RunResult(\n run_id=checkpoint.run_id,\n output=checkpoint.output if checkpoint.output is not None else dict(checkpoint.state),\n state=dict(checkpoint.state),\n path=list(checkpoint.path),\n steps=checkpoint.step,\n provenance=dict(checkpoint.provenance),\n end_node=checkpoint.node,\n failures=[Failure(**record) for record in checkpoint.failures],\n attempts=dict(getattr(checkpoint, \"attempts\", None) or {}),\n )\n", "stepmold/log.py": "\"\"\"Structured logging for the runtime — silent until an operator asks for it.\n\nA stepmold run used to print its final JSON and nothing else. Every fact an operator needs at\n3am already existed inside the runtime — `graph` tracks the path and the attempts,\n`verify` knows every rejection and why, `openai_compat` knows the tokens and the\nmilliseconds — and none of it was written down. This module is where it gets written.\n\nThree rules hold it together, and two of them are about what must *not* come out.\n\n**1. A library does not configure logging for its host.**\nImporting `stepmold` must not touch the root logger, must not call `basicConfig`, and must not\nput a byte on stdout or stderr. So the package logger gets a `NullHandler` at import and\nnothing else. That single line does more than swallow records: `logging.lastResort` only\nfires when a record reaches the end of the chain having found *no* handler at all, so\nwithout the NullHandler a lone `logger.warning(...)` would print to stderr from a library\nthat was never switched on. `propagate` is deliberately left alone, so a host that has\nconfigured logging of its own still sees stepmold's records; `configure` — which only the CLI\ncalls — is the explicit opt-in that installs stepmold's own handler.\n\n**2. Secrets and model text do not go in a log.**\n`redact` is the same key-shaped filter `stepmold.backends.openai_compat` has always run over\nupstream error bodies; it lives here now because \"text that is about to be written down\"\nis this module's subject, and the backend imports it back. Every formatter runs it over\nevery string it emits, so redaction is a property of the *sink* rather than a discipline\nat two hundred call sites. Rejected model output is the other half, and the rule is in\n`stepmold.verify`: the INFO path carries `Rejected.feedback` (what was wrong), never\n`Rejected.detail` (what the model said). The detail is DEBUG-only — an operator who asks\nfor DEBUG is asking to read what came back, and bytes in a log file cannot condition a\nmodel. Prompts and state never appear at all: sizes and digests instead.\n\n**3. Disabled logging costs nothing.**\nThe long-horizon suite walks 50-node packs, so no call site may build a string, a dict of\ncomputed values, or a JSON blob that a filtered-out level will throw away. `event` checks\n`isEnabledFor` before it does anything, and the call sites that would have to *compute* a\nfield — a digest, a token summary — guard themselves with `isEnabledFor` first.\n\nTwo output shapes, because two audiences read logs. `TextFormatter` is for a terminal;\n`JsonFormatter` writes one JSON object per line with stable field names, for anything\nthat ships logs somewhere.\n\"\"\"\n\nimport hashlib\nimport json\nimport logging\nimport re\nimport sys\nimport time\n\n__all__ = [\n \"BEARER\",\n \"CLIP\",\n \"DEBUG\",\n \"ERROR\",\n \"INFO\",\n \"KEY_SHAPED\",\n \"LEVELS\",\n \"ROOT\",\n \"WARNING\",\n \"JsonFormatter\",\n \"TextFormatter\",\n \"clip\",\n \"configure\",\n \"digest\",\n \"event\",\n \"get_logger\",\n \"level_named\",\n \"redact\",\n \"reset\",\n \"size_of\",\n]\n\n#: The package logger every stepmold module hangs off. `logging.getLogger(\"stepmold\")` in a host\n#: application reaches the same object, which is the whole point of naming it.\nROOT = \"stepmold\"\n\nDEBUG = logging.DEBUG\nINFO = logging.INFO\nWARNING = logging.WARNING\nERROR = logging.ERROR\n\n#: What `--log-level` accepts, plus \"off\" for \"do not configure anything\".\nLEVELS = (\"off\", \"debug\", \"info\", \"warning\", \"error\")\n\n#: How much of any single user-controlled string may reach a log line. A support ticket\n#: can be a megabyte; a log line about a support ticket may not be.\nCLIP = 200\n\n# Credentials, as they appear in text somebody else wrote: a header a gateway echoed back\n# at us, or a key pasted into an upstream error message. These moved here from\n# `stepmold.backends.openai_compat` when logging arrived — the backend still imports them, and\n# there is still exactly one of them.\nBEARER = re.compile(r\"(?i)(bearer\\s+)[^\\s\\\"',]+\")\n# The separator is part of the vendor's format, not a detail: Groq issues `gsk_...` and\n# GitHub issues `ghp_...`, so a pattern that only accepted a hyphen matched neither of the\n# two prefixes most likely to show up in a real 401 body. Both separators, and the GitHub\n# token family in full, because `ghp_` is only one of five.\nKEY_SHAPED = re.compile(\n r\"\\b(?:c?sk|gsk|xai|xox[abpsr]|gh[pousr]|AKIA|ASIA)[-_][A-Za-z0-9_-]{8,}\"\n)\n\n#: LogRecord attributes the formatters read. Prefixed because `extra=` writes straight\n#: onto the record and a collision with a stdlib attribute raises at emit time.\nEVENT_ATTR = \"stepmold_event\"\nFIELDS_ATTR = \"stepmold_fields\"\n\n_HANDLER_MARK = \"_stepmold_handler\"\n\n_package_logger = logging.getLogger(ROOT)\n# The one line that makes stepmold a well-behaved library: no output, and no `lastResort`.\n_package_logger.addHandler(logging.NullHandler())\n\n\ndef get_logger(name):\n \"\"\"The logger for one stepmold module — `get_logger(\"graph\")` -> `stepmold.graph`.\n\n Named for the module rather than passed `__name__` so the hierarchy stays flat and\n predictable: an operator filters on `stepmold.backend` without knowing that it is spelled\n `stepmold.backends.openai_compat` on disk.\n \"\"\"\n return logging.getLogger(\"%s.%s\" % (ROOT, name))\n\n\ndef event(logger, level, name, /, **fields):\n \"\"\"Emit one structured event, or do nothing if `level` is filtered out.\n\n The three parameters are positional-only so that `level=`, `name=` and `logger=` are\n usable as *field* names — `event(_log, INFO, \"run.start\", level=\"p1\")` has to mean\n what it looks like, and a logging helper that quietly stole three field names would\n be found the hard way by whoever needed one of them.\n\n `name` is the event, `fields` are its data — one flat mapping of stable field names,\n because a log line an operator can grep and a log line a collector can parse are the\n same line here. Nothing is formatted at the call site: the record carries the fields\n as objects and the formatter decides what a line looks like, which is what keeps a\n filtered-out DEBUG event down to one `isEnabledFor` check.\n\n Callers whose fields cost something to *compute* — a digest, a token summary, a\n length over a large structure — must guard with `logger.isEnabledFor(...)` themselves\n before calling, because Python evaluates the arguments before the check in here.\n \"\"\"\n if not logger.isEnabledFor(level):\n return\n logger.log(level, name, extra={EVENT_ATTR: name, FIELDS_ATTR: fields})\n\n\n# ------------------------------------------------------------------ safe field values\n\n\ndef redact(text):\n \"\"\"Strip anything credential-shaped out of text before it is written down.\n\n Unchanged from where it used to live in the backend, and for the same reason: error\n bodies are written by somebody else and read by our logs, and a gateway that echoes\n the offending request back puts the caller's own `Authorization` header in it. stepmold is\n not the leaker there, but without this it is the amplifier.\n \"\"\"\n if not text:\n return text\n return KEY_SHAPED.sub(\"\", BEARER.sub(r\"\\1\", text))\n\n\ndef clip(text, limit=CLIP):\n \"\"\"One line, bounded. Whatever a log line is about, it is not a megabyte long.\"\"\"\n collapsed = \" \".join(str(text).split())\n if len(collapsed) <= limit:\n return collapsed\n return collapsed[:limit] + \"...(%d chars)\" % len(collapsed)\n\n\ndef size_of(value):\n \"\"\"The JSON size of a value, in bytes — what may be said about state at INFO.\"\"\"\n try:\n return len(json.dumps(value, sort_keys=True, default=repr))\n except (TypeError, ValueError): # pragma: no cover - default=repr covers the rest\n return -1\n\n\ndef digest(value):\n \"\"\"A short stable fingerprint of a value, for correlating without quoting.\n\n Two runs whose `state_digest` matches saw the same state; nobody reading the log\n learns what was in it. That is the trade this function exists to make.\n \"\"\"\n try:\n blob = json.dumps(value, sort_keys=True, default=repr).encode(\"utf-8\")\n except (TypeError, ValueError): # pragma: no cover - default=repr covers the rest\n blob = repr(value).encode(\"utf-8\", \"replace\")\n return hashlib.sha256(blob).hexdigest()[:12]\n\n\ndef _safe(value):\n \"\"\"A field value as it may appear in a log: redacted, clipped, JSON-representable.\"\"\"\n if isinstance(value, str):\n # Redact first, THEN clip. The other order truncates a credential that\n # straddles the clip boundary until KEY_SHAPED no longer matches it, and the\n # surviving prefix is printed verbatim. Reproduced at offsets 185-196.\n return clip(redact(value))\n if isinstance(value, (bool, int, float)) or value is None:\n return value\n if isinstance(value, (list, tuple)):\n return [_safe(item) for item in value]\n if isinstance(value, dict):\n return dict((str(key), _safe(item)) for key, item in value.items())\n return redact(clip(repr(value)))\n\n\n# ----------------------------------------------------------------------- formatters\n\n\nclass TextFormatter(logging.Formatter):\n \"\"\"One event per line, for a human at a terminal.\n\n 14:02:11.402 INFO stepmold.graph node.ok node=classify attempt=1 duration_ms=0.8\n\n Values are printed bare when they are a single word and JSON-quoted when they are\n not, so a field containing a space cannot be misread as two fields.\n \"\"\"\n\n def format(self, record):\n fields = getattr(record, FIELDS_ATTR, None) or {}\n rendered = \" \".join(\n \"%s=%s\" % (key, _as_text(value)) for key, value in fields.items()\n )\n line = \"%s %-5s %s %s\" % (\n _timestamp(record), record.levelname, record.name, _event_of(record)\n )\n return line + (\" \" + rendered if rendered else \"\")\n\n\nclass JsonFormatter(logging.Formatter):\n \"\"\"One JSON object per line, for anything that ships logs.\n\n `ts`, `level`, `logger` and `event` come first and always exist; the event's own\n fields follow at the top level, because `jq '.attempt'` is what somebody will\n actually type. A field that collides with one of the four reserved names is prefixed\n rather than dropped — losing data to make a line tidy is the wrong trade in the file\n somebody reads after an incident.\n \"\"\"\n\n RESERVED = (\"ts\", \"level\", \"logger\", \"event\")\n\n def format(self, record):\n payload = {\n \"ts\": _timestamp(record, date=True),\n \"level\": record.levelname,\n \"logger\": record.name,\n \"event\": _event_of(record),\n }\n for key, value in (getattr(record, FIELDS_ATTR, None) or {}).items():\n name = \"field_%s\" % key if key in self.RESERVED else key\n payload[name] = _safe(value)\n if record.exc_info:\n payload[\"exc_type\"] = record.exc_info[0].__name__\n # ensure_ascii=False: a log file is UTF-8, and escaping an em dash to\n # \\\\u2014 makes the one field an operator is trying to read unreadable.\n return json.dumps(payload, default=str, ensure_ascii=False)\n\n\ndef _event_of(record):\n \"\"\"The event name, or a plain record's message — redacted either way.\n\n Only `stepmold_fields` used to be filtered, so a record logged through the ordinary\n stdlib API on a `stepmold.*` logger reached the output unfiltered. Redaction is supposed\n to be a property of the sink, not a discipline every call site remembers, so the\n message goes through the same filter as the fields.\n \"\"\"\n name = getattr(record, EVENT_ATTR, None)\n if name is not None:\n return redact(str(name))\n return clip(redact(record.getMessage()))\n\n\ndef _timestamp(record, date=False):\n shape = \"%Y-%m-%dT%H:%M:%S\" if date else \"%H:%M:%S\"\n stamp = time.strftime(shape, time.gmtime(record.created))\n return \"%s.%03d%s\" % (stamp, record.msecs, \"Z\" if date else \"\")\n\n\n_CONTROL = re.compile(r\"[\\x00-\\x1f\\x7f]\")\n\n\ndef _as_text(value):\n \"\"\"One field's value as a terminal line spells it.\n\n A missing value prints as `-` rather than vanishing, because a field that\n disappears when it is empty makes two runs' log lines impossible to diff. Lists\n print comma-joined — `inputs=ticket,account` — which is what an eye reads; the JSON\n formatter is where a machine goes for the real structure.\n \"\"\"\n safe = _safe(value)\n if safe is None:\n return \"-\"\n if isinstance(safe, str) and _CONTROL.search(safe):\n # An unescaped ESC from upstream text would run as a terminal command in the\n # operator's console. json.dumps turns it into \\u001b, which is readable and inert.\n return json.dumps(safe, ensure_ascii=False)\n if isinstance(safe, bool):\n return \"true\" if safe else \"false\"\n if isinstance(safe, (int, float)):\n return repr(safe)\n if isinstance(safe, list):\n safe = \",\".join(_as_text(item) for item in safe)\n elif not isinstance(safe, str):\n safe = json.dumps(safe, default=str, sort_keys=True, ensure_ascii=False)\n if safe == \"\" or any(char.isspace() for char in safe) or '\"' in safe:\n return json.dumps(safe, ensure_ascii=False)\n return safe\n\n\n# --------------------------------------------------------------------- configuration\n\n\ndef configure(level=\"info\", fmt=\"text\", stream=None):\n \"\"\"Turn stepmold's logging on. Only an application — the CLI — may call this.\n\n Everything lands on **stderr** by default, never stdout: `stepmold run` prints its result\n as JSON on stdout and a caller pipes it onward, so a log line there would corrupt the\n output rather than describe it.\n\n `propagate` is switched off once stepmold owns a handler of its own. A host that had\n already configured the root logger would otherwise get every record twice, which is\n the classic library-logging bug and reads as a runtime that repeats itself.\n \"\"\"\n logger = logging.getLogger(ROOT)\n for handler in list(logger.handlers):\n if getattr(handler, _HANDLER_MARK, False):\n logger.removeHandler(handler)\n handler.close()\n handler = logging.StreamHandler(sys.stderr if stream is None else stream)\n handler.setFormatter(JsonFormatter() if fmt == \"json\" else TextFormatter())\n setattr(handler, _HANDLER_MARK, True)\n logger.addHandler(handler)\n logger.setLevel(level_named(level))\n logger.propagate = False\n return logger\n\n\ndef reset():\n \"\"\"Undo `configure` — back to a library that emits nothing on its own.\n\n Here for tests and for a host embedding stepmold that wants its own logging back; the\n NullHandler stays, because rule 1 above holds whether or not anyone configured\n anything.\n \"\"\"\n logger = logging.getLogger(ROOT)\n for handler in list(logger.handlers):\n if getattr(handler, _HANDLER_MARK, False):\n logger.removeHandler(handler)\n handler.close()\n logger.setLevel(logging.NOTSET)\n logger.propagate = True\n return logger\n\n\ndef level_named(level):\n \"\"\"`\"debug\"` / `\"DEBUG\"` / `logging.DEBUG` -> a level number. `\"off\"` silences.\"\"\"\n if isinstance(level, int):\n return level\n name = str(level).strip().lower()\n if name in (\"off\", \"none\", \"silent\"):\n return logging.CRITICAL + 1\n number = logging.getLevelName(name.upper())\n if not isinstance(number, int):\n raise ValueError(\n \"unknown log level %r (known: %s)\" % (level, \", \".join(LEVELS))\n )\n return number\n", "stepmold/model.py": "\"\"\"The model interface stepmold executes against, and the FakeModel every test uses.\n\nstepmold never calls a model directly from the graph walker; it calls whatever satisfies\n`Model`. That is what keeps the entire test suite offline — `FakeModel` is a drop-in.\n\"\"\"\n\nfrom dataclasses import dataclass, field\nfrom typing import Dict, List, Optional, Protocol, Sequence, Union, runtime_checkable\n\n\nclass ModelExhausted(RuntimeError):\n \"\"\"A FakeModel was asked for a response its script does not contain.\"\"\"\n\n\n@runtime_checkable\nclass Model(Protocol):\n \"\"\"Anything stepmold can generate with.\"\"\"\n\n def generate(\n self,\n prompt: str,\n grammar: Optional[dict] = None,\n max_tokens: int = 512,\n ) -> str:\n \"\"\"Return a completion for `prompt`, shaped by `grammar` when one is given.\"\"\"\n ...\n\n\n@dataclass(frozen=True)\nclass Call:\n \"\"\"One recorded generation, so tests can assert on how the model was used.\"\"\"\n\n prompt: str\n grammar: Optional[dict]\n max_tokens: int\n\n\nScript = Union[Sequence[str], Dict[str, Union[str, Sequence[str]]]]\n\n\n@dataclass\nclass FakeModel:\n \"\"\"A scripted stand-in for a real model.\n\n Two modes:\n\n * **ordered** — `FakeModel([\"a\", \"b\"])` returns the responses in order and raises\n `ModelExhausted` once past the end.\n * **keyed** — `FakeModel({\"classify\": \"billing\"})` returns the response whose key is\n a substring of the prompt. The *longest* matching key wins, so a specific key can\n override a general one. A key's value may be a list, which is consumed in order\n (this is how a multi-case evalset scripts one node across many inputs).\n \"\"\"\n\n scripted: Script\n calls: List[Call] = field(default_factory=list, init=False, repr=False)\n\n def __post_init__(self) -> None:\n if isinstance(self.scripted, dict):\n if not self.scripted:\n raise ValueError(\"FakeModel needs at least one scripted response\")\n self._keyed_script = {\n k: (v if isinstance(v, str) else list(v))\n for k, v in self.scripted.items()\n }\n elif isinstance(self.scripted, (list, tuple)):\n if not self.scripted:\n raise ValueError(\"FakeModel needs at least one scripted response\")\n self._ordered = list(self.scripted)\n else:\n raise TypeError(\n \"FakeModel script must be a list of responses or a dict keyed by \"\n \"prompt substring, not %s\" % type(self.scripted).__name__\n )\n\n @property\n def call_count(self) -> int:\n return len(self.calls)\n\n def generate(\n self,\n prompt: str,\n grammar: Optional[dict] = None,\n max_tokens: int = 512,\n ) -> str:\n self.calls.append(Call(prompt=prompt, grammar=grammar, max_tokens=max_tokens))\n if isinstance(self.scripted, dict):\n return self._keyed(prompt)\n return self._next_ordered()\n\n def _next_ordered(self) -> str:\n index = len(self.calls) - 1\n if index >= len(self._ordered):\n raise ModelExhausted(\n \"FakeModel script has %d responses; call %d has nothing to return\"\n % (len(self._ordered), len(self.calls))\n )\n return self._ordered[index]\n\n def _keyed(self, prompt: str) -> str:\n matches = [k for k in self._keyed_script if k in prompt]\n if not matches:\n raise ModelExhausted(\n \"FakeModel has no scripted response matching prompt: %r\" % prompt\n )\n key = max(matches, key=len)\n responses = self._keyed_script[key]\n if isinstance(responses, str):\n return responses # a plain-string key answers every matching prompt\n if not responses:\n raise ModelExhausted(\n \"FakeModel ran out of scripted responses for key %r\" % key\n )\n return responses.pop(0)\n", "stepmold/pack.py": "\"\"\"Loading and validating a StepmoldPack.\n\nA pack is a directory, not a database — it is meant to be read in a diff, checked into\na client's repo, and shipped as text (docs/ARCHITECTURE.md §7.2):\n\n /\n manifest.yaml name, version, entry node, model hint\n graph.yaml nodes + edges (the compiled \"plan\")\n prompts/.txt one prompt template per generate node\n prompts/.think.txt optional think-stage template (T5)\n grammars/.json one JSON Schema per generate node\n evalset.jsonl the contract: {\"input\": {...}, \"expect\": {...}} per line\n\nA `tool` node has no files of its own: it names a function the *host* registered\n(`stepmold/tools.py`), so there is nothing in the pack to read for it. Pass the registry —\n`load_pack(path, tools=registry)` — and the name it calls and the state that tool reads\nare checked here too; leave it out and the pack still loads, unchecked on that one point.\n\nEverything a run needs is validated here, at load time, so the walker never has to ask\n\"does this node exist?\" mid-run. Errors name the offending file and node.\n\"\"\"\n\nimport json\nimport os\nfrom dataclasses import dataclass, field\nfrom typing import Any, Dict, List, Optional\n\nfrom .grammar import SchemaError, check_schema\nfrom .yamlish import YamlError, parse as parse_yaml\n\n__all__ = [\n \"Edge\",\n \"EvalCase\",\n \"EvalsetError\",\n \"GrammarError\",\n \"GraphError\",\n \"ManifestError\",\n \"MissingArtifactError\",\n \"Node\",\n \"Pack\",\n \"PackError\",\n \"RESERVED_STATE_NAMES\",\n \"ToolWiringError\",\n \"UnsafePath\",\n \"check_tools\",\n \"load_pack\",\n]\n\nNODE_TYPES = (\"generate\", \"assert\", \"tool\", \"end\")\n\n# Names stepmold binds in a run's scope for its own purposes. `codegen.think` renders the\n# think template with a `scratchpad` of its own, so anything else that lands under that\n# name is served to the model in the slot the prompt labels \"your notes from thinking\n# this through\" — the most persuasive position in the whole prompt, filled with text that\n# is not the model's reasoning at all.\n#\n# A pack cannot claim the name: `_build_node` refuses a node whose `output` is one of\n# these. A *run input* with that name is the same hole from the other side, and closing\n# it belongs where inputs enter a run (`graph.run`), not here — this tuple is public so\n# that check has one list to read.\nRESERVED_STATE_NAMES = (\"scratchpad\",)\nDEFAULT_MAX_STEPS = 100\nDEFAULT_MAX_TOKENS = 512\nDEFAULT_THINK_MAX_TOKENS = 256\nDEFAULT_RETRIES = 2\n\n_NODE_KEYS = {\n \"type\", \"output\", \"two_stage\", \"max_tokens\", \"think_max_tokens\", \"retries\",\n \"on_fail\", \"on_unsure\", \"expr\", \"assert\", \"prompt\", \"grammar\", \"tool\",\n \"description\", \"samples\", \"agree\",\n}\n\n# Keys that belong to a generate or an assert node and mean nothing on a tool node. Each\n# is refused by name, with the reason, rather than ignored: a key that reads as if it\n# does something and does nothing is how a pack ends up meaning something other than it\n# says — and on a tool node the thing it silently does not do guards a side effect.\n_TOOL_FORBIDDEN_KEYS = {\n \"prompt\": \"a tool node calls a function, not a model, so there is no prompt \"\n \"to render\",\n \"grammar\": \"a tool node's contract is the tool's own `writes`, declared by the host \"\n \"in its registry, not a grammar file in the pack\",\n \"two_stage\": \"a tool node never generates, so there is no think stage to run\",\n \"retries\": \"a re-run tool is a side effect done twice; route the failure with \"\n \"`on_fail` instead of re-attempting it\",\n \"max_tokens\": \"a tool node never generates\",\n \"think_max_tokens\": \"a tool node never generates\",\n \"assert\": \"`assert:` gates a *generation* before it is committed; a tool node has no \"\n \"retry ladder for a rejection to spend\",\n \"expr\": \"`expr` is the assert node's branch condition\",\n \"samples\": \"the gate compares independent draws from a model; a tool node calls a \"\n \"function, and calling it twice is a side effect done twice, not a \"\n \"second opinion\",\n \"agree\": \"the gate compares independent draws from a model; a tool node calls a \"\n \"function, and calling it twice is a side effect done twice, not a \"\n \"second opinion\",\n}\n_EDGE_KEYS = {\"from\", \"to\", \"when\", \"description\"}\n\n\nclass PackError(Exception):\n \"\"\"Anything wrong with a pack on disk.\"\"\"\n\n\nclass UnsafePath(PackError):\n \"\"\"A pack referenced a file outside its own directory.\n\n A pack is untrusted input the moment it leaves the machine that compiled it\n (docs/ARCHITECTURE.md §6 plans a registry, §7.2 describes copying packs between hosts), so\n every artifact reference must resolve inside the pack root.\n \"\"\"\n\n\nclass MissingArtifactError(PackError):\n \"\"\"A file the pack declares it needs is not there.\"\"\"\n\n\nclass ManifestError(PackError):\n \"\"\"`manifest.yaml` is missing a key or holds the wrong kind of value.\"\"\"\n\n\nclass GraphError(PackError):\n \"\"\"`graph.yaml` describes a graph that cannot be walked.\"\"\"\n\n\nclass GrammarError(PackError):\n \"\"\"A node's grammar file is not a schema stepmold can enforce.\"\"\"\n\n\nclass EvalsetError(PackError):\n \"\"\"`evalset.jsonl` has a line that is not a usable case.\"\"\"\n\n\nclass ToolWiringError(GraphError):\n \"\"\"A tool node is wired to state that nothing in this graph produces.\n\n The alternative is a run that dies at step four because the tool wanted a field\n nobody wrote — by which point the run has already done part of a job it cannot\n finish, and part of a job with side effects in it is the worst place to stop.\n \"\"\"\n\n\n@dataclass(frozen=True)\nclass Node:\n \"\"\"One step of the workflow.\"\"\"\n\n name: str\n type: str\n prompt: Optional[str] = None\n think_prompt: Optional[str] = None\n grammar: Optional[dict] = None\n output: Any = None\n two_stage: bool = False\n max_tokens: int = DEFAULT_MAX_TOKENS\n think_max_tokens: int = DEFAULT_THINK_MAX_TOKENS\n retries: int = DEFAULT_RETRIES\n on_fail: Optional[str] = None\n on_unsure: Optional[str] = None\n expr: Optional[str] = None\n assert_expr: Optional[str] = None\n # The registered name a `type: tool` node calls. A pack names an action; it never\n # contains one (see stepmold/tools.py) — so this is a key into the host's registry and\n # nothing else: no import, no dotted path, no default.\n tool: Optional[str] = None\n # The confidence gate. `samples` is how many independent draws to take, `agree` how\n # many must match before the answer is accepted; disagreement takes `on_unsure`.\n # None means \"not asked for\", which is not the same as 1: `verify.gate_for` reads\n # these to decide whether a node has a gate at all, and every pack written before the\n # keys existed must keep meaning one draw, one answer.\n samples: Optional[int] = None\n agree: Optional[int] = None\n\n\n@dataclass(frozen=True)\nclass Edge:\n \"\"\"A transition, taken when `when` matches the current state (or is unset).\"\"\"\n\n source: str\n target: str\n when: Optional[dict] = None\n\n\n@dataclass(frozen=True)\nclass EvalCase:\n \"\"\"One line of `evalset.jsonl` — the hand-maintained contract.\n\n `expect` compares fields, which is not the whole contract a graph makes. Two fields\n exist because authoring real packs proved that:\n\n * `end` — the ending the run must reach. Field comparison cannot see routing, so a\n pack whose branches project the same shape scored full marks with its policy\n inverted. Naming the ending makes the branch part of the contract.\n * `rescued` — this case is *supposed* to burn a node's ladder and take its `on_fail`\n edge. Without it a declared rescue path could never be a passing expectation, so\n the one path an author most wants to prove was the one the evalset could not score.\n It is checked both ways: a case that claims a rescue and does not get one fails\n too, so it cannot be used to silence a real failure.\n \"\"\"\n\n input: dict\n expect: dict\n name: Optional[str] = None\n end: Optional[str] = None\n rescued: bool = False\n\n\n@dataclass(frozen=True)\nclass Pack:\n \"\"\"A loaded, validated pack. Immutable: a run never edits its own pack.\"\"\"\n\n path: str\n name: str\n version: Any\n entry: str\n model: Optional[str]\n nodes: Dict[str, Node]\n edges: List[Edge]\n evalset: List[EvalCase] = field(default_factory=list)\n max_steps: int = DEFAULT_MAX_STEPS\n manifest: dict = field(default_factory=dict)\n\n def edges_from(self, node_name):\n \"\"\"Outgoing edges for `node_name`, in the order they were declared.\"\"\"\n return [edge for edge in self.edges if edge.source == node_name]\n\n\ndef load_pack(path, tools=None):\n \"\"\"Read the pack at `path`, validate it, and return a `Pack`.\n\n `tools` is the host's `stepmold.tools.ToolRegistry`, and passing it turns on the one\n check this loader cannot do alone: that every `type: tool` node names something the\n host actually registered, and that what each tool declares it `reads` is a field\n this graph will have by the time the node runs. See `check_tools`.\n\n It is optional on purpose. `stepmold validate` on a machine where the tools live in\n somebody else's process must still be able to say the pack is well formed — a check\n that cannot run is not the same as a check that failed.\n \"\"\"\n path = os.path.normpath(path)\n if not os.path.isdir(path):\n # Clipped: this argument is whatever was on the command line, and pasting a\n # ticket where a pack path belongs is a common enough slip that the message\n # must not be a megabyte long.\n raise MissingArtifactError(\"pack directory not found: %s\" % _clip(path))\n\n manifest = _load_yaml(path, \"manifest.yaml\", ManifestError)\n graph = _load_yaml(path, \"graph.yaml\", GraphError)\n\n name = _require(manifest, \"name\", \"manifest.yaml\", str)\n entry = _require(manifest, \"entry\", \"manifest.yaml\", str)\n version = manifest.get(\"version\", 1)\n model = manifest.get(\"model\")\n if model is not None and not isinstance(model, str):\n raise ManifestError(\"manifest.yaml: 'model' must be a string, got %s\"\n % type(model).__name__)\n\n _declared_input_names(manifest)\n\n max_steps = graph.get(\"max_steps\", DEFAULT_MAX_STEPS)\n if not isinstance(max_steps, int) or isinstance(max_steps, bool) or max_steps < 1:\n raise GraphError(\"graph.yaml: 'max_steps' must be a positive integer\")\n\n nodes = _load_nodes(path, graph)\n edges = _load_edges(graph, nodes)\n\n if entry not in nodes:\n raise GraphError(\n \"manifest.yaml: entry node %r is not defined in graph.yaml (nodes: %s)\"\n % (entry, \", \".join(sorted(nodes)) or \"none\")\n )\n _check_reachable_targets(nodes, edges)\n _check_gates(nodes)\n\n evalset = _load_evalset(path)\n _check_case_endings(evalset, nodes)\n\n pack = Pack(\n path=path,\n name=name,\n version=version,\n entry=entry,\n model=model,\n nodes=nodes,\n edges=edges,\n evalset=evalset,\n max_steps=max_steps,\n manifest=manifest,\n )\n if tools is not None:\n check_tools(pack, tools)\n return pack\n\n\n# ------------------------------------------------------------------------ manifest\n\n\ndef _load_yaml(path, filename, error_type):\n full = os.path.join(path, filename)\n if not os.path.isfile(full):\n raise MissingArtifactError(\"%s: required file is missing (%s)\" % (filename, full))\n with open(full, \"r\") as handle:\n text = handle.read()\n try:\n document = parse_yaml(text, filename=filename)\n except YamlError as exc:\n raise error_type(\"%s: %s\" % (filename, exc))\n if document is None:\n document = {}\n if not isinstance(document, dict):\n raise error_type(\"%s: must be a mapping at the top level\" % filename)\n return document\n\n\ndef _require(mapping, key, filename, kind):\n if key not in mapping or mapping[key] is None:\n raise ManifestError(\"%s: missing required key %r\" % (filename, key))\n value = mapping[key]\n if not isinstance(value, kind):\n raise ManifestError(\n \"%s: %r must be a %s, got %s\"\n % (filename, key, kind.__name__, type(value).__name__)\n )\n return value\n\n\n# --------------------------------------------------------------------------- nodes\n\n\ndef _load_nodes(path, graph):\n declared = graph.get(\"nodes\")\n if not declared:\n raise GraphError(\"graph.yaml: declares no nodes\")\n if not isinstance(declared, dict):\n raise GraphError(\"graph.yaml: 'nodes' must be a mapping of name -> node\")\n\n nodes = {}\n for node_name, spec in declared.items():\n if spec is None:\n spec = {}\n if not isinstance(spec, dict):\n raise GraphError(\"graph.yaml: node %r must be a mapping\" % node_name)\n unknown = set(spec) - _NODE_KEYS\n if unknown:\n raise GraphError(\n \"graph.yaml: node %r has unknown key(s): %s\"\n % (node_name, \", \".join(sorted(unknown)))\n )\n node_type = spec.get(\"type\")\n if node_type not in NODE_TYPES:\n raise GraphError(\n \"graph.yaml: node %r has unknown type %r (expected one of %s)\"\n % (node_name, node_type, \", \".join(NODE_TYPES))\n )\n nodes[node_name] = _build_node(path, node_name, node_type, spec)\n return nodes\n\n\ndef _build_node(path, node_name, node_type, spec):\n tool_name = _tool_key(node_name, node_type, spec)\n\n prompt = think_prompt = grammar = None\n # Only a generate node reads artifacts off disk. A tool node deliberately does not\n # fall into this branch: it has no prompt and no grammar, so requiring\n # `prompts/.txt` of it would refuse a pack that is perfectly well formed.\n if node_type == \"generate\":\n prompt = _read_text(path, spec.get(\"prompt\") or \"prompts/%s.txt\" % node_name)\n grammar_relative = spec.get(\"grammar\") or \"grammars/%s.json\" % node_name\n grammar = _read_json(path, grammar_relative)\n try:\n check_schema(grammar)\n except SchemaError as exc:\n raise GrammarError(\"%s: %s\" % (grammar_relative, exc))\n think_relative = \"prompts/%s.think.txt\" % node_name\n if os.path.isfile(_resolve_inside(path, think_relative)):\n think_prompt = _read_text(path, think_relative)\n\n if spec.get(\"output\") in RESERVED_STATE_NAMES:\n raise GraphError(\n \"graph.yaml: node %r has output %r, which is a name stepmold reserves for its \"\n \"own scope — committing there would write the node's answer into the think \"\n \"stage's notes slot\" % (node_name, spec.get(\"output\"))\n )\n\n if node_type == \"assert\" and not spec.get(\"expr\"):\n raise GraphError(\"graph.yaml: assert node %r needs an 'expr'\" % node_name)\n\n return Node(\n name=node_name,\n type=node_type,\n prompt=prompt,\n think_prompt=think_prompt,\n grammar=grammar,\n output=spec.get(\"output\"),\n two_stage=bool(spec.get(\"two_stage\", False)),\n max_tokens=_positive_int(spec, \"max_tokens\", node_name, DEFAULT_MAX_TOKENS),\n think_max_tokens=_positive_int(\n spec, \"think_max_tokens\", node_name, DEFAULT_THINK_MAX_TOKENS\n ),\n retries=_positive_int(spec, \"retries\", node_name, DEFAULT_RETRIES, floor=0),\n on_fail=spec.get(\"on_fail\"),\n on_unsure=spec.get(\"on_unsure\"),\n expr=spec.get(\"expr\"),\n assert_expr=spec.get(\"assert\"),\n tool=tool_name,\n samples=_optional_int(spec, \"samples\", node_name),\n agree=_optional_int(spec, \"agree\", node_name),\n )\n\n\ndef _tool_key(node_name, node_type, spec):\n \"\"\"Validate the `tool:` key both ways round, and return the name a tool node calls.\n\n Both halves are load-time refusals rather than run-time surprises. A tool node\n without a name has nothing to call, and a `tool:` on a generate node is a key the\n walker never reads — it would sit in the pack looking like an action that is never\n taken, which is the most expensive kind of silence a pack can hold.\n \"\"\"\n if node_type != \"tool\":\n if \"tool\" in spec:\n raise GraphError(\n \"graph.yaml: node %r is type %r but carries 'tool: %s'. Only a tool node \"\n \"names a tool — set 'type: tool', or drop the key.\"\n % (node_name, node_type, _clip(spec.get(\"tool\")))\n )\n return None\n\n forbidden = sorted(set(spec) & set(_TOOL_FORBIDDEN_KEYS))\n if forbidden:\n raise GraphError(\n \"graph.yaml: tool node %r carries %s. Those keys belong to a generate or \"\n \"an assert node and nothing would read them here — remove them, or make \"\n \"this a node type that uses them. %s\"\n % (node_name, \", \".join(\"%r\" % key for key in forbidden),\n \" \".join(\"%r: %s.\" % (key, _TOOL_FORBIDDEN_KEYS[key])\n for key in forbidden))\n )\n\n name = spec.get(\"tool\")\n if not isinstance(name, str) or not name.strip():\n raise GraphError(\n \"graph.yaml: tool node %r needs a 'tool:' naming the registered tool it \"\n \"calls (got %r). A pack names an action; the host registers it.\"\n % (node_name, name)\n )\n\n output = spec.get(\"output\")\n if output is not None and (not isinstance(output, str) or not output):\n # Same shape as a generate node's `output:`, for the same reason: it is the one\n # state key the result is committed under. A list here would read like an end\n # node's projection and commit under no key at all.\n raise GraphError(\n \"graph.yaml: tool node %r: 'output' must be a single state key to commit \"\n \"the tool's result under (a string), got %r\" % (node_name, output)\n )\n return name.strip()\n\n\ndef _optional_int(spec, key, node_name):\n \"\"\"A key that may be absent entirely, and must be a whole number when it is not.\n\n Distinct from `_positive_int`, which substitutes a default: for the gate keys \"absent\"\n is a third state that has to survive to `verify.gate_for`, because a node that never\n asked for a gate must keep behaving exactly as it did before the keys existed.\n \"\"\"\n if key not in spec:\n return None\n value = spec[key]\n if not isinstance(value, int) or isinstance(value, bool) or value < 1:\n raise GraphError(\n \"graph.yaml: node %r: %r must be an integer >= 1, not %r\"\n % (node_name, key, value)\n )\n return value\n\n\ndef _positive_int(spec, key, node_name, default, floor=1):\n value = spec.get(key, default)\n if not isinstance(value, int) or isinstance(value, bool) or value < floor:\n raise GraphError(\n \"graph.yaml: node %r: %r must be an integer >= %d\" % (node_name, key, floor)\n )\n return value\n\n\ndef _clip(text, limit=120):\n \"\"\"Keep a message bounded — the offending text is usually not ours.\"\"\"\n text = \" \".join(str(text).split())\n return text if len(text) <= limit else text[:limit] + \"...\"\n\n\ndef _resolve_inside(path, relative):\n \"\"\"Resolve `relative` against the pack root, refusing anything that escapes it.\n\n Rejects absolute paths (os.path.join silently discards the root for those), `..`\n traversal, and symlinks pointing outside — realpath resolves links on both sides, so\n a symlinked artifact is caught by the same containment check.\n \"\"\"\n if not isinstance(relative, str) or not relative:\n raise UnsafePath(\"artifact reference must be a non-empty string\")\n if os.path.isabs(relative) or os.path.splitdrive(relative)[0]:\n raise UnsafePath(\n \"%s: absolute paths are not allowed in a pack\" % _clip(relative)\n )\n root = os.path.realpath(path)\n full = os.path.realpath(os.path.join(root, relative))\n if full != root and not full.startswith(root + os.sep):\n raise UnsafePath(\"%s: resolves outside the pack directory\" % _clip(relative))\n return full\n\n\ndef _read_text(path, relative):\n full = _resolve_inside(path, relative)\n if not os.path.isfile(full):\n raise MissingArtifactError(\n \"%s: required file is missing (%s)\" % (_clip(relative), _clip(full))\n )\n with open(full, \"r\") as handle:\n return handle.read()\n\n\ndef _read_json(path, relative):\n text = _read_text(path, relative)\n try:\n return json.loads(text)\n except ValueError as exc:\n raise PackError(\"%s: is not valid JSON (%s)\" % (relative, exc))\n\n\n# --------------------------------------------------------------------------- edges\n\n\ndef _load_edges(graph, nodes):\n declared = graph.get(\"edges\") or []\n if not isinstance(declared, list):\n raise GraphError(\"graph.yaml: 'edges' must be a list\")\n\n edges = []\n for index, spec in enumerate(declared, start=1):\n if not isinstance(spec, dict):\n raise GraphError(\"graph.yaml: edge %d must be a mapping\" % index)\n unknown = set(spec) - _EDGE_KEYS\n if unknown:\n raise GraphError(\n \"graph.yaml: edge %d has unknown key(s): %s\"\n % (index, \", \".join(sorted(unknown)))\n )\n source, target = spec.get(\"from\"), spec.get(\"to\")\n for role, value in ((\"from\", source), (\"to\", target)):\n if not isinstance(value, str) or not value:\n raise GraphError(\"graph.yaml: edge %d is missing %r\" % (index, role))\n for role, value in ((\"from\", source), (\"to\", target)):\n if value not in nodes:\n raise GraphError(\n \"graph.yaml: edge %s -> %s points at undefined node %r\"\n % (source, target, value)\n )\n when = spec.get(\"when\")\n if when is not None and not isinstance(when, dict):\n raise GraphError(\n \"graph.yaml: edge %s -> %s: 'when' must be a mapping of \"\n \"state key -> expected value\" % (source, target)\n )\n if nodes[source].type == \"end\":\n raise GraphError(\n \"graph.yaml: end node %r cannot have an outgoing edge\" % source\n )\n edges.append(Edge(source=source, target=target, when=when))\n return edges\n\n\ndef _check_gates(nodes):\n \"\"\"Settle every node's confidence gate at load, not on the draw that trips it.\n\n Two refusals, both about a pack meaning something other than it says.\n\n `gate_for` already rejects an impossible gate — agree above samples, agree on a single\n draw — but it does so when the node runs, which on a branch that is rarely taken can\n be a long way from the edit that caused it. Calling it here moves every one of those\n to `stepmold validate`.\n\n And an `on_unsure` with no `samples` is an edge nothing can ever take. That was true of\n every pack until these keys existed, and the documentation said so; now that a pack can\n ask for a gate, an `on_unsure` without one is a mistake rather than a limitation.\n \"\"\"\n from .verify import GateError, gate_for\n\n for node in nodes.values():\n if node.type != \"generate\":\n continue\n try:\n samples, _ = gate_for(node)\n except GateError as exc:\n raise GraphError(\"graph.yaml: %s\" % exc)\n if node.on_unsure and samples == 1:\n raise GraphError(\n \"graph.yaml: node %r has an 'on_unsure' edge but draws one sample, so \"\n \"nothing can ever make it unsure and that edge can never be taken. Add \"\n \"'samples: 3' (or more) to give it a gate, or remove 'on_unsure'.\"\n % node.name\n )\n\n\ndef _check_reachable_targets(nodes, edges):\n for node in nodes.values():\n # `on_fail` and `on_unsure` are both edges the walk can take without an entry in\n # `edges:`, so both are checked here or nowhere.\n for key, target in ((\"on_fail\", node.on_fail), (\"on_unsure\", node.on_unsure)):\n if target is not None and target not in nodes:\n raise GraphError(\n \"graph.yaml: node %r has %s %r, which is not a defined node\"\n % (node.name, key, target)\n )\n if node.type == \"end\":\n continue\n if not any(edge.source == node.name for edge in edges):\n raise GraphError(\n \"graph.yaml: node %r has no outgoing edge and is not an end node\"\n % node.name\n )\n\n\n# --------------------------------------------------------------------------- tools\n\n\ndef check_tools(pack, tools):\n \"\"\"Check every `type: tool` node in `pack` against the host's registry.\n\n Two questions, both of which have a right answer before the run starts:\n\n * **Is the tool there?** A name the host never registered is refused here rather\n than at the step that would have called it. `stepmold/tools.py` builds the allowlist\n that way on purpose — a pack can only call what the host already handed it — and\n an allowlist that is checked halfway through a job is not one.\n * **Can the tool's `reads` be satisfied?** A tool is invoked with exactly the state\n it declared it needs (`Tool.invoke`), so a field that no earlier node writes and\n that no caller supplies is a wiring mistake with a name. Finding it at load turns\n \"the run died at step 4 because the tool wanted `order_id`\" into \"this pack is\n wired wrong, here is the field\".\n\n What counts as \"the graph will have it by then\", at any earlier node:\n\n | Source | The state keys it contributes |\n | --- | --- |\n | a node with `output:` | the one key it commits under |\n | a generate node without one | its grammar's property names (merge mode) |\n | a tool node without one | the registered tool's `writes` |\n | the run's own inputs | keys an evalset case supplies, or the manifest's `inputs:` |\n\n \"Earlier\" is any node the walk can reach this one from — down any branch, round any\n loop, along any rescue path. That is deliberately generous: this check exists to\n catch the field *nobody* writes, and reporting a field that merely *might* not be\n written on some branch would make it the kind of check people switch off. The one\n node it will not credit is one whose `on_fail` leads here, because a node that\n failed committed nothing at all (`_links`).\n\n For the same reason it stays quiet where it cannot be sure. A pack that declares no\n inputs anywhere (no evalset, no manifest `inputs:`) says nothing about what the\n caller passes, and an earlier node whose grammar declares no properties can write\n anything at all; in either case an unknown field is unproven, not wrong.\n\n Raises `stepmold.tools.ToolNotRegistered` for a name the registry does not hold, and\n `ToolWiringError` for a field nothing produces.\n \"\"\"\n tool_nodes = [node for node in pack.nodes.values() if node.type == \"tool\"]\n if not tool_nodes:\n return\n if not (hasattr(tools, \"get\") and hasattr(tools, \"has\")):\n # A plain dict would answer `get(name, node_name)` with the node name and sail\n # straight past the registration check, so refuse the shape rather than trust it.\n raise TypeError(\n \"tools must be a stepmold.tools.ToolRegistry (got %s)\" % type(tools).__name__\n )\n\n # Every name first: an unregistered tool is the more basic mistake, and reporting it\n # before a wiring complaint keeps the two from being confused for each other.\n registered = {node.name: tools.get(node.tool, node.name) for node in tool_nodes}\n\n declared_inputs = _declared_inputs(pack)\n committed, lost = _links(pack)\n live = _walk(pack.entry, _merged(committed, lost))\n preceding, rescued_from = _reverse(committed), _reverse(lost)\n\n for node in tool_nodes:\n if node.name not in live:\n # Unreachable from the entry node, so it never runs and has no \"earlier\"\n # to speak of. That is a graph problem, not a tool problem.\n continue\n tool = registered[node.name]\n if not tool.reads:\n continue\n earlier = _earlier(node.name, preceding, rescued_from) & live\n available, complete = _available_before(pack, earlier, registered)\n if not complete or declared_inputs is None:\n continue\n missing = [field for field in tool.reads\n if field not in available and field not in declared_inputs]\n if missing:\n raise ToolWiringError(\n \"graph.yaml: tool node %r calls tool %r, which reads %s — and nothing \"\n \"writes %s before this node runs. Earlier nodes write: %s. The run \"\n \"inputs this pack declares are: %s. Give an earlier node an 'output:' \"\n \"that names the field, add it to the pack's inputs (an evalset case, or \"\n \"manifest 'inputs:'), or call a tool that reads what this graph has.\"\n % (node.name, tool.name, \", \".join(repr(f) for f in sorted(missing)),\n \"it\" if len(missing) == 1 else \"them\",\n \", \".join(sorted(available)) or \"nothing\",\n \", \".join(sorted(declared_inputs)) or \"none\")\n )\n\n\ndef _declared_inputs(pack):\n \"\"\"Every state key the caller is known to supply, or None if the pack never says.\n\n Two sources, both of them the pack's own text: the manifest's optional `inputs:`\n list, and the keys of each evalset case's `input` object. None — \"this pack declares\n nothing\" — is not the same as an empty set, and only the empty set is evidence.\n \"\"\"\n names = _declared_input_names(pack.manifest)\n if names is None and not pack.evalset:\n return None\n declared = set(names or ())\n for case in pack.evalset:\n declared.update(case.input)\n return declared\n\n\ndef _declared_input_names(manifest):\n \"\"\"The manifest's optional `inputs:` list, validated.\n\n Unknown manifest keys are kept rather than refused (docs/pack-format.md), but this\n one is read, so a value of the wrong shape would quietly declare nothing — and the\n whole point of declaring inputs is to be believed.\n \"\"\"\n names = manifest.get(\"inputs\")\n if names is None:\n return None\n if not isinstance(names, list) or not all(\n isinstance(name, str) and name for name in names\n ):\n raise ManifestError(\n \"manifest.yaml: 'inputs', when present, must be a list of the state key \"\n \"names a caller supplies to a run, got %s\" % _clip(names)\n )\n return list(names)\n\n\ndef _links(pack):\n \"\"\"The graph's transitions, split by whether the node they leave got to commit.\n\n Two maps, both node name -> the nodes it can move to:\n\n * **committed** — ordinary `edges:`, and `on_unsure`. A node reached this way ran to\n completion, so whatever it writes is in state.\n * **lost** — `on_fail`. A node whose ladder ran out committed *nothing*: the\n rejected output is dropped and never touches state (`graph.run`). Its fields are\n not available to what it diverts to, though its own predecessors' fields are.\n\n `on_unsure` sits with the first group deliberately. Being unsure about a value is not\n the same as not having produced one, and assuming a loss here would invent wiring\n errors in packs that route a low-confidence result onward for review.\n \"\"\"\n committed = dict((name, set()) for name in pack.nodes)\n lost = dict((name, set()) for name in pack.nodes)\n for edge in pack.edges:\n committed[edge.source].add(edge.target)\n for node in pack.nodes.values():\n if node.on_unsure in pack.nodes:\n committed[node.name].add(node.on_unsure)\n if node.on_fail in pack.nodes:\n lost[node.name].add(node.on_fail)\n return committed, lost\n\n\ndef _merged(committed, lost):\n return dict((name, committed[name] | lost[name]) for name in committed)\n\n\ndef _reverse(following):\n reversed_map = dict((name, set()) for name in following)\n for name, targets in following.items():\n for target in targets:\n reversed_map[target].add(name)\n return reversed_map\n\n\ndef _earlier(node_name, preceding, rescued_from):\n \"\"\"Every node whose writes are in state by the time `node_name` runs.\n\n Walked backwards from the node's predecessors, not from the node itself — so a node\n inside a loop counts as its own ancestor (its earlier pass really did write those\n fields) while a node outside one does not (its own writes come too late).\n\n A node reached backwards through its `on_fail` is walked *past* rather than counted:\n the run took that edge precisely because the node produced nothing.\n \"\"\"\n counted, seen = set(), set()\n queue = [(node_name, False)]\n while queue:\n name, writes_landed = queue.pop()\n if (name, writes_landed) in seen:\n continue\n seen.add((name, writes_landed))\n if writes_landed:\n counted.add(name)\n queue.extend((previous, True) for previous in preceding.get(name, ()))\n queue.extend((previous, False) for previous in rescued_from.get(name, ()))\n return counted\n\n\ndef _walk(start, links):\n \"\"\"Everything reachable from `start` through `links`, `start` itself included.\"\"\"\n seen, queue = set(), [start]\n while queue:\n name = queue.pop()\n if name in seen:\n continue\n seen.add(name)\n queue.extend(links.get(name, ()))\n return seen\n\n\ndef _available_before(pack, earlier, registered):\n \"\"\"(state keys those nodes write, whether that set is the whole story).\"\"\"\n available = set()\n complete = True\n for name in earlier:\n keys, known = _node_writes(pack.nodes[name], registered)\n available.update(keys)\n complete = complete and known\n return available, complete\n\n\ndef _node_writes(node, registered):\n \"\"\"What one node commits into state, and whether that can be known from the pack.\n\n A generate node with no `output:` merges its generated object into state, so its\n state keys are its grammar's property names — unless the grammar declares no\n properties, in which case the node may write anything and this returns \"unknown\"\n rather than \"nothing\". Same for a tool node whose tool declares no `writes`.\n \"\"\"\n if node.type not in (\"generate\", \"tool\"):\n # assert and end nodes cannot write state at all (docs/graph.md, \"Node types\").\n return set(), True\n if isinstance(node.output, str) and node.output:\n return {node.output}, True\n if node.output:\n # An `output:` of a shape `commit` cannot use as a state key. The CLI refuses\n # that pack outright (`cli._check_output_shapes`); here it simply means this\n # node's writes are not something to draw a conclusion from.\n return set(), False\n if node.type == \"generate\":\n properties = (node.grammar or {}).get(\"properties\")\n if isinstance(properties, dict) and properties:\n return set(properties), True\n return set(), False\n tool = registered.get(node.name)\n if tool is not None and tool.writes:\n return set(tool.writes), True\n return set(), False\n\n\n# ------------------------------------------------------------------------ evalset\n\n\ndef _case_end(raw, number):\n \"\"\"The ending a case must reach, or None. Validated against the graph by the caller.\"\"\"\n value = raw.get(\"end\")\n if value is None:\n return None\n if not isinstance(value, str) or not value:\n raise EvalsetError(\n \"evalset.jsonl line %d: 'end' must be the name of an end node\" % number\n )\n return value\n\n\ndef _case_flag(raw, key, number):\n value = raw.get(key, False)\n if not isinstance(value, bool):\n raise EvalsetError(\n \"evalset.jsonl line %d: %r must be true or false\" % (number, key)\n )\n return value\n\n\ndef _check_case_endings(cases, nodes):\n \"\"\"Every `end:` a case names must be a real ending in this graph.\n\n A typo would otherwise never match and quietly fail every run of that case, which is\n the same silent-wrongness the field exists to remove.\n \"\"\"\n for case in cases:\n if case.end is None:\n continue\n node = nodes.get(case.end)\n if node is None:\n raise EvalsetError(\n \"evalset.jsonl: case %r expects ending %r, which is not a node in \"\n \"graph.yaml\" % (case.name, case.end)\n )\n if node.type != \"end\":\n raise EvalsetError(\n \"evalset.jsonl: case %r expects ending %r, but that node is type %r, \"\n \"not 'end'\" % (case.name, case.end, node.type)\n )\n\n\ndef _load_evalset(path):\n full = os.path.join(path, \"evalset.jsonl\")\n if not os.path.isfile(full):\n return []\n cases = []\n with open(full, \"r\") as handle:\n for number, line in enumerate(handle, start=1):\n if not line.strip():\n continue\n try:\n raw = json.loads(line)\n except ValueError as exc:\n raise EvalsetError(\"evalset.jsonl:%d: not valid JSON (%s)\" % (number, exc))\n if not isinstance(raw, dict):\n raise EvalsetError(\"evalset.jsonl:%d: each line must be an object\" % number)\n for key in (\"input\", \"expect\"):\n if not isinstance(raw.get(key), dict):\n raise EvalsetError(\n \"evalset.jsonl:%d: missing or non-object %r\" % (number, key)\n )\n cases.append(\n EvalCase(\n input=raw[\"input\"],\n expect=raw[\"expect\"],\n name=raw.get(\"name\") or \"case %d\" % number,\n end=_case_end(raw, number),\n rescued=_case_flag(raw, \"rescued\", number),\n )\n )\n return cases\n", "stepmold/render.py": "\"\"\"Prompt templating: `{var}` and `{a.b}`, substituted from run state.\n\nDeliberately *not* `str.format`. Prompts routinely contain literal JSON (`{\"a\": 1}`) —\nwhich `str.format` treats as a field — and `str.format` also resolves attributes and\nindexes, which is more machinery than a prompt template should have. This does one thing:\nlook a name up in state, render it as text.\n\n`{{` and `}}` are literal braces, so a prompt can show the model an example object.\n\nSubstitution is a single `re.sub` pass and the result is never re-scanned. That is the\nload-bearing property, not an implementation detail: run state holds every value the\nworkflow has seen, so a second pass would let a ticket reading `{card_number}` print\nanother state key into the prompt — input reading state it was never shown. Tests in\ntests/production/test_adversarial.py pin it.\n\"\"\"\n\nimport json\nimport re\n\nfrom .errors import MissingVariable\n\n__all__ = [\"render\"]\n\n_TOKEN = re.compile(\n r\"\\{\\{|\\}\\}|\\{([A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*)\\}\"\n)\n\n\ndef render(template, state):\n \"\"\"Return `template` with every `{name}` replaced by its value from `state`.\"\"\"\n\n def substitute(match):\n if match.group(0) == \"{{\":\n return \"{\"\n if match.group(0) == \"}}\":\n return \"}\"\n return as_text(_lookup(match.group(1), state))\n\n return _TOKEN.sub(substitute, template)\n\n\ndef as_text(value):\n \"\"\"Render a state value for inclusion in a prompt.\"\"\"\n if isinstance(value, str):\n return value\n return json.dumps(value, sort_keys=False)\n\n\ndef _lookup(path, state):\n current = state\n for part in path.split(\".\"):\n if not isinstance(current, dict) or part not in current:\n raise MissingVariable(\n \"prompt needs {%s} but state has %s\" % (_clip(path), _names(state))\n )\n current = current[part]\n return current\n\n\ndef _names(state):\n \"\"\"The state keys, repr'd — because the confusing case is an invisible difference.\n\n A key holding a zero-width space renders identically to the real one, so a plain\n list says \"prompt needs {ticket} but state has ticket\" and the operator concludes\n stepmold is broken. repr writes such a character as an escape, so the difference shows.\n Keys are caller-supplied, so the list is clipped too: a run input can be as long as\n whoever pasted it.\n \"\"\"\n if not state:\n return \"nothing\"\n return _clip(\", \".join(repr(name) for name in sorted(state)), 200)\n\n\ndef _clip(text, limit=120):\n \"\"\"Keep a message bounded. A megabyte of input must not become a megabyte of error.\"\"\"\n text = \" \".join(str(text).split())\n return text if len(text) <= limit else text[:limit] + \"...\"\n", "stepmold/state.py": "\"\"\"Checkpoints: a run that dies at node 17 resumes at node 17.\n\nLong workflows are the whole point of stepmold, and a workflow that restarts from zero on any\nfailure is a workflow you cannot run on real volume (docs/ARCHITECTURE.md §3). So state is written\nto SQLite after every node that completes, keyed by run id, and `resume` picks the walk up\nat the node the crash interrupted.\n\nSQLite because it is in the standard library, it is a real database with real durability,\nand a client can open the file with tools they already have. ARCHITECTURE.md §7 lists Postgres as\nthe option for later; nothing here is SQLite-specific beyond `Store`.\n\n`Store` knows nothing about walking a graph, and the walker knows nothing about SQL — it\njust calls `store.save(...)` with keywords. That is what keeps these two modules from\nimporting each other.\n\nTwo contracts hold this together, and both are enforced rather than hoped for:\n\n* **A checkpoint round-trips.** What `latest` returns is what `save` was handed, type for\n type. JSON does not preserve every Python value — a tuple comes back a list, an int\n dict key comes back a string, a dict mixing key types cannot be sorted at all — so a\n value that would change shape is refused at the door instead of corrupting the run it\n is supposed to rescue. Only strict JSON is written: NaN and Infinity are Python's\n extensions to the format, and a file carrying them is unreadable by any conforming\n reader, including the other-language runtimes ARCHITECTURE.md §7 leaves room for.\n* **A run resumes under the pack that started it.** The checkpoint records which pack\n wrote it, and `resume` refuses a pack that disagrees. Resuming under a different graph\n skips nodes that were inserted since and trusts nodes that were rewritten, which turns\n a crash into wrong output rather than a late one.\n* **A tool call that already happened is never made again.** Replaying state cannot tell\n a resumer whether the email went out, because state records the *result* of a call and\n not the fact of it. So a checkpoint carries `tool_calls` as well: the node, the\n arguments it was handed and what it returned, written down the moment the call returns\n and cleared once the walk has left the node. `graph.run` reads it and replays instead\n of calling. This is deliberately not an audit log of every call a run ever made — the\n checkpoint chain already is one, and a list that only grew would put back the quadratic\n term the delta encoding below exists to remove.\n\nConcurrency\n-----------\n\nA deployed stepmold is a pool of workers over one store file, and every operation here is\nwritten for that rather than for the single-threaded in-process case it grew up in.\n\n* **A `Store` is safe to share between threads and between processes.** The connection is\n opened with `check_same_thread=False` and every statement runs under one lock, so the\n obvious deployment — one `Store`, a thread pool — works instead of raising\n `sqlite3.ProgrammingError` out of the first `save`. Across processes the file locking\n does the same job; the journal is WAL so a reader is never shut out by a writer.\n* **The first checkpoint of a run claims its run id, atomically.** Checking\n `latest(run_id)` and then walking is a read-then-write: two runs that start together\n both see an empty store and weld their chains into one. The claim is a row in `runs`\n with `run_id` as the primary key, taken inside the same transaction as the checkpoint,\n so the loser of a race is refused with `RunIdInUse` and writes nothing.\n* **Resuming an unfinished run takes a lease.** Two supervisors retrying the same resume\n would otherwise both replay from the same checkpoint and both execute every remaining\n node — twice the charges, twice the emails. `Store.lease` is a claim with an expiry, so\n a resumer that dies holding one does not wedge the run forever.\n* **Contention arrives as a `StepmoldError`.** sqlite's busy handler retries for `timeout`\n seconds; past that the raw `sqlite3.OperationalError` is wrapped in `StoreBusy`, which\n names the run and the node, so `except StepmoldError` around a run keeps working.\n\nSize and retention\n------------------\n\nA checkpoint stores what changed at that node, not the whole of state, so an N-node run\ncosts bytes linear in N instead of quadratic. A full snapshot is written again whenever\nthe deltas since the last one would cost more to read than the snapshot would, which\nbounds rebuilding a state of size S at roughly 2S bytes read — reconstruction is an\nimplementation detail, `latest` and `history` still hand back whole `Checkpoint` objects.\n\nNothing is deleted on stepmold's own initiative: a checkpoint chain is an audit trail, and a\nstore that quietly forgot last month's runs would be worse than one that grows. Retention\nis the operator's call, and `prune` plus `vacuum` are how they make it — drop finished\nruns older than a date or beyond a count, then give the pages back to the filesystem.\n\"\"\"\n\nimport contextlib\nimport json\nimport math\nimport os\nimport sqlite3\nimport threading\nimport time\nimport uuid\nfrom dataclasses import dataclass, field\nfrom datetime import datetime, timezone\nfrom typing import Any, Dict, List, Optional\n\nfrom .errors import RunError, RunIdInUse, UnknownRun\nfrom .log import DEBUG, INFO, WARNING, event, get_logger\n\n_log = get_logger(\"state\")\n\n__all__ = [\n \"Checkpoint\",\n \"CheckpointMismatch\",\n \"ResumeInProgress\",\n \"Store\",\n \"StoreBusy\",\n \"resume\",\n]\n\n\nclass CheckpointMismatch(RunError):\n \"\"\"The checkpoint being resumed was written by a different pack than the one given.\n\n Lives here rather than in `stepmold.errors` for the same reason the pack-loading errors\n live in `stepmold.pack`: it is raised before the walk restarts, by the store's own\n bookkeeping, and nothing in the walker can produce it.\n \"\"\"\n\n\nclass StoreBusy(RunError):\n \"\"\"The store stayed locked for longer than its busy timeout.\n\n Raised instead of the bare `sqlite3.OperationalError`, which is not a `StepmoldError` and\n names neither the run nor the node — so a caller wrapping its runs in\n `except StepmoldError` was shown a traceback about a database it never opened.\n \"\"\"\n\n\nclass ResumeInProgress(RunError):\n \"\"\"Another resumer holds this run's lease.\n\n Two supervisors resuming one unfinished run both replay from the same checkpoint and\n both execute every remaining node. The second one is refused rather than allowed to\n do the work twice.\n \"\"\"\n\n\nSCHEMA = \"\"\"\nCREATE TABLE IF NOT EXISTS checkpoints (\n run_id TEXT NOT NULL,\n step INTEGER NOT NULL,\n node TEXT NOT NULL,\n next_node TEXT,\n state TEXT NOT NULL,\n path TEXT NOT NULL,\n provenance TEXT NOT NULL,\n failures TEXT NOT NULL,\n output TEXT,\n pack TEXT,\n pack_version TEXT,\n state_kind TEXT,\n attempts TEXT,\n tool_calls TEXT,\n created_at TEXT NOT NULL,\n PRIMARY KEY (run_id, step)\n);\n\nCREATE TABLE IF NOT EXISTS runs (\n run_id TEXT PRIMARY KEY,\n owner TEXT NOT NULL,\n claimed_at TEXT NOT NULL,\n lease_owner TEXT,\n lease_expires REAL\n);\n\"\"\"\n\n# Columns added after the first release. A store file written by an older stepmold has the\n# table already, so CREATE TABLE IF NOT EXISTS silently leaves it short a column and\n# every read of that column fails. Adding them on open keeps old files readable.\n_ADDED_COLUMNS = ((\"pack_version\", \"TEXT\"), (\"state_kind\", \"TEXT\"),\n (\"attempts\", \"TEXT\"), (\"tool_calls\", \"TEXT\"))\n\n#: The walker's first checkpoint of a fresh run. `graph.run` starts its step counter at\n#: zero and increments before the first node, so step 1 is the moment a run id is taken\n#: and the only write that has to fight for it.\n_FIRST_STEP = 1\n\n#: Seconds sqlite may spend retrying a locked database before `save` gives up. Higher\n#: than sqlite3's own 5s default because a stepmold store is written by a fleet and may sit on\n#: a slow or networked filesystem; `Store(path, timeout=...)` is the knob.\nDEFAULT_TIMEOUT = 30.0\n\n#: How long a resume lease is honoured before another resumer may take it. A resumer that\n#: exits normally releases it immediately; this only covers one that died holding it, so\n#: it is long enough that a slow run is never overtaken by its own retry.\nDEFAULT_LEASE = 300.0\n\n\n@dataclass\nclass Checkpoint:\n \"\"\"The run, frozen after one node completed.\"\"\"\n\n run_id: str\n step: int\n node: str\n next_node: Optional[str]\n state: Dict[str, Any] = field(default_factory=dict)\n path: List[str] = field(default_factory=list)\n provenance: Dict[str, str] = field(default_factory=dict)\n failures: List[dict] = field(default_factory=list)\n output: Optional[Dict[str, Any]] = None\n pack: Optional[str] = None\n pack_version: Optional[str] = None\n attempts: Dict[str, int] = field(default_factory=dict)\n #: Tool calls this run has made but has not yet finished leaving the node for. Empty\n #: on all but the moment between a call returning and its node being walked out of —\n #: which is precisely the window a crash would otherwise turn into a second call.\n tool_calls: List[dict] = field(default_factory=list)\n created_at: Optional[str] = None\n\n @property\n def finished(self):\n \"\"\"True when this checkpoint is the end of the run, not a pause in it.\"\"\"\n return self.next_node is None\n\n\nclass Store:\n \"\"\"Run checkpoints in a SQLite file (or `:memory:` for tests).\n\n Safe to share between threads and between processes; see the module docstring for\n what that costs and what it buys.\n \"\"\"\n\n def __init__(self, path=\":memory:\", timeout=DEFAULT_TIMEOUT):\n self.path = path\n self.timeout = float(timeout)\n #: Identifies this Store among everything else touching the file. A run id is\n #: claimed by an owner, so re-saving a step is allowed to the writer that already\n #: holds the run and refused to anyone else.\n self._owner = uuid.uuid4().hex\n self._lock = threading.RLock()\n #: run_id -> (step, frame) for the last checkpoint this Store wrote, so the usual\n #: case — a walk saving step after step — computes its delta without re-reading\n #: the chain. Keyed by step, so a stale entry is ignored rather than trusted.\n self._recent = {}\n if path != \":memory:\":\n directory = os.path.dirname(os.path.abspath(path))\n if directory:\n # exist_ok, because a fleet cold-starting on a new store directory has\n # every worker but one arrive after it exists. `isdir` then `makedirs` is\n # a read-then-write and loses that race.\n os.makedirs(directory, exist_ok=True)\n self._connection = sqlite3.connect(\n path,\n timeout=self.timeout,\n # The store is shared; one lock around every statement is what makes that\n # safe, and it is cheaper than a connection per thread on a file this small.\n check_same_thread=False,\n # Autocommit, so a claim and its checkpoint can be one explicit\n # BEGIN IMMEDIATE ... COMMIT rather than whatever sqlite3 decides to open.\n isolation_level=None,\n )\n self._connection.row_factory = sqlite3.Row\n self._connection.execute(\"PRAGMA busy_timeout = %d\" % int(self.timeout * 1000))\n if path != \":memory:\":\n # WAL so a reader — `history` over a large store, a backup — never blocks the\n # writer, and the writer never blocks it. Meaningless for `:memory:`.\n self._enable_wal()\n self._connection.executescript(SCHEMA)\n self._migrate()\n\n def _enable_wal(self):\n \"\"\"Switch the file to WAL, tolerating another opener holding it right now.\n\n `PRAGMA journal_mode=WAL` wants the file to itself for a moment and answers\n SQLITE_BUSY without ever consulting the busy handler, so a fleet cold-starting on\n one store has openers that collide over it. The journal mode belongs to the file\n rather than to this connection: whoever wins sets it for everyone, and a loser\n left on the rollback journal is slower, not wrong. Refusing to open a perfectly\n good store over that would be the worse trade, so this retries briefly and then\n carries on.\n \"\"\"\n deadline = time.monotonic() + min(self.timeout, 1.0)\n while True:\n try:\n self._connection.execute(\"PRAGMA journal_mode=WAL\")\n return\n except sqlite3.OperationalError as exc:\n if \"locked\" not in str(exc).lower() and \"busy\" not in str(exc).lower():\n raise\n if time.monotonic() >= deadline:\n return\n time.sleep(0.005)\n\n def _migrate(self):\n \"\"\"Add columns a store file written by an older stepmold is missing.\"\"\"\n for column, declared_type in _ADDED_COLUMNS:\n _add_column(self._connection, column, declared_type)\n\n def save(self, run_id, step, node, next_node, state, path=None, provenance=None,\n failures=None, output=None, pack=None, pack_version=None, attempts=None,\n tool_calls=None):\n \"\"\"Record one completed node. Re-saving the same step replaces it.\n\n `pack` is the pack's identity: either its name, or the pack itself, in which case\n its version is recorded too and `resume` can catch a graph that moved on under a\n run. Every field is checked before anything is written, so a value JSON would\n change on the way back raises here and leaves no half-written checkpoint.\n\n The first checkpoint of a run claims its run id in the same transaction that\n writes the checkpoint; a second run under a live id raises `RunIdInUse` here\n rather than quietly welding itself onto the first one's chain.\n\n Steps are assumed to arrive in order within a run — that is what the walker does,\n and what lets a checkpoint record only the state its node changed. Rewriting a\n step that already has successors is the one thing that would leave those\n successors describing a state that no longer precedes them.\n\n `tool_calls` is how a side effect survives a crash without being repeated: the\n walker saves the same step twice around a tool node, once with the call recorded\n and the walk still standing on the node, then again once the node has been left\n and the call is settled. Re-saving a step replaces it, so only the second row\n survives a run that got that far.\n \"\"\"\n name, version = _identity(pack, pack_version)\n # Validate and serialise before opening a transaction: a value that cannot be\n # checkpointed must leave the store exactly as it was, lock and all.\n snapshot = (\n _dump(state, \"state\"),\n _dump(list(path or []), \"path\"),\n _dump(dict(provenance or {}), \"provenance\"),\n )\n tail = (\n _dump(list(failures or []), \"failures\"),\n None if output is None else _dump(output, \"output\"),\n name,\n version,\n )\n # Out here with the rest for the reason above: a tool result JSON cannot hold is\n # refused before a lock is taken, not halfway through a write.\n calls = _dump(list(tool_calls or []), \"tool_calls\")\n created_at = datetime.now(timezone.utc).isoformat(timespec=\"seconds\")\n\n with self._lock, self._transaction(run_id, step, node):\n self._claim(run_id, step)\n kind, blobs = self._encode(run_id, step, snapshot)\n self._connection.execute(\n \"INSERT OR REPLACE INTO checkpoints \"\n \"(run_id, step, node, next_node, state, path, provenance, failures, \"\n \" output, pack, pack_version, state_kind, attempts, tool_calls, \"\n \" created_at) \"\n \"VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)\",\n (run_id, step, node, next_node) + blobs + tail\n + (kind, _dump(dict(attempts or {}), \"attempts\"), calls, created_at),\n )\n # Only once the transaction committed: a cache entry for a row that was rolled\n # back would describe a chain the file does not have.\n self._recent[run_id] = (step, _parse(snapshot))\n # DEBUG rather than INFO on purpose. This fires exactly once per node that\n # completes, so at INFO it would double the volume of a run's log to repeat what\n # `graph`'s own `node.ok` already said — while the fact an operator actually\n # wants at INFO, \"is this run checkpointed at all\", is answered once by\n # `run.claimed` below. Delta-vs-full and the byte count are here because they are\n # the two numbers behind a store that is growing faster than it should.\n if _log.isEnabledFor(DEBUG):\n event(_log, DEBUG, \"checkpoint.saved\", run_id=run_id, step=step, node=node,\n next_node=next_node, kind=kind, state_bytes=len(snapshot[0]),\n finished=next_node is None)\n\n def latest(self, run_id):\n \"\"\"The most recent checkpoint for `run_id`, or None.\"\"\"\n with self._lock:\n row = self._connection.execute(\n \"SELECT * FROM checkpoints WHERE run_id = ? ORDER BY step DESC LIMIT 1\",\n (run_id,),\n ).fetchone()\n if row is None:\n return None\n return _to_checkpoint(row, self._read_frame(run_id, row[\"step\"]))\n\n def history(self, run_id):\n \"\"\"Every checkpoint for `run_id`, oldest first — the run's audit trail.\"\"\"\n with self._lock:\n rows = self._connection.execute(\n \"SELECT * FROM checkpoints WHERE run_id = ? ORDER BY step\", (run_id,)\n ).fetchall()\n checkpoints = []\n frame = _EMPTY_FRAME\n for row in rows:\n frame = _apply(frame, row)\n checkpoints.append(_to_checkpoint(row, frame))\n return checkpoints\n\n def runs(self):\n \"\"\"Every run id the store knows about.\"\"\"\n with self._lock:\n cursor = self._connection.execute(\n \"SELECT DISTINCT run_id FROM checkpoints\"\n )\n return [row[\"run_id\"] for row in cursor.fetchall()]\n\n def delete(self, run_id):\n \"\"\"Forget a run: its checkpoints and its claim on the id.\"\"\"\n with self._lock, self._transaction(run_id, None, None):\n self._connection.execute(\n \"DELETE FROM checkpoints WHERE run_id = ?\", (run_id,)\n )\n self._connection.execute(\"DELETE FROM runs WHERE run_id = ?\", (run_id,))\n self._recent.pop(run_id, None)\n\n # ------------------------------------------------------------- retention\n\n def prune(self, keep_last=None, before=None):\n \"\"\"Delete finished runs, and return the ids deleted.\n\n Retention is the operator's policy, not stepmold's, so this does nothing unless it is\n called and it never touches a run that has not finished — an unfinished chain is\n the only copy of work someone still intends to resume.\n\n `keep_last` keeps the N most recently created finished runs and drops the rest.\n `before` drops finished runs whose last checkpoint predates it, given as an ISO\n timestamp string or a datetime. Both may be given; a run is dropped if either\n rule says so.\n \"\"\"\n if keep_last is None and before is None:\n return []\n if hasattr(before, \"isoformat\"):\n before = before.isoformat(timespec=\"seconds\")\n with self._lock:\n # The last checkpoint of each run: finished when its next_node is NULL.\n rows = self._connection.execute(\n \"SELECT c.run_id AS run_id, c.next_node AS next_node,\"\n \" c.created_at AS created_at FROM checkpoints c\"\n \" JOIN (SELECT run_id, MAX(step) AS step FROM checkpoints\"\n \" GROUP BY run_id) last\"\n \" ON c.run_id = last.run_id AND c.step = last.step\"\n \" ORDER BY c.created_at, c.run_id\"\n ).fetchall()\n finished = [row for row in rows if row[\"next_node\"] is None]\n doomed = set()\n if before is not None:\n doomed.update(\n row[\"run_id\"] for row in finished if row[\"created_at\"] < before\n )\n if keep_last is not None and len(finished) > keep_last:\n keep = len(finished) - max(int(keep_last), 0)\n doomed.update(row[\"run_id\"] for row in finished[:keep])\n for run_id in sorted(doomed):\n self.delete(run_id)\n return sorted(doomed)\n\n def vacuum(self):\n \"\"\"Give freed pages back to the filesystem.\n\n Deleting runs does not shrink the file — sqlite keeps the pages for reuse — so an\n operator who has just pruned a year of runs and wants the disk back needs this.\n It rewrites the whole database, so it is theirs to schedule, not stepmold's to run.\n \"\"\"\n with self._lock:\n self._connection.execute(\"VACUUM\")\n # In WAL mode the rebuilt database lands in the write-ahead log, so the file\n # an operator is watching does not shrink until the log is folded back in.\n if self.path != \":memory:\":\n self._connection.execute(\"PRAGMA wal_checkpoint(TRUNCATE)\")\n\n # ------------------------------------------------------------ the resume lease\n\n @contextlib.contextmanager\n def lease(self, run_id, seconds=DEFAULT_LEASE):\n \"\"\"Hold an exclusive claim on `run_id` for the body of the `with`.\n\n Raises `ResumeInProgress` if someone else holds it. The expiry is the answer to a\n holder that died: nothing else can release the lease on its behalf, so the lease\n releases itself.\n\n The expiry is wall-clock rather than monotonic because the workers contending for\n it are separate processes, and a monotonic clock means nothing outside the one\n that read it.\n \"\"\"\n token = uuid.uuid4().hex\n deadline = time.time() + float(seconds)\n with self._lock, self._transaction(run_id, None, None):\n self._connection.execute(\n \"INSERT OR IGNORE INTO runs (run_id, owner, claimed_at)\"\n \" VALUES (?,?,?)\",\n (run_id, self._owner, _now()),\n )\n cursor = self._connection.execute(\n \"UPDATE runs SET lease_owner = ?, lease_expires = ?\"\n \" WHERE run_id = ?\"\n \" AND (lease_owner IS NULL OR lease_expires IS NULL\"\n \" OR lease_expires < ?)\",\n (token, deadline, run_id, time.time()),\n )\n if cursor.rowcount == 0:\n event(_log, WARNING, \"lease.refused\", run_id=run_id, store=self.path)\n raise ResumeInProgress(\n \"run %r is already being resumed by another worker — a second \"\n \"resume would execute every remaining node a second time\" % run_id\n )\n event(_log, INFO, \"lease.taken\", run_id=run_id, store=self.path,\n seconds=float(seconds))\n try:\n yield token\n finally:\n with self._lock, self._transaction(run_id, None, None):\n self._connection.execute(\n \"UPDATE runs SET lease_owner = NULL, lease_expires = NULL\"\n \" WHERE run_id = ? AND lease_owner = ?\",\n (run_id, token),\n )\n event(_log, INFO, \"lease.released\", run_id=run_id, store=self.path)\n\n # ------------------------------------------------------------ internals\n\n @contextlib.contextmanager\n def _transaction(self, run_id, step, node):\n \"\"\"One BEGIN IMMEDIATE, and contention reported as a stepmold error.\n\n IMMEDIATE rather than the default deferred begin: the write lock is taken before\n the claim is read, so two workers cannot both read \"unclaimed\" and both write.\n \"\"\"\n try:\n self._connection.execute(\"BEGIN IMMEDIATE\")\n except sqlite3.OperationalError as exc:\n _raise_busy(exc, run_id, step, node)\n try:\n yield\n except sqlite3.OperationalError as exc:\n self._rollback()\n _raise_busy(exc, run_id, step, node)\n except BaseException:\n self._rollback()\n raise\n try:\n self._connection.execute(\"COMMIT\")\n except sqlite3.OperationalError as exc:\n self._rollback()\n _raise_busy(exc, run_id, step, node)\n\n def _rollback(self):\n try:\n self._connection.execute(\"ROLLBACK\")\n except sqlite3.Error: # pragma: no cover - nothing to roll back\n pass\n\n def _claim(self, run_id, step):\n \"\"\"Take the run id, or confirm this Store already holds it.\n\n The claim is an INSERT against a primary key inside the checkpoint's own\n transaction, so it is decided by sqlite rather than by a read the caller performs\n and then acts on. Only the first step fights for the id: a resume continues a run\n that is already claimed, and a caller saving rows by hand may start anywhere.\n \"\"\"\n if step != _FIRST_STEP:\n self._connection.execute(\n \"INSERT OR IGNORE INTO runs (run_id, owner, claimed_at) VALUES (?,?,?)\",\n (run_id, self._owner, _now()),\n )\n return\n cursor = self._connection.execute(\n \"INSERT OR IGNORE INTO runs (run_id, owner, claimed_at) VALUES (?,?,?)\",\n (run_id, self._owner, _now()),\n )\n if cursor.rowcount == 1:\n event(_log, INFO, \"run.claimed\", run_id=run_id, store=self.path,\n owner=self._owner)\n return\n holder = self._connection.execute(\n \"SELECT owner FROM runs WHERE run_id = ?\", (run_id,)\n ).fetchone()\n if holder is not None and holder[\"owner\"] != self._owner:\n event(_log, WARNING, \"run.claim_refused\", run_id=run_id, store=self.path,\n owner=self._owner, held_by=holder[\"owner\"])\n raise RunIdInUse(\n \"run id %r is already claimed in this store by another run; \"\n \"resume it, delete it, or choose another id\" % run_id\n )\n\n def _encode(self, run_id, step, snapshot):\n \"\"\"('full'|'delta', (state, path, provenance)) as this row should be written.\n\n A checkpoint that repeated the whole of state cost an N-node run O(N^2) bytes,\n which is the one shape stepmold's own pitch — long workflows — guarantees. `path` and\n `provenance` grow the same way and are encoded the same way, because moving the\n quadratic term from one column to the next is not a fix.\n\n Snapshots are what keep a read cheap, and the rule for taking one is measured in\n bytes rather than in steps: write a full row as soon as rebuilding it would read\n more than twice what it holds. That size is the floor — it is how much there is\n to return — so this bounds a read at twice it, while leaving a run whose state\n only grows with the single snapshot it started with. Counting steps instead would\n take snapshots a run does not need and put the quadratic term straight back.\n \"\"\"\n base_step = self._previous_step(run_id, step)\n if base_step is None:\n return \"full\", snapshot\n last_full = self._last_full_step(run_id, base_step)\n if last_full is None:\n return \"full\", snapshot\n cached = self._recent.get(run_id)\n base = (\n cached[1] if cached is not None and cached[0] == base_step\n else self._read_frame(run_id, base_step)\n )\n current = _parse(snapshot)\n delta = (\n _dumps(_dict_delta(base[0], current[0])),\n _dumps(_path_delta(base[1], current[1])),\n _dumps(_dict_delta(base[2], current[2])),\n )\n full_bytes = sum(len(blob) for blob in snapshot)\n delta_bytes = sum(len(blob) for blob in delta)\n # A delta at least as big as the snapshot buys nothing and costs a hop on every\n # read — which is what a node that rewrites the whole of state produces.\n if delta_bytes >= full_bytes:\n return \"full\", snapshot\n # Everything a read would have to walk to rebuild this step: the snapshot it\n # starts from, plus every delta between that and here.\n carried = self._connection.execute(\n \"SELECT COALESCE(SUM(LENGTH(state) + LENGTH(path) + LENGTH(provenance)), 0)\"\n \" AS bytes FROM checkpoints WHERE run_id = ? AND step >= ? AND step <= ?\",\n (run_id, last_full, base_step),\n ).fetchone()[\"bytes\"]\n if carried + delta_bytes >= 2 * full_bytes:\n return \"full\", snapshot\n return \"delta\", delta\n\n def _previous_step(self, run_id, step):\n row = self._connection.execute(\n \"SELECT MAX(step) AS step FROM checkpoints WHERE run_id = ? AND step < ?\",\n (run_id, step),\n ).fetchone()\n return row[\"step\"]\n\n def _last_full_step(self, run_id, step):\n \"\"\"The newest snapshot at or before `step`. NULL state_kind is a pre-delta row.\"\"\"\n return self._connection.execute(\n \"SELECT MAX(step) AS step FROM checkpoints WHERE run_id = ? AND step <= ?\"\n \" AND (state_kind IS NULL OR state_kind = 'full')\",\n (run_id, step),\n ).fetchone()[\"step\"]\n\n def _read_frame(self, run_id, step):\n \"\"\"Rebuild (state, path, provenance) for a step, from its snapshot forward.\"\"\"\n last_full = self._last_full_step(run_id, step)\n start = last_full if last_full is not None else 0\n rows = self._connection.execute(\n \"SELECT state, path, provenance, state_kind FROM checkpoints\"\n \" WHERE run_id = ? AND step >= ? AND step <= ? ORDER BY step\",\n (run_id, start, step),\n ).fetchall()\n frame = _EMPTY_FRAME\n for row in rows:\n frame = _apply(frame, row)\n return frame\n\n def close(self):\n with self._lock:\n self._connection.close()\n\n def __enter__(self):\n return self\n\n def __exit__(self, *exc_info):\n self.close()\n return False\n\n\ndef _now():\n return datetime.now(timezone.utc).isoformat(timespec=\"seconds\")\n\n\ndef _raise_busy(exc, run_id, step, node):\n \"\"\"Re-raise a lock timeout as `StoreBusy`; leave every other sqlite error alone.\n\n A schema that is wrong, a disk that is full and a database that is merely contended\n are three different operator problems, and only the last one is stepmold's to rename.\n \"\"\"\n text = str(exc).lower()\n if \"locked\" not in text and \"busy\" not in text:\n raise exc\n where = \"run %r\" % run_id\n if step is not None:\n where += \" at step %d\" % step\n if node is not None:\n where += \" (node %r)\" % node\n raise StoreBusy(\n \"the store stayed locked longer than the busy timeout while writing %s: %s \"\n \"— raise Store(path, timeout=...) or reduce the writers on this file\"\n % (where, exc)\n ) from exc\n\n\ndef _add_column(connection, column, declared_type):\n \"\"\"ALTER TABLE ... ADD COLUMN, tolerating the column already being there.\n\n Reading `PRAGMA table_info` and then deciding is a read-then-write: two workers\n opening one legacy store file both see the column missing and both run the ALTER, and\n the second is answered with `duplicate column name` out of a constructor. Asking\n sqlite and accepting its refusal is the same work done atomically — a duplicate here\n means the other worker did it, which is the outcome either way.\n \"\"\"\n try:\n connection.execute(\n \"ALTER TABLE checkpoints ADD COLUMN %s %s\" % (column, declared_type)\n )\n except sqlite3.OperationalError as exc:\n if \"duplicate column\" not in str(exc).lower():\n raise\n\n\n#: What a checkpoint carries that grows along the walk, in the order the columns hold it.\n#: A run starts from nothing, which is what a delta chain with no snapshot in front of it\n#: would be read against.\n_EMPTY_FRAME = ({}, [], {})\n\n\ndef _dumps(value):\n return json.dumps(value, sort_keys=True, allow_nan=False)\n\n\ndef _parse(snapshot):\n \"\"\"(state, path, provenance) from the three JSON blobs of a full row.\"\"\"\n return tuple(json.loads(blob) for blob in snapshot)\n\n\ndef _dict_delta(base, new):\n \"\"\"What changed between two dicts: keys set to a new value, and keys removed.\"\"\"\n changed = {\n key: value\n for key, value in new.items()\n # Canonical JSON rather than `!=`, because `True == 1` in Python and a value that\n # went from true to 1 would otherwise be recorded as unchanged and come back as\n # the wrong one of the two — which is the round-trip contract, broken quietly.\n if key not in base or _dumps(base[key]) != _dumps(value)\n }\n return {\"set\": changed, \"del\": sorted(key for key in base if key not in new)}\n\n\ndef _path_delta(base, new):\n \"\"\"How a path grew: how much of the old one still stands, and what was appended.\n\n A walk only ever appends, so `keep` is normally the whole of the previous path — but\n a path that diverges is recorded correctly rather than assumed away.\n \"\"\"\n keep = 0\n for before, after in zip(base, new):\n if _dumps(before) != _dumps(after):\n break\n keep += 1\n return {\"keep\": keep, \"add\": list(new[keep:])}\n\n\ndef _apply(frame, row):\n \"\"\"The frame after one row: a snapshot replaces it, a delta edits it.\"\"\"\n if row[\"state_kind\"] != \"delta\":\n return (\n json.loads(row[\"state\"]),\n json.loads(row[\"path\"]),\n json.loads(row[\"provenance\"]),\n )\n return (\n _apply_dict(frame[0], json.loads(row[\"state\"])),\n _apply_path(frame[1], json.loads(row[\"path\"])),\n _apply_dict(frame[2], json.loads(row[\"provenance\"])),\n )\n\n\ndef _apply_dict(base, delta):\n result = dict(base)\n for key in delta.get(\"del\", ()):\n result.pop(key, None)\n result.update(delta.get(\"set\", {}))\n return result\n\n\ndef _apply_path(base, delta):\n return list(base[:delta.get(\"keep\", 0)]) + list(delta.get(\"add\", ()))\n\n\ndef resume(pack, model, run_id, store, **kwargs):\n \"\"\"Continue `run_id` from its last checkpoint, under the pack that started it.\n\n A run that already finished is returned as-is, without calling the model — resuming\n is idempotent, so a supervisor can retry a resume without paying for it twice.\n\n `pack` is checked against the checkpoint first, finished run or not: replaying one\n graph's output as another's is the same lie whether the walk continues or not.\n\n An unfinished run is resumed under a lease, so two supervisors retrying the same\n resume do not both execute every remaining node. The second one is refused with\n `ResumeInProgress` rather than allowed to charge the card twice.\n\n Extra keywords go through to `graph.run` — `tools=` among them, which a pack with\n `tool` nodes needs on the resume exactly as it needed it on the first attempt.\n \"\"\"\n from .graph import run as run_pack, replay # local: graph imports nothing from here\n\n checkpoint = store.latest(run_id)\n if checkpoint is None:\n event(_log, WARNING, \"resume.unknown\", run_id=run_id, pack=pack.name)\n raise UnknownRun(\"no checkpoint found for run %r\" % run_id)\n _check_same_pack(pack, checkpoint)\n if checkpoint.finished:\n event(_log, INFO, \"resume.replayed\", run_id=run_id, pack=pack.name,\n step=checkpoint.step, end_node=checkpoint.node)\n return replay(checkpoint)\n event(_log, INFO, \"resume.start\", run_id=run_id, pack=pack.name,\n from_step=checkpoint.step, next_node=checkpoint.next_node)\n\n lease = getattr(store, \"lease\", None)\n if lease is None:\n # A store that predates the lease — anything with save/latest is a store, per\n # graph.run's contract. Nothing to serialise against, so resume as before.\n return run_pack(pack, model, run_id=run_id, store=store,\n resume_from=checkpoint, **kwargs)\n with lease(run_id):\n # Re-read under the lease: the run may have been finished by whoever held it\n # while this caller was waiting for it.\n checkpoint = store.latest(run_id)\n if checkpoint is None: # pragma: no cover - deleted mid-resume\n raise UnknownRun(\"no checkpoint found for run %r\" % run_id)\n _check_same_pack(pack, checkpoint)\n if checkpoint.finished:\n return replay(checkpoint)\n return run_pack(pack, model, run_id=run_id, store=store,\n resume_from=checkpoint, **kwargs)\n\n\ndef _check_same_pack(pack, checkpoint):\n \"\"\"Refuse to resume `checkpoint` under a pack that is not the one that wrote it.\n\n Identity first, then shape. The recorded identity is whatever the writer supplied —\n a checkpoint written before these columns existed carries no name and no version, so\n those comparisons are skipped rather than failed, and the shape check below is all\n that stands between the run and a graph it never walked.\n \"\"\"\n described = _describe(checkpoint)\n if checkpoint.pack is not None and checkpoint.pack != pack.name:\n raise CheckpointMismatch(\n \"run %r was checkpointed under %s, but resume was handed pack %r version %s \"\n \"— resume it under the pack that started it, or start a new run\"\n % (checkpoint.run_id, described, pack.name, pack.version)\n )\n recorded_version = checkpoint.pack_version\n if recorded_version is not None and recorded_version != str(pack.version):\n raise CheckpointMismatch(\n \"run %r was checkpointed under %s, but resume was handed version %s of %r \"\n \"— a version bump means the graph moved on, so the checkpoint no longer \"\n \"describes a walk through it\"\n % (checkpoint.run_id, described, pack.version, pack.name)\n )\n\n # Shape. A node the run already walked, or the one it stopped in front of, must still\n # exist. This catches a renamed or deleted node even when the version was never\n # recorded — it cannot catch a node whose prompt changed, which is what the version\n # is for.\n walked = list(checkpoint.path)\n if checkpoint.next_node is not None:\n walked.append(checkpoint.next_node)\n for name in walked:\n if name not in pack.nodes:\n raise CheckpointMismatch(\n \"run %r was checkpointed under %s and needs node %r, which pack %r \"\n \"version %s does not define — the graph changed under the run\"\n % (checkpoint.run_id, described, name, pack.name, pack.version)\n )\n\n\ndef _describe(checkpoint):\n \"\"\"How a checkpoint names the pack that wrote it, including when it does not.\"\"\"\n if checkpoint.pack is None:\n return \"a pack that did not record its name\"\n if checkpoint.pack_version is None:\n return \"pack %r (no version recorded)\" % checkpoint.pack\n return \"pack %r version %s\" % (checkpoint.pack, checkpoint.pack_version)\n\n\ndef _identity(pack, pack_version=None):\n \"\"\"(name, version) for the store, from either a pack name or the pack itself.\"\"\"\n name = getattr(pack, \"name\", pack)\n version = pack_version if pack_version is not None else getattr(pack, \"version\", None)\n return (\n None if name is None else str(name),\n None if version is None else str(version),\n )\n\n\n# ------------------------------------------------------- the round-trip contract\n\n# What a checkpoint may hold: exactly the values JSON hands back unchanged. Anything\n# else is refused by name, because a checkpoint that quietly alters the run it is\n# restoring is worse than no checkpoint at all.\n_SCALARS = (str, int, float, bool)\n\n\ndef _dump(value, where):\n _check(value, where, set())\n # allow_nan=False is the belt to _check's braces: nothing reaches the file that a\n # conforming JSON reader would choke on.\n return json.dumps(value, sort_keys=True, allow_nan=False)\n\n\ndef _check(value, where, open_containers):\n \"\"\"Raise if `value` would not survive a JSON round trip unchanged.\n\n TypeError for a value JSON has no representation for, ValueError for one it can\n represent only with a non-standard extension — the same split json.dumps uses, so a\n caller already catching one keeps catching it.\n \"\"\"\n if value is None or isinstance(value, _SCALARS):\n if isinstance(value, float) and not math.isfinite(value):\n raise ValueError(\n \"cannot checkpoint %s: %r is not a JSON number — strict JSON has no \"\n \"NaN or Infinity, and a store file carrying one cannot be read back\"\n % (where, value)\n )\n return\n\n if id(value) in open_containers:\n raise ValueError(\n \"cannot checkpoint %s: it contains itself, so there is nothing finite to \"\n \"write\" % where\n )\n\n if isinstance(value, list):\n open_containers.add(id(value))\n for index, item in enumerate(value):\n _check(item, \"%s[%d]\" % (where, index), open_containers)\n open_containers.discard(id(value))\n return\n\n if isinstance(value, dict):\n open_containers.add(id(value))\n for key, item in value.items():\n # Not `isinstance(key, str)`: a bool key is not a str, and json would write\n # it as \"true\" and hand back a string.\n if type(key) is not str:\n raise TypeError(\n \"cannot checkpoint %s: the key %r is a %s, and JSON object keys are \"\n \"strings — it would come back as %r\"\n % (where, key, type(key).__name__, str(key))\n )\n _check(item, \"%s.%s\" % (where, key), open_containers)\n open_containers.discard(id(value))\n return\n\n if isinstance(value, tuple):\n raise TypeError(\n \"cannot checkpoint %s: a tuple comes back from JSON as a list — commit a \"\n \"list, so what resumes is what was committed\" % where\n )\n\n raise TypeError(\n \"cannot checkpoint %s: a %s is not JSON data (commit only str, int, float, \"\n \"bool, None, list, or dict with string keys)\" % (where, type(value).__name__)\n )\n\n\ndef _json_column(row, column, kind):\n \"\"\"A JSON column read back, or its empty value if this row has nothing usable.\n\n Both columns this serves were added after the first release, so a store file written\n by an older stepmold may not have them at all — and a row written before the column\n existed has NULL in it. Neither is a broken chain, so both read back empty rather\n than raising: what is lost is a diagnostic, and in `tool_calls`' case a replay that\n was never recorded to begin with.\n \"\"\"\n try:\n raw = row[column]\n except (IndexError, KeyError):\n return kind()\n if not raw:\n return kind()\n try:\n value = json.loads(raw)\n except ValueError:\n return kind()\n return value if isinstance(value, kind) else kind()\n\n\ndef _to_checkpoint(row, frame):\n state, path, provenance = frame\n return Checkpoint(\n run_id=row[\"run_id\"],\n step=row[\"step\"],\n node=row[\"node\"],\n next_node=row[\"next_node\"],\n state=state,\n path=path,\n provenance=provenance,\n failures=json.loads(row[\"failures\"]),\n output=None if row[\"output\"] is None else json.loads(row[\"output\"]),\n pack=row[\"pack\"],\n pack_version=row[\"pack_version\"],\n # A checkpoint written before this column existed has no attempt counts. That is\n # a missing diagnostic, not a broken chain, so it reads back as {}.\n attempts=_json_column(row, \"attempts\", dict),\n tool_calls=_json_column(row, \"tool_calls\", list),\n created_at=row[\"created_at\"],\n )\n", "stepmold/tools.py": "\"\"\"Tools: the only way a pack can reach outside itself.\n\nA pack is text. It has no code in it and never will — that is what lets a pack be\nreviewed in a diff, copied to a machine that cannot install anything, and read by a\nruntime written in another language. So a pack cannot *contain* an action. It can only\n*name* one.\n\nThe host supplies the actions:\n\n registry = ToolRegistry()\n\n @registry.register(\"lookup_order\", reads=[\"order_id\"], writes=[\"order_total\"])\n def lookup_order(order_id):\n return {\"order_total\": db.total_for(order_id)}\n\n run(pack, model, inputs, tools=registry)\n\nand a `tool` node in the graph names one:\n\n fetch:\n type: tool\n tool: lookup_order\n\nTwo properties fall out of that shape, and both are the reason it is shaped that way.\n\n**A pack can only call what the host already allowed.** There is no import, no dotted\npath, no eval — a name that was never registered is refused at load, before the run\nstarts. A pack you did not write cannot reach anything you did not hand it. This is an\nallowlist by construction rather than a sandbox that has to hold.\n\n**A tool call is a side effect, and side effects must not happen twice.** A run that\nsends an email, then crashes, then resumes must not send it again. Every completed call\nis recorded in the checkpoint with the arguments it was given, and a resumed run replays\nthe recorded result instead of calling again. A tool that is genuinely safe to repeat can\nsay so with `idempotent=True` and skip the bookkeeping.\n\nNothing here calls a model. A tool node is deterministic: same state in, same call out.\nThat is what makes an action auditable in a way a generation is not.\n\"\"\"\n\nimport inspect\nfrom dataclasses import dataclass, field\nfrom typing import Any, Callable, Dict, List, Optional\n\nfrom .errors import RunError\n\n__all__ = [\n \"Tool\",\n \"ToolRegistry\",\n \"ToolError\",\n \"ToolNotRegistered\",\n \"ToolFailed\",\n \"ToolContract\",\n]\n\n\nclass ToolError(RunError):\n \"\"\"A tool could not be run, or its result could not be trusted.\"\"\"\n\n\nclass ToolNotRegistered(ToolError):\n \"\"\"A pack named a tool the host did not supply.\n\n Raised at load time wherever possible. A run that discovers this halfway through has\n already done part of a job it cannot finish.\n \"\"\"\n\n\nclass ToolFailed(ToolError):\n \"\"\"The tool raised. Carries the node so the failure can be routed like any other.\"\"\"\n\n def __init__(self, node, tool, cause):\n self.node = node\n self.tool = tool\n self.cause = cause\n ToolError.__init__(self, \"tool %r on node %r failed: %s: %s\"\n % (tool, node, type(cause).__name__, cause))\n\n\nclass ToolContract(ToolError):\n \"\"\"The tool returned something its declaration said it would not.\n\n Checked for the same reason a generation is checked: a value that does not match what\n the graph was built around is a bad result, whether a model or a function produced it.\n \"\"\"\n\n\n@dataclass(frozen=True)\nclass Tool:\n \"\"\"One action the host has made available to a pack.\"\"\"\n\n name: str\n call: Callable\n reads: List[str] = field(default_factory=list)\n writes: List[str] = field(default_factory=list)\n idempotent: bool = False\n description: str = \"\"\n\n def invoke(self, state, node_name):\n \"\"\"Run the tool against `state` and return the object to commit.\n\n `reads` is the whole argument list: a tool is given exactly the state it declared\n it needs and nothing else. That keeps a tool's dependencies visible in the graph\n instead of hidden in its body, and stops a tool quietly coupling to a field the\n author did not intend.\n \"\"\"\n missing = [key for key in self.reads if key not in state]\n if missing:\n raise ToolContract(\n \"tool %r on node %r needs %s, which state does not have (it has: %s)\"\n % (self.name, node_name, \", \".join(sorted(missing)),\n \", \".join(sorted(state)) or \"nothing\")\n )\n arguments = {key: state[key] for key in self.reads}\n try:\n result = self.call(**arguments)\n except Exception as exc: # noqa: BLE001 - any failure is the node's failure\n raise ToolFailed(node_name, self.name, exc)\n return self._checked(result, node_name)\n\n def _checked(self, result, node_name):\n if result is None:\n result = {}\n if not isinstance(result, dict):\n raise ToolContract(\n \"tool %r on node %r returned %s; a tool must return a dict of the state \"\n \"it writes, or None for nothing\"\n % (self.name, node_name, type(result).__name__)\n )\n if self.writes:\n missing = [key for key in self.writes if key not in result]\n if missing:\n raise ToolContract(\n \"tool %r on node %r declares it writes %s but returned %s\"\n % (self.name, node_name, \", \".join(sorted(self.writes)),\n \", \".join(sorted(result)) or \"nothing\")\n )\n extra = [key for key in result if key not in self.writes]\n if extra:\n raise ToolContract(\n \"tool %r on node %r returned undeclared key(s) %s. A tool's `writes` \"\n \"is the contract the graph is built around — widen it deliberately \"\n \"rather than by accident.\"\n % (self.name, node_name, \", \".join(sorted(extra)))\n )\n return dict(result)\n\n\nclass ToolRegistry:\n \"\"\"The set of actions a host is willing to let a pack take.\n\n Deliberately not a module-level default. There is no ambient registry a pack could\n reach by existing; a host that wants a pack to be able to act has to say so, per run.\n \"\"\"\n\n def __init__(self):\n self._tools = {}\n\n def register(self, name, reads=(), writes=(), idempotent=False, description=\"\"):\n \"\"\"Decorator: expose one function to packs under `name`.\n\n `reads` names the state this tool needs and `writes` names what it produces, both\n checked at load time against the graph. Declaring them is not bureaucracy — it is\n what lets `stepmold validate` catch a tool wired to a field that does not exist yet,\n before a run has done half a job.\n \"\"\"\n\n def decorate(function):\n if name in self._tools:\n raise ToolError(\"tool %r is already registered\" % name)\n reads_list = list(reads)\n if not reads_list:\n # A tool that named nothing gets its parameter list read off the function,\n # which is right often enough to be worth doing and always visible in\n # `stepmold validate` when it is not.\n try:\n signature = inspect.signature(function)\n reads_list = [\n parameter.name\n for parameter in signature.parameters.values()\n if parameter.kind in (parameter.POSITIONAL_OR_KEYWORD,\n parameter.KEYWORD_ONLY)\n ]\n except (TypeError, ValueError):\n reads_list = []\n self._tools[name] = Tool(\n name=name, call=function, reads=reads_list, writes=list(writes),\n idempotent=bool(idempotent),\n description=description or (function.__doc__ or \"\").strip().split(\"\\n\")[0],\n )\n return function\n\n return decorate\n\n def add(self, name, function, **kwargs):\n \"\"\"Register without the decorator, for a function you did not define.\"\"\"\n return self.register(name, **kwargs)(function)\n\n def get(self, name, node_name=None):\n tool = self._tools.get(name)\n if tool is None:\n where = (\" on node %r\" % node_name) if node_name else \"\"\n raise ToolNotRegistered(\n \"no tool named %r%s. A pack can only call what the host registered \"\n \"(available: %s). Register it before the run, or remove the node.\"\n % (name, where, \", \".join(sorted(self._tools)) or \"none\")\n )\n return tool\n\n def has(self, name):\n return name in self._tools\n\n @property\n def names(self):\n return sorted(self._tools)\n\n def __len__(self):\n return len(self._tools)\n\n def __contains__(self, name):\n return name in self._tools\n", "stepmold/verify.py": "\"\"\"Verify-before-commit, and the retry ladder.\n\nThis module is the reason a small model can be trusted here at all (docs/ARCHITECTURE.md §3).\nTwo rules, and the second one is the load-bearing one:\n\n1. **Nothing is committed until it is verified.** Output must parse, satisfy the node's\n schema, and satisfy the node's optional `assert` expression.\n2. **A rejected generation is never shown to the model again.** Not in the run's state,\n not in a later node's prompt, and not in this node's own retry prompt. Verification\n runs against a *trial* copy of state; only a candidate that survives is written back.\n The retry prompt may say *what was wrong* (`Rejected.feedback`, derived from the\n pack's schema) but never *what the model said*. That is the structural fix for\n self-conditioning decay — a model that never sees its own bad output cannot spiral\n on it.\n\n The full text, offending value and all, is retained in `RunResult.failures` and in\n the checkpoint. That is deliberate: an operator debugging a pack needs it, and bytes\n on disk cannot condition a model. `tests/test_invariants.py` enforces both halves.\n\nThe ladder is: generate, then re-sample once for each retry the node allows, then the\nnode's `on_fail` edge (or `NodeFailed`). No frontier-model fallback, by design — ARCHITECTURE.md\nkeeps the cost story honest.\n\nEvery rung after the first changes two things, because a re-sample is only worth its\ntokens if it is a *different draw*:\n\n* **a sampling hint** (`codegen.Sampling`, `RESAMPLE_TEMPERATURES` below). ARCHITECTURE.md §3\n writes the first rung as a plain re-sample \"(temp bump)\", and for a long time nothing\n at this layer could bump anything: the protocol had no sampling parameter, so against\n a greedy backend rung 1 re-issued a byte-identical request and got the byte-identical\n rejection. The hint is optional in the protocol and passed only to a model that\n declares it (`codegen._generate`), so a backend that cannot vary its sampling is\n called exactly as before and still gets the feedback rung.\n* **the rejection, as feedback** — what was wrong, never what was said.\n\nAnd it drops one thing: on a `two_stage` node, the scratchpad behind a rejected answer.\nThe think stage is what produced the reasoning the emit stage obeyed, so re-emitting from\nthose same notes is not a re-sample at all — `tests/production/test_longhorizon.py`\nmeasured a two-stage arm sitting exactly on the naive analytical curve because of it. A\nrejection makes the notes suspect, so the next rung re-thinks. A rung spent for any other\nreason (a 200 that carried no text — see `EmptyCompletion`) keeps them: nothing about\nthose notes was ever judged, and re-thinking would be a call spent to learn nothing.\n\n`EmptyCompletion` also turns that content-less 200 into a rejection rather than an abort,\nso the ladder answers it and the node's `on_fail` edge still means what the pack says.\n\nRule 2 has one more downstream now that stepmold logs (`stepmold.log`). A log file cannot condition\na model, so `Rejected.detail` is allowed there — but a log an operator ships to a\ncollector is still somewhere a customer's ticket should not turn up by accident, so the\ndetail is DEBUG-only and every other level carries `feedback`, the half already derived\nfrom the pack's own schema. `NodeFailed` carries both for the same reason.\n\n## The confidence gate — agreement, not self-report\n\nA node may ask to be drawn more than once and have the answers compared:\n\n classify:\n type: generate\n samples: 3 # draw three independent answers\n agree: 2 # accept when this many match; otherwise the node is unsure\n\nThis exists because the obvious alternative does not work. A number the model *says*\nabout its own answer is generated after the answer is already on the page: it reflects\nthe rubric in the prompt, not whether the answer is right, and it is overconfident\nexactly where being wrong costs the most. stepmold's usable signals, best first, are a\ndeterministic `assert` (a fact, not a guess), then agreement across independent draws,\nand only then anything the model claims about itself. `verify` is the first. This is the\nsecond. There is no third.\n\n**What agreement means.** Two draws agree when the objects that would be committed are\nthe same object — compared as canonical JSON (`_canonical`: sorted keys, no whitespace).\nNot \"the fields that matter\": at this layer nothing knows which fields those are, and\nguessing wrong is the one failure that must not happen here — two draws that match on\nthe enum and differ on the amount are *not* a confident answer when the next node is a\ntool that spends the amount. The node's own grammar is already the pack's declaration of\nwhat matters; an author who wants agreement on less should narrow it, or split the node,\nso that the thing being agreed on stays the thing being committed. Canonical text is also\nthe cheap answer: one string per draw, hashable, O(draws) grouping, and stable across key\norder. It is stricter than `==` in exactly one place — `1` and `1.0` are different draws\nwhere Python would call them equal — and that is the direction to be strict in for a gate\nwhose entire job is to notice that the model was not consistent.\n\n**Unsure is not rejected.** A rejection means the output was invalid, and the ladder\nbelow answers it. Disagreement means every output was *valid* and the model was not\nconsistent, which no re-sample fixes and which deserves a different destination — a\nhuman queue, a cheaper safe branch, a second opinion. So it raises `Unsure`, a sibling of\n`NodeFailed` rather than a subclass of it: a walker that wants to route both to `on_fail`\ncan, but it has to say so, and inheritance would have made that choice silently.\n`Unsure` carries the counts (`Unsure.consensus`), the answer that came closest\n(`Unsure.value`), and nothing is committed by this module either way.\n\n**Cost.** n samples cost n generations, so the loop stops the moment the answer cannot\nchange: as soon as one group reaches `agree`, and as soon as the draws left cannot lift\nany group to `agree`. A node with `samples: 3, agree: 2` whose first two draws match\nspends two generations, not three.\n\n**The ladder is per draw.** A draw that fails verification is a rejection, not a\ndisagreement: it climbs the rungs exactly as it does today, and a draw that spends the\nwhole ladder fails the node (`NodeFailed`) rather than counting as one dissenting voice —\na node that could not produce a valid answer has not produced evidence about anything.\nEach draw starts its ladder clean, with no feedback and no scratchpad from the draw\nbefore it, because a draw conditioned on another draw's rejection is not independent, and\nagreement between draws that were conditioned on each other measures nothing.\n\nEvery generation after the very first also carries a distinct sampling hint (see\n`sampling_for`) — against a backend that varies nothing, two draws are one draw charged\ntwice and would agree by construction. That is a false confidence signal rather than a\nmissing one, so a sampled node in front of a backend that cannot hear the hint says so at\nWARNING (`node.samples.blind`).\n\"\"\"\n\nimport json\nfrom dataclasses import dataclass\n\nfrom .codegen import Sampling, accepts_sampling, generate_once\nfrom .errors import BackendError, ExprError, NodeFailed, RunError\nfrom .expr import is_true\nfrom .grammar import ValidationError, validate_against\nfrom .log import DEBUG, INFO, WARNING, clip, event, get_logger\n\n_log = get_logger(\"verify\")\n\n__all__ = [\n \"Consensus\",\n \"DRAW_SEED_STRIDE\",\n \"DRAW_TEMPERATURE\",\n \"EmptyCompletion\",\n \"GateError\",\n \"RESAMPLE_TEMPERATURES\",\n \"Rejected\",\n \"Unsure\",\n \"extract_json\",\n \"gate_for\",\n \"run_node\",\n \"sampling_for\",\n \"verify\",\n]\n\n# What each re-sample rung asks for. The climb is deliberate: rung 1 wants a different\n# answer, not a wild one, and only a ladder that has already spent two rungs has evidence\n# that the neighbourhood of the greedy answer is the problem. Deeper ladders stay at the\n# top of the range rather than inventing values nobody has measured.\nRESAMPLE_TEMPERATURES = (0.5, 0.8, 1.0)\n\nEMPTY_COMPLETION_FEEDBACK = (\n \"your previous answer arrived empty — return a single JSON object and nothing else\"\n)\n\n# What an *extra draw* asks for. Not a rung of the ladder: nothing was rejected, so there\n# is nothing to climb away from, and a temperature ramp across draws would measure the\n# ramp rather than the model. Same temperature every time, different seed every time —\n# the bottom of the measured range, because a draw taken to check another draw should be\n# drawn the way the node normally is.\nDRAW_TEMPERATURE = RESAMPLE_TEMPERATURES[0]\n\n# Spacing between one draw's seeds and the next's. Every generation a node spends gets a\n# seed nothing else in that node uses, which is what stops draw 2's first rung and draw\n# 3's first rung from being the same request answered twice and counted as agreement.\n# Draw 0 keeps `seed == rung` exactly as before, so an unsampled node's requests are\n# byte-for-byte the ones it has always made.\nDRAW_SEED_STRIDE = 1 << 16\n\n\nclass Rejected(ValueError):\n \"\"\"One candidate output failed verification. Not fatal — the ladder continues.\n\n Two halves, and keeping them apart is what makes rule 2 above true:\n\n * ``str(exc)`` is the full detail, including the offending text. It goes to logs,\n `RunResult.failures` and the checkpoint — diagnostics can never self-condition a\n model, and an operator debugging a pack needs to see what came back.\n * ``feedback`` is the only half the *model* is ever shown. It says what was wrong\n without quoting what the model said.\n \"\"\"\n\n def __init__(self, detail, feedback=None):\n ValueError.__init__(self, detail)\n self.detail = detail\n self.feedback = detail if feedback is None else feedback\n\n\nclass EmptyCompletion(BackendError):\n \"\"\"A 200 that carried no text — a bad *sample*, not a backend that is down.\n\n The endpoint answered, and this draw simply had nothing in `message.content`: a\n reasoning model that spent its budget thinking, an empty choice, a filtered\n completion. That is the case a re-sample exists for, so `run_node` turns it into a\n `Rejected` and spends a rung instead of aborting the run past the node's `on_fail`.\n\n A backend that is unreachable, or returning 500s, is a different thing and still\n stops the run: no rung can fix it, and burning the ladder against a dead endpoint\n only delays the error.\n\n `empty_content` is the flag `run_node` actually reads, so a backend can mark an\n existing `BackendError` instead of raising this class — `stepmold.backends.openai_compat`\n keeps its own diagnostic message either way.\n \"\"\"\n\n empty_content = True\n\n\n@dataclass(frozen=True)\nclass Consensus:\n \"\"\"What one visit to a sampled node found out — the reporting half of the gate.\n\n Counts only, deliberately. This record is meant to be logged, checkpointed and\n printed by `stepmold eval`, and every one of those is somewhere a customer's data must not\n turn up by accident; a record that holds no model output is safe in all three without\n anyone having to remember that it is. The value itself is *returned* when the node\n agreed, and carried on `Unsure.value` when it did not.\n\n * `asked` — what the pack asked for (`samples:`).\n * `drawn` — what it actually paid for. Lower than `asked` whenever the answer could\n no longer change: a group reached the threshold, or the draws left could not lift\n one to it.\n * `agreed` — the size of the largest group of matching draws.\n * `required` — the threshold (`agree:`, or a strict majority of `asked`).\n * `generations` — model calls this visit spent, rejected ones included. `drawn`\n counts answers; this counts the bill.\n * `distinct` — how many different answers the draws produced. It is the shape of a\n disagreement rather than its size, and it is what an author tuning `samples` needs:\n a 2-2 split is a node with two defensible readings, four different answers is a\n node that is guessing.\n \"\"\"\n\n node: str\n asked: int\n drawn: int\n agreed: int\n required: int\n generations: int\n distinct: int = 1\n\n @property\n def unsure(self):\n \"\"\"True when no group of matching draws reached the threshold.\"\"\"\n return self.agreed < self.required\n\n\nclass Unsure(RunError):\n \"\"\"A node's draws were all valid and did not agree.\n\n Distinct from `NodeFailed` on purpose (see this module's docstring): nothing was\n wrong with any of these answers, so the ladder has nothing to fix and the node's\n `on_fail` edge is not obviously where this should go. What a pack usually wants is a\n different destination — a human queue, a cheaper safe branch — which is why this is a\n signal a walker routes on rather than a failure it absorbs.\n\n For whoever wires the routing: catch `Unsure` alongside `NodeFailed`, and route it to\n the node's `on_unsure` if the pack declares one, its `on_fail` if it does not, and\n let it escape when it declares neither. `node`, `reason`, `feedback` and `attempts`\n are named the same as on `NodeFailed` so one failure-recording path can hold both.\n\n Every word of `str(exc)` is counts and node names — no model output — so unlike a\n `NodeFailed` this one is safe at any log level whole. `value` is the answer that came\n closest (the largest group's, ties going to the earliest draw). Nothing here is\n committed: a caller that decides an unsure answer is good enough for a human to look\n at has to commit it deliberately.\n \"\"\"\n\n def __init__(self, node, consensus, value=None):\n self.node = node\n self.consensus = consensus\n self.value = value\n self.attempts = consensus.generations\n self.reason = (\n \"%d of %d draws agreed and %d had to; %d generation(s) spent\"\n % (consensus.agreed, consensus.drawn, consensus.required,\n consensus.generations)\n )\n # Both halves are the same text because both halves are safe. `feedback` exists\n # so a walker written against `NodeFailed` can read either exception the same way.\n self.feedback = self.reason\n RunError.__init__(self, \"node %r is unsure: %s\" % (node, self.reason))\n\n\nclass GateError(RunError):\n \"\"\"A node's `samples`/`agree` pair does not describe a gate that can do anything.\n\n Raised rather than quietly repaired. Every reading of a broken gate is a lie about\n confidence — clamping `agree: 5, samples: 3` down to 3 silently weakens the check the\n author asked for, and accepting `agree: 1` alongside `samples: 3` gives a pack a gate\n that never fires and an author who believes it does. `stepmold validate` should catch these\n before a run starts; this is the backstop for a pack that arrived another way.\n \"\"\"\n\n\ndef sampling_for(rung, draw=0):\n \"\"\"The sampling hint for rung `rung` of draw `draw`, or None for the very first one.\n\n Draw 0, rung 0 asks for nothing on purpose: the first generation is the one the\n operator configured, so a pack that runs greedily stays reproducible and a run that\n never needed the ladder is byte-for-byte what it always was. Turning a node's gate on\n does not change that generation either — the extra draws are the check, not the\n answer.\n\n Every other generation the node spends asks for something no other generation of that\n node asked for. Across rungs that is the ladder climbing away from a rejection; across\n draws it is the same temperature with a different seed, because an extra draw is not a\n retry (`DRAW_TEMPERATURE`) — and because two identical requests are one draw charged\n twice, which on a sampled node would be counted as the model agreeing with itself.\n \"\"\"\n if rung <= 0 and draw <= 0:\n return None\n # The seed rides along for a server pinned to temperature 0 by policy: greedy\n # decoding ignores a temperature it was told to ignore, and a per-request seed is\n # the only knob left.\n seed = rung + draw * DRAW_SEED_STRIDE\n if rung <= 0:\n return Sampling(temperature=DRAW_TEMPERATURE, seed=seed)\n index = min(rung, len(RESAMPLE_TEMPERATURES)) - 1\n return Sampling(temperature=RESAMPLE_TEMPERATURES[index], seed=seed)\n\n\ndef gate_for(node):\n \"\"\"The `(samples, agree)` this node asks for — defaulted, checked, and cheap.\n\n A node that says nothing draws once and needs one answer, which is exactly what every\n pack written before this feature existed does. Read with `getattr` because the keys\n are optional in the node record as well as in the pack: a `Node` without them is a\n node that never asked for a gate.\n\n An `agree` left unset on a sampled node is a strict majority of the samples, which is\n the only default that is a *rule* rather than a preference — anything else has to\n pick a number, and a number picked here would be a confidence threshold nobody\n measured.\n \"\"\"\n samples = _whole(\"samples\", getattr(node, \"samples\", None), node)\n if samples is None:\n samples = 1\n if samples < 1:\n raise GateError(\n \"node %r asks for samples: %d. A node draws at least once — use samples: 1 \"\n \"(or drop the key) for the ordinary single draw.\" % (node.name, samples)\n )\n required = _whole(\"agree\", getattr(node, \"agree\", None), node)\n if samples == 1:\n # Nothing to compare a lone draw with, so `agree` cannot mean anything here. Say\n # so rather than ignoring it: a pack that set one and not the other has a gate its\n # author believes in and the runtime does not.\n if required is not None and required > 1:\n raise GateError(\n \"node %r asks for agree: %d but draws only one sample. Add samples: %d \"\n \"(or more), or remove agree.\" % (node.name, required, required)\n )\n return 1, 1\n if required is None or required == 0:\n return samples, samples // 2 + 1\n if required < 2:\n raise GateError(\n \"node %r asks for agree: %d, which accepts the first answer and never draws \"\n \"the other %d. Use agree: 2 or more, or remove samples.\"\n % (node.name, required, samples - 1)\n )\n if required > samples:\n raise GateError(\n \"node %r asks for agree: %d out of samples: %d, which no run can satisfy. \"\n \"Raise samples to at least %d, or lower agree.\"\n % (node.name, required, samples, required)\n )\n return samples, required\n\n\ndef _whole(key, value, node):\n \"\"\"`value` as a non-negative whole number, or None when the node did not set it.\"\"\"\n if value is None:\n return None\n # `isinstance(True, int)` is True in Python, and `samples: yes` is a plausible slip in\n # a YAML file. A boolean here is a key that was misunderstood, not a count.\n if not isinstance(value, int) or isinstance(value, bool):\n raise GateError(\n \"node %r has %s: %r — it must be a whole number, not %s\"\n % (node.name, key, value, type(value).__name__)\n )\n if value < 0:\n raise GateError(\"node %r has %s: %d — it cannot be negative\"\n % (node.name, key, value))\n return value\n\n\ndef run_node(node, state, model, attempts=None, consensus=None):\n \"\"\"Generate, verify, and return the object to commit.\n\n Raises `NodeFailed` when no draw could be verified, and `Unsure` when the draws were\n all valid and did not agree. Those are different outcomes and this module keeps them\n different; see the module docstring for why, and for what a walker should do with the\n second one.\n\n `retries` is the number of *re-samples* after the first attempt, so the default of 2\n buys three generations — per draw. `samples` (default 1) is how many verified answers\n the node wants compared, and `agree` (default: a strict majority) is how many of them\n must match. A node that sets neither draws once and behaves exactly as it always has,\n down to the bytes of the request.\n\n `attempts` is an optional dict the caller owns; the generations this node spends are\n added to it under the node's name, whether the node ends up succeeding or failing.\n That is how a finished run can say it needed three attempts at node 40 — see\n `graph.RunResult.attempts`.\n\n `consensus` is the same arrangement for the gate: an optional dict the caller owns,\n which gets a `Consensus` under the node's name whenever the node drew more than once.\n A node absent from it drew once and had nothing to compare — the same convention\n `attempts` uses for a node that spent no rungs. A node inside a loop leaves its most\n recent visit there, the way `provenance` records the most recent writer.\n\n A prompt that names state nobody wrote raises `MissingVariable` out of here\n untouched, before any generation is spent: no re-sample can fix a template, so the\n ladder is skipped rather than burned. The walker routes it to the node's `on_fail`\n exactly as it routes `NodeFailed` — a node that cannot produce a verified output is\n what that edge is for.\n \"\"\"\n samples, required = gate_for(node)\n if samples > 1 and not accepts_sampling(model) and _log.isEnabledFor(WARNING):\n # The failure this catches is silent by nature: identical requests produce\n # identical answers, the draws \"agree\", and the pack reports high confidence it\n # never measured. An operator has to be told, because the run will look fine.\n event(_log, WARNING, \"node.samples.blind\", node=node.name, samples=samples,\n model=type(model).__name__,\n reason=\"backend takes no sampling hint, so extra draws repeat the first\")\n\n spent = 0 # generations this visit has paid for, rejections included\n counts = {} # canonical form -> how many draws produced it\n answers = {} # canonical form -> the object itself, from the first draw of it\n drawn = 0\n for draw in range(samples):\n try:\n value, cost = _ladder(node, state, model, draw)\n except NodeFailed as exc:\n # A draw that could not be verified is a rejection, and a node that cannot\n # produce a valid answer has produced no evidence about anything — so this\n # ends the node rather than counting as one dissenting voice.\n _tally(attempts, node.name, exc.attempts)\n if not spent:\n # Nothing came before it: this is the single-draw failure the ladder has\n # always raised, handed on exactly as it was built.\n raise\n raise NodeFailed(exc.node, exc.reason, attempts=spent + exc.attempts,\n feedback=exc.feedback)\n spent += cost\n drawn += 1\n _tally(attempts, node.name, cost)\n if samples == 1:\n # The overwhelming majority of nodes. One draw commits itself; there is\n # nothing to compare it with, and none of the bookkeeping below is paid for.\n return value\n\n key = _canonical(value)\n counts[key] = counts.get(key, 0) + 1\n answers.setdefault(key, value)\n if _log.isEnabledFor(DEBUG):\n event(_log, DEBUG, \"node.sample\", node=node.name, draw=drawn, of=samples,\n matched=counts[key], needed=required)\n if counts[key] >= required:\n # Short-circuit: enough draws already match, and the ones not yet taken\n # cannot change that. `samples: 3, agree: 2` costs two generations when the\n # first two match, which is the common case a gate is worth paying for.\n record = _report(consensus, node, samples, drawn, counts[key], required,\n spent, len(counts))\n # INFO, once per sampled node rather than once per generation: a gate that\n # quietly costs three generations on every node is the same kind of\n # unnoticed bill the retry rung is logged for. Counts only, so the line is\n # safe wherever an operator ships it.\n event(_log, INFO, \"node.agreed\", node=node.name, agreed=record.agreed,\n of=drawn, required=required, asked=samples, generations=spent)\n return value\n if max(counts.values()) + (samples - drawn) < required:\n # The other short-circuit: no group can still reach the threshold, so the\n # remaining draws would cost tokens to confirm an answer already known.\n break\n\n # Ties go to the earliest draw: `max` keeps the first key it saw at that count and\n # dicts preserve insertion order, so the answer reported as closest is the same one\n # every time rather than whichever the dict happened to hold first.\n leader = max(counts, key=lambda key: counts[key])\n record = _report(consensus, node, samples, drawn, counts[leader], required, spent,\n len(counts))\n event(_log, WARNING, \"node.unsure\", node=node.name, agreed=record.agreed, of=drawn,\n required=required, asked=samples, distinct=record.distinct,\n generations=spent)\n raise Unsure(node.name, record, value=answers[leader])\n\n\ndef _report(consensus, node, samples, drawn, agreed, required, spent, distinct):\n \"\"\"Build this visit's `Consensus`, and leave it in the caller's dict if it kept one.\"\"\"\n record = Consensus(node=node.name, asked=samples, drawn=drawn, agreed=agreed,\n required=required, generations=spent, distinct=distinct)\n if consensus is not None:\n consensus[node.name] = record\n return record\n\n\ndef _canonical(value):\n \"\"\"The comparison key for one draw: the committed object as canonical JSON.\n\n Sorted keys so that two draws that emitted the same fields in a different order are\n one answer, and no whitespace so that formatting is never mistaken for disagreement.\n Nothing here can fail: `verify` only ever returns a dict that came out of `json.loads`\n and survived the JSON-shape check, so it is round-trippable by construction.\n \"\"\"\n return json.dumps(value, sort_keys=True, separators=(\",\", \":\"))\n\n\ndef _ladder(node, state, model, draw=0):\n \"\"\"One verified draw and what it cost, or `NodeFailed` when the rungs run out.\n\n This is the retry ladder, and it is per draw. A sampled node runs it once per draw,\n each time from rung 0 with no feedback and no scratchpad carried over: a draw\n conditioned on another draw's rejection is not an independent draw, and agreement\n between draws that saw each other's mistakes is not evidence.\n \"\"\"\n rungs = node.retries + 1\n scratchpad = None\n reason = \"no attempts were made\"\n feedback = None\n spent = 0\n for rung in range(rungs):\n # `feedback` is None on the first attempt and the previous rejection after that;\n # `sampling_for` makes every rung after the first an independent draw wherever\n # the backend can manage one — and every draw after the first, for the same\n # reason at the other scale.\n sampling = sampling_for(rung, draw)\n # `rung and ...` short-circuits on the first attempt, so the happy path through\n # this loop — the overwhelming majority of generations — asks the logging layer\n # nothing at all. The first attempt is not silent: `codegen` logs `node.emit`\n # with the prompt size, and `graph` logs `node.ok` when it lands. There is no\n # event here that only restates one of those.\n if rung and _log.isEnabledFor(INFO):\n # The rung an operator is paying for. INFO rather than DEBUG because a pack\n # that quietly burns two extra generations on node 40 of every run is the\n # single most expensive thing that can go unnoticed here, and `reason` is\n # the model-safe half by construction — it is the same text the next prompt\n # is allowed to carry.\n event(_log, INFO, \"node.retry\", node=node.name, attempt=rung + 1, of=rungs,\n temperature=sampling.temperature if sampling else None,\n seed=sampling.seed if sampling else None, reason=feedback,\n rethink=bool(node.two_stage and scratchpad is None))\n try:\n candidate = generate_once(\n node, state, model, error=feedback, scratchpad=scratchpad,\n sampling=sampling,\n )\n except BackendError as exc:\n if not getattr(exc, \"empty_content\", False):\n raise\n # The endpoint answered and this draw simply had no text in it. That is a\n # rejection — one rung of the ladder — not a reason to abort the run past\n # the node's declared `on_fail`. The backend's own diagnostic is the detail\n # an operator needs, so it is kept verbatim; the model is told only that its\n # answer arrived empty.\n spent += 1\n reason, feedback = str(exc), EMPTY_COMPLETION_FEEDBACK\n # The backend's diagnostic names the endpoint and the finish reason and\n # quotes no generation, so it is safe at WARNING as it stands. `clip` runs\n # over text of unbounded length, which is exactly the kind of work that must\n # not happen when nobody is listening — hence the guard rather than trusting\n # `event` to throw the result away.\n if _log.isEnabledFor(WARNING):\n event(_log, WARNING, \"node.rejected\", node=node.name, attempt=spent,\n cause=\"empty_completion\", reason=EMPTY_COMPLETION_FEEDBACK,\n detail=clip(reason))\n # Nothing about a two-stage node's notes was judged here, so the next rung\n # keeps them: `codegen.generate_once` hands back the notes of the attempt\n # that never got an answer.\n scratchpad = getattr(exc, \"scratchpad\", None) or scratchpad\n continue\n spent += 1\n try:\n value = verify(node, candidate.text, state)\n except Rejected as exc:\n # `reason` keeps the whole story for diagnostics; `feedback` is the only\n # part that may be shown to the model on the next rung. The notes behind a\n # rejected answer are discarded with it: the reasoning is what the emit\n # stage obeyed, so it is part of what was just judged.\n reason = str(exc)\n feedback = exc.feedback\n scratchpad = None\n # The split that rule 2 of this module's docstring is about, spelled out at\n # the one place both halves are in scope. `feedback` says what was wrong and\n # is derived from the pack's own schema, so it goes out at WARNING where an\n # operator shipping logs to a collector will see it. `detail` may quote the\n # generation verbatim, so it is DEBUG-only: someone who asked for DEBUG asked\n # to read what came back, and a log file cannot condition a model — but a\n # default-level line that carried it would put rejected model output into\n # every collector stepmold is ever pointed at.\n if _log.isEnabledFor(WARNING):\n event(_log, WARNING, \"node.rejected\", node=node.name, attempt=spent,\n cause=\"verify\", reason=feedback, of=rungs)\n if _log.isEnabledFor(DEBUG):\n event(_log, DEBUG, \"node.rejected.detail\", node=node.name,\n attempt=spent, detail=clip(reason))\n continue\n return value, spent\n # The count rides on the exception rather than being tallied here, because the caller\n # is the one that knows whether earlier draws of the same visit have already been\n # charged for.\n raise NodeFailed(node.name, reason, attempts=spent, feedback=feedback)\n\n\ndef _tally(attempts, name, spent):\n \"\"\"Add this visit's generations to the run's per-node count.\n\n Added rather than assigned: a node inside a loop is visited more than once, and what\n an operator is reading this for is what the node cost the run — and a sampled node\n adds every draw's ladder to the same total, because every one of them is on the bill.\n \"\"\"\n if attempts is not None and spent:\n attempts[name] = attempts.get(name, 0) + spent\n\n\ndef verify(node, text, state):\n \"\"\"Return the object `text` commits to, or raise `Rejected` saying why not.\"\"\"\n value = extract_json(text)\n if not isinstance(value, dict):\n raise Rejected(\n \"output must be a JSON object, got %s\" % type(value).__name__\n )\n # Always, even with no schema. `validate_against` runs a JSON-shape check (no NaN or\n # Infinity, nothing nested past the ceiling) before it looks at the schema, and shape\n # is not a schema question — a value JSON cannot represent is bad output whether or not\n # a node declared constraints. Guarding this with `if node.grammar:` skipped it for a\n # free-form node, which the pack format documents `{}` as being: NaN then committed,\n # printed as a bare NaN no strict reader can parse, and killed a checkpointed run AFTER\n # the commit — the exact hazard checking-before-commit exists to prevent. An empty\n # schema constrains nothing, so free-form nodes stay free.\n try:\n validate_against(node.grammar or {}, value)\n except ValidationError as exc:\n raise Rejected(\"schema: %s\" % exc, feedback=\"schema: %s\" % exc.safe_text)\n if node.assert_expr:\n _check_assert(node, value, state)\n return value\n\n\ndef _check_assert(node, value, state):\n \"\"\"Evaluate the node's assert against state *as it would be if committed*.\n\n The trial scope is a copy. A candidate that fails here is discarded whole, so the\n real state never saw it.\n \"\"\"\n trial = dict(state)\n if node.output:\n trial[node.output] = value\n else:\n trial.update(value)\n try:\n passed = is_true(node.assert_expr, trial)\n except ExprError as exc:\n raise Rejected(\"assert %r could not be evaluated: %s\" % (node.assert_expr, exc))\n if not passed:\n raise Rejected(\"assert failed: %s\" % node.assert_expr)\n\n\ndef extract_json(text):\n \"\"\"Pull an object out of a generation.\n\n With a real constrained decoder the text is already exact JSON. Backends without\n grammar support (and llama.cpp's looser modes) still wrap it in prose or a fence, so\n this is forgiving about *finding* the object — and `verify` stays merciless about\n what is in it.\n \"\"\"\n if not isinstance(text, str):\n raise Rejected(\"model returned %s, not text\" % type(text).__name__)\n for attempt in _candidates(text.strip()):\n try:\n return json.loads(attempt)\n except ValueError:\n continue\n except RecursionError:\n # Deeply nested output exhausts the decoder's own stack. On CPython before\n # 3.12 this escapes json.loads as RecursionError rather than ValueError, so\n # without this it is not a Rejected, bypasses the retry ladder and the node's\n # on_fail edge, and kills the run. A model that emits 10,000 nested arrays is\n # a bad generation, not a broken runtime — reject it like any other.\n raise Rejected(\n \"output nested too deeply to parse (%d bytes)\" % len(text),\n feedback=\"output was nested too deeply — return a flat JSON object\",\n )\n raise Rejected(\n \"output was not valid JSON: %s\" % _clip(text),\n feedback=\"output was not valid JSON — return a single JSON object and nothing else\",\n )\n\n\ndef _candidates(text):\n \"\"\"Every span worth parsing, best first: the whole answer, a fence, then objects.\n\n The objects come out **last one first**, and that ordering is a security property\n rather than a preference. A small model restates the format it was given, or quotes\n the ticket it was handed, and *then* answers; taking the first balanced `{...}` in\n the text hands the node whatever the model was merely repeating — user-controlled\n text, schema-validated and committed, which is the one thing verify-before-commit\n exists to prevent. What a model says last is its answer; everything before it is\n preamble.\n\n Deliberately *not* \"the object that validates against the node's schema\". That rule\n reads better until the model's own answer is the imperfect one: the echo then\n outranks it, and a rejection the ladder could have fixed becomes a silent commit of\n quoted input. Selection stays blind to the schema; earlier spans are reached only\n when the later ones do not parse at all, which is how a valid object behind a\n braces-in-prose span is still recovered.\n \"\"\"\n yield text\n fenced = _unfence(text)\n if fenced is not None:\n yield fenced\n for span in reversed(_objects(text)):\n yield span\n\n\ndef _unfence(text):\n if not text.startswith(\"```\"):\n return None\n body = text[3:]\n newline = body.find(\"\\n\")\n if newline == -1:\n return None\n body = body[newline + 1:]\n end = body.rfind(\"```\")\n return body[:end].strip() if end != -1 else body.strip()\n\n\ndef _objects(text):\n \"\"\"Every balanced top-level `{...}` span, in order, ignoring braces inside strings.\"\"\"\n spans = []\n depth = 0\n quote = False\n start = -1\n index = 0\n while index < len(text):\n char = text[index]\n if quote:\n if char == \"\\\\\":\n index += 2\n continue\n if char == '\"':\n quote = False\n elif char == '\"':\n # Only quotes *inside* a span can hide a brace; prose before one is not JSON\n # and its apostrophes and quotes must not swallow the object that follows.\n if depth:\n quote = True\n elif char == \"{\":\n if depth == 0:\n start = index\n depth += 1\n elif char == \"}\" and depth:\n depth -= 1\n if depth == 0:\n spans.append(text[start:index + 1])\n index += 1\n return spans\n\n\ndef _clip(text, limit=120):\n text = \" \".join(str(text).split())\n return text if len(text) <= limit else text[:limit] + \"...\"\n", "stepmold/yamlish.py": "\"\"\"A YAML subset parser, because stepmold may not install PyYAML.\n\n`TASKS.md` specifies the pack format as `manifest.yaml` / `graph.yaml`, and the\nproject rule is standard library only. The standard library has no YAML parser, so\nthis is the minimal piece implemented by hand (see NIGHT-LOG.md, T2).\n\nSupported: block mappings, block sequences, nesting by indentation, `#` comments,\nsingle-line flow collections (`[a, b]`, `{a: 1}`), quoted and plain scalars, block and\nfolded scalars (`|`, `>`, with `-`/`+` chomping), and the scalar types\nnull / bool / int / float / str.\n\nDeliberately unsupported, each with a clear error: anchors and aliases, tags, multiple\ndocuments, complex keys, block scalar lines indented less than the block they are in,\n`key:value` without a space in a flow mapping, empty flow entries, and the C0 controls\n`str.splitlines()` would mistake for line breaks. Pack files do not need them, and every\nunsupported construct fails loudly rather than silently: where this parser cannot match\nreal YAML it refuses the input by name rather than guessing a value, because the pack\nformat is meant to read the same in a future Go or TypeScript runtime (docs/ARCHITECTURE.md §7).\n\"\"\"\n\nimport re\n\n__all__ = [\"YamlError\", \"parse\"]\n\n\nclass YamlError(ValueError):\n \"\"\"A YAML document stepmold cannot parse, with the line it gave up on.\"\"\"\n\n\n_INT = re.compile(r\"^[-+]?[0-9][0-9_]*$\")\n_FLOAT = re.compile(r\"^[-+]?(?:[0-9][0-9_]*)?\\.[0-9_]+(?:[eE][-+]?[0-9]+)?$|\"\n r\"^[-+]?[0-9][0-9_]*[eE][-+]?[0-9]+$\")\n_NULL = (\"\", \"~\", \"null\", \"Null\", \"NULL\")\n_TRUE = (\"true\", \"True\", \"TRUE\", \"yes\", \"Yes\", \"YES\", \"on\", \"On\", \"ON\")\n_FALSE = (\"false\", \"False\", \"FALSE\", \"no\", \"No\", \"NO\", \"off\", \"Off\", \"OFF\")\n_UNSUPPORTED = {\n \"&\": \"anchors (`&`)\",\n \"*\": \"aliases (`*`)\",\n \"!\": \"tags (`!`)\",\n}\n_BLOCK_HEADER = re.compile(r\"^([|>])([-+]?)$\")\n# str.splitlines() breaks on these, so a document containing one would be silently\n# re-flowed into extra lines. Real YAML rejects them outright, so stepmold does too. (NEL\n# and U+2028/U+2029 are left alone: real YAML treats those as line breaks as well.)\n_CONTROLS = \"\\x0b\\x0c\\x1c\\x1d\\x1e\"\n\n\nclass _Line(object):\n __slots__ = (\"indent\", \"text\", \"lineno\", \"block\")\n\n def __init__(self, indent, text, lineno, block=None):\n self.indent = indent\n self.text = text\n self.lineno = lineno\n self.block = block # resolved text when this line opened a `|` or `>` scalar\n\n\ndef parse(text, filename=\"\"):\n \"\"\"Parse a YAML subset document into plain Python data.\"\"\"\n lines = _lex(text, filename)\n if not lines:\n return None\n if lines[0].indent != 0:\n raise _err(filename, lines[0], \"document must not start indented\")\n value, index = _parse_block(lines, 0, 0, filename)\n if index != len(lines):\n raise _err(filename, lines[index], \"unexpected content\")\n return value\n\n\n# --------------------------------------------------------------------------- lexing\n\n\ndef _lex(text, filename):\n _reject_controls(text, filename)\n raw_lines = text.splitlines()\n out = []\n index = 0\n started = False # a `---` has opened the one document stepmold accepts\n ended = False # a `...` has closed it\n while index < len(raw_lines):\n raw = raw_lines[index]\n number = index + 1\n if \"\\t\" in raw[: len(raw) - len(raw.lstrip(\" \\t\"))]:\n raise YamlError(\n \"%s:%d: tabs cannot be used for indentation\" % (filename, number)\n )\n stripped = _strip_comment(raw)\n if not stripped.strip():\n index += 1\n continue\n marker = stripped.strip()\n if marker in (\"---\", \"...\"):\n # One document is fine to frame; a second one would be silently merged\n # into the first, so refuse it by name.\n if marker == \"---\" and (started or out or ended):\n raise YamlError(\n \"%s:%d: stepmold's YAML subset does not support multiple \"\n \"documents (`---`)\" % (filename, number)\n )\n started = started or marker == \"---\"\n ended = ended or marker == \"...\"\n index += 1\n continue\n if ended:\n raise YamlError(\n \"%s:%d: content after `...`; stepmold's YAML subset does not support \"\n \"multiple documents\" % (filename, number)\n )\n indent = len(stripped) - len(stripped.lstrip(\" \"))\n content = stripped.strip()\n\n header = _block_header(content)\n if header is None:\n out.append(_Line(indent, content, number))\n index += 1\n continue\n\n style, chomp = header\n if chomp == \"+\":\n raise YamlError(\n \"%s:%d: stepmold's YAML subset does not support keep chomping (`%s+`)\"\n % (filename, number, style)\n )\n parent = _block_parent_indent(indent, content)\n body, index = _block_body(raw_lines, index + 1, parent, filename, number)\n out.append(_Line(indent, content, number, block=_fold(body, style, chomp)))\n return out\n\n\ndef _reject_controls(text, filename):\n \"\"\"Refuse the C0 controls `str.splitlines()` would treat as line breaks.\"\"\"\n hits = [found for found in (text.find(char) for char in _CONTROLS) if found >= 0]\n if not hits:\n return\n at = min(hits)\n # The sentinel keeps a break that ends the prefix from being dropped by\n # splitlines(), so a control on a fresh line reports that line, not the one before.\n number = len((text[:at] + \".\").splitlines())\n raise YamlError(\n \"%s:%d: control character %r is not allowed\" % (filename, number, text[at])\n )\n\n\ndef _block_parent_indent(indent, content):\n \"\"\"The column a line must out-indent to stay inside the block scalar in `content`.\n\n A block scalar's body belongs to its parent node. For `- |` the parent is the\n sequence, so the body only has to clear the dash. For `- key: |` the parent is the\n mapping that starts after the dash, so a sibling key in that mapping ends the body\n instead of being swallowed and re-sliced into the value.\n \"\"\"\n while _is_item(content):\n rest = content[2:]\n offset = 2 + (len(rest) - len(rest.lstrip(\" \")))\n rest = rest.strip()\n if _split_key(rest) is None and not _is_item(rest):\n break\n indent += offset\n content = rest\n return indent\n\n\ndef _block_header(content):\n \"\"\"Return (style, chomp) when `content` ends in a `|`/`>` scalar header.\"\"\"\n marker = content\n if \":\" in content:\n split = _split_key(content)\n if split is None:\n return None\n marker = split[1]\n elif content.startswith(\"- \"):\n marker = content[2:].strip()\n match = _BLOCK_HEADER.match(marker)\n return (match.group(1), match.group(2)) if match else None\n\n\ndef _block_body(raw_lines, index, indent, filename, opened_at):\n \"\"\"Collect the raw lines belonging to a block scalar opened at `indent`.\"\"\"\n body = []\n block_indent = None\n while index < len(raw_lines):\n raw = raw_lines[index]\n if raw.strip():\n current = len(raw) - len(raw.lstrip(\" \"))\n if current <= indent:\n break\n if block_indent is None:\n block_indent = current\n if current < block_indent:\n # Slicing at block_indent would delete leading characters and hand\n # back a plausible-looking wrong value, so refuse instead.\n raise YamlError(\n \"%s:%d: line is indented less than the block scalar opened on \"\n \"line %d\" % (filename, index + 1, opened_at)\n )\n body.append(raw[block_indent:])\n else:\n body.append(\"\")\n index += 1\n while body and not body[-1].strip():\n body.pop() # trailing blank lines are not content\n return body, index\n\n\ndef _fold(body, style, chomp):\n \"\"\"Apply literal/folded joining and `-`/`+` chomping to a block scalar body.\"\"\"\n if not body:\n return \"\" # an empty block scalar is the empty string, not a lone break\n if style == \"|\":\n text = \"\\n\".join(body)\n else:\n text = _fold_lines(body)\n return text.rstrip(\"\\n\") if chomp == \"-\" else text + \"\\n\"\n\n\ndef _fold_lines(body):\n \"\"\"Join a folded (`>`) body: breaks become spaces only between plain lines.\n\n A run of blank lines becomes that many breaks, and a line more indented than the\n block is kept verbatim with the breaks around it, because YAML folds only the\n lines it can safely re-flow.\n \"\"\"\n parts = []\n previous = None # the last non-blank line, or None before any content\n blanks = 0\n for line in body:\n if not line.strip():\n blanks += 1\n continue\n if previous is None:\n parts.append(\"\\n\" * blanks)\n elif previous.startswith(\" \") or line.startswith(\" \"):\n parts.append(\"\\n\" * (blanks + 1))\n else:\n parts.append(\"\\n\" * blanks if blanks else \" \")\n parts.append(line.rstrip() if line.startswith(\" \") else line.strip())\n previous = line\n blanks = 0\n return \"\".join(parts)\n\n\ndef _strip_comment(raw):\n quote = None\n for index, char in enumerate(raw):\n if quote:\n if char == quote:\n quote = None\n elif char in \"'\\\"\" and (index == 0 or raw[index - 1] in \" \\t[{,\"):\n # A quote only opens a string where a token may start. Inside a plain\n # scalar (`o'brien`, `6\" pipe`, `b:'c`) it is just a character, and\n # treating it as a string would swallow the `#` of any comment after it.\n quote = char\n elif char == \"#\" and (index == 0 or raw[index - 1] in \" \\t\"):\n return raw[:index]\n return raw\n\n\n# --------------------------------------------------------------------------- blocks\n\n\ndef _parse_block(lines, index, indent, filename):\n if _is_item(lines[index].text):\n return _parse_sequence(lines, index, indent, filename)\n return _parse_mapping(lines, index, indent, filename)\n\n\ndef _is_item(text):\n return text == \"-\" or text.startswith(\"- \")\n\n\ndef _parse_mapping(lines, index, indent, filename):\n out = {}\n while index < len(lines) and lines[index].indent == indent:\n line = lines[index]\n if _is_item(line.text):\n raise _err(filename, line, \"sequence item where a mapping key was expected\")\n split = _split_key(line.text)\n if split is None:\n raise _err(filename, line, \"expected 'key: value'\")\n key_text, rest = split\n key = _scalar(key_text, filename, line)\n if not isinstance(key, (str, int, float, bool)) and key is not None:\n raise _err(filename, line, \"unsupported complex key\")\n if key in out:\n raise _err(filename, line, \"duplicate key %r\" % (key,))\n if line.block is not None:\n out[key] = line.block\n index += 1\n elif rest:\n out[key] = _value(rest, filename, line)\n index += 1\n else:\n child = index + 1\n if child < len(lines) and lines[child].indent > indent:\n out[key], index = _parse_block(\n lines, child, lines[child].indent, filename\n )\n else:\n out[key] = None\n index += 1\n if index < len(lines) and lines[index].indent > indent:\n raise _err(filename, lines[index], \"unexpected indentation\")\n return out, index\n\n\ndef _parse_sequence(lines, index, indent, filename):\n out = []\n while (\n index < len(lines)\n and lines[index].indent == indent\n and _is_item(lines[index].text)\n ):\n line = lines[index]\n if line.text == \"-\":\n child = index + 1\n if child < len(lines) and lines[child].indent > indent:\n value, index = _parse_block(lines, child, lines[child].indent, filename)\n else:\n value, index = None, index + 1\n out.append(value)\n continue\n rest = line.text[2:]\n offset = 2 + (len(rest) - len(rest.lstrip(\" \")))\n rest = rest.strip()\n if _split_key(rest) is not None or _is_item(rest):\n # A collection opened on the dash line: re-read it as its own block,\n # indented to the column the content actually starts at. Any block scalar\n # belongs to that inner mapping's key (`- when: |`), so it travels along.\n lines[index] = _Line(indent + offset, rest, line.lineno, line.block)\n value, index = _parse_block(lines, index, indent + offset, filename)\n elif line.block is not None:\n value, index = line.block, index + 1\n else:\n value, index = _value(rest, filename, line), index + 1\n out.append(value)\n if index < len(lines) and lines[index].indent > indent:\n raise _err(filename, lines[index], \"unexpected indentation\")\n return out, index\n\n\ndef _split_key(text):\n \"\"\"Split `key: value` at the first colon outside quotes and flow collections.\"\"\"\n quote = None\n depth = 0\n for index, char in enumerate(text):\n if quote:\n if char == quote:\n quote = None\n elif char in \"'\\\"\":\n quote = char\n elif char in \"[{\":\n depth += 1\n elif char in \"]}\":\n depth -= 1\n elif char == \":\" and depth == 0:\n after = text[index + 1:]\n if after and not after.startswith(\" \"):\n continue\n return text[:index].strip(), after.strip()\n return None\n\n\n# --------------------------------------------------------------------------- scalars\n\n\ndef _value(text, filename, line):\n if text.startswith(\"[\") or text.startswith(\"{\"):\n value, rest = _flow(text, filename, line)\n if rest.strip():\n raise _err(filename, line, \"trailing content after flow collection\")\n return value\n return _scalar(text, filename, line)\n\n\ndef _flow(text, filename, line):\n if text.startswith(\"[\"):\n return _flow_collection(text, \"]\", filename, line, mapping=False)\n return _flow_collection(text, \"}\", filename, line, mapping=True)\n\n\ndef _flow_collection(text, closer, filename, line, mapping):\n out = {} if mapping else []\n rest = text[1:].lstrip()\n while True:\n if not rest:\n raise _err(filename, line, \"unterminated flow collection\")\n if rest.startswith(closer):\n # The collection is empty, or a comma just ended the last entry: real\n # YAML allows a trailing comma, and it must not invent an entry.\n return out, rest[1:]\n if rest.startswith(\",\"):\n raise _err(filename, line, \"empty entry in flow collection\")\n if rest[0] in \"[{\":\n item, rest = _flow(rest, filename, line)\n key = None\n quoted = False\n else:\n quoted = rest[0] in \"'\\\"\"\n token, rest = _flow_token(rest, closer, filename, line)\n item = None\n key = token\n if mapping:\n if key is None:\n raise _err(filename, line, \"flow mapping keys must be scalars\")\n if not key.endswith(\":\") and not rest.startswith(\":\"):\n raise _err(filename, line, \"expected 'key: value' in flow mapping\")\n if rest.startswith(\":\"):\n if not quoted and rest[1:2] not in (\"\", \" \", \",\", closer):\n # Real YAML reads `{key:value}` as the single scalar 'key:value',\n # so guessing a pair here would diverge from every other reader.\n raise _err(filename, line,\n \"flow mapping needs a space after ':' (real YAML reads \"\n \"'key:value' as one scalar)\")\n rest = rest[1:].lstrip()\n else:\n key = key[:-1].strip()\n if key.endswith(\":\"):\n key = key[:-1].strip()\n if rest[:1] in (\"[\", \"{\"):\n value, rest = _flow(rest, filename, line)\n else:\n token, rest = _flow_token(rest, closer, filename, line)\n value = _scalar(token, filename, line)\n out[_scalar(key, filename, line)] = value\n else:\n out.append(item if key is None else _scalar(key, filename, line))\n rest = rest.lstrip()\n if rest.startswith(\",\"):\n rest = rest[1:].lstrip()\n continue\n if rest.startswith(closer):\n return out, rest[1:]\n raise _err(filename, line, \"expected ',' or '%s' in flow collection\" % closer)\n\n\ndef _flow_token(text, closer, filename, line):\n if text[:1] in (\"'\", '\"'):\n quote = text[0]\n end = _closing_quote(text, quote)\n if end < 0:\n raise _err(filename, line, \"unterminated quoted string\")\n return text[: end + 1], text[end + 1:].lstrip()\n stop = len(text)\n for index, char in enumerate(text):\n if char in \",:\" or char in \"]}\":\n stop = index\n break\n return text[:stop].strip(), text[stop:]\n\n\ndef _closing_quote(text, quote):\n index = 1\n while index < len(text):\n if text[index] == \"\\\\\" and quote == '\"':\n index += 2\n continue\n if text[index] == quote:\n if quote == \"'\" and text[index + 1:index + 2] == \"'\":\n index += 2 # '' is an escaped quote inside a single-quoted scalar\n continue\n return index\n index += 1\n return -1\n\n\ndef _scalar(text, filename, line):\n text = text.strip()\n if text[:1] in _UNSUPPORTED and text[:1] not in (\"-\", \"+\"):\n raise _err(filename, line, \"stepmold's YAML subset does not support %s\"\n % _UNSUPPORTED[text[0]])\n if text[:1] == \"'\":\n return _unquote_single(text, filename, line)\n if text[:1] == '\"':\n return _unquote_double(text, filename, line)\n if text in _NULL:\n return None\n if text in _TRUE:\n return True\n if text in _FALSE:\n return False\n if _INT.match(text):\n return int(text.replace(\"_\", \"\"))\n if _FLOAT.match(text):\n return float(text.replace(\"_\", \"\"))\n return text\n\n\ndef _unquote_single(text, filename, line):\n end = _closing_quote(text, \"'\")\n if end != len(text) - 1:\n raise _err(filename, line, \"unterminated quoted string\")\n return text[1:end].replace(\"''\", \"'\")\n\n\n_ESCAPES = {\"n\": \"\\n\", \"t\": \"\\t\", \"r\": \"\\r\", \"0\": \"\\0\", '\"': '\"', \"\\\\\": \"\\\\\", \"/\": \"/\"}\n\n\ndef _unquote_double(text, filename, line):\n end = _closing_quote(text, '\"')\n if end != len(text) - 1:\n raise _err(filename, line, \"unterminated quoted string\")\n body = text[1:end]\n out = []\n index = 0\n while index < len(body):\n char = body[index]\n if char == \"\\\\\" and index + 1 < len(body):\n following = body[index + 1]\n if following == \"u\":\n out.append(chr(int(body[index + 2:index + 6], 16)))\n index += 6\n continue\n if following not in _ESCAPES:\n raise _err(filename, line, \"unknown escape '\\\\%s'\" % following)\n out.append(_ESCAPES[following])\n index += 2\n continue\n out.append(char)\n index += 1\n return \"\".join(out)\n\n\ndef _err(filename, line, message):\n return YamlError(\"%s:%d: %s\" % (filename, line.lineno, message))\n" } }