dirigent-examples 0.18.2__tar.gz → 0.18.3__tar.gz

{dirigent_examples-0.18.2 → dirigent_examples-0.18.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: dirigent-examples
-Version: 0.18.2
+Version: 0.18.3
 Summary: The dirigent example corpus: the shelves of runnable documents, installed.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-client==0.18.2
-Requires-Dist: dirigent-plugin==0.18.2
+Requires-Dist: dirigent-client==0.18.3
+Requires-Dist: dirigent-plugin==0.18.3
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 

{dirigent_examples-0.18.2 → dirigent_examples-0.18.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-examples"
-version = "0.18.2"
+version = "0.18.3"
 description = "The dirigent example corpus: the shelves of runnable documents, installed."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,8 +11,8 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-client==0.18.2",
-    "dirigent-plugin==0.18.2",
+    "dirigent-client==0.18.3",
+    "dirigent-plugin==0.18.3",
 ]
 
 [project.entry-points."dirigent.plugins.v1"]

{dirigent_examples-0.18.2 → dirigent_examples-0.18.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-examples"
-version = "0.18.2"
+version = "0.18.3"
 description = "The dirigent example corpus: the shelves of runnable documents, installed."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -12,8 +12,8 @@ classifiers = [
 ]
 dependencies = [
     # The python/ shelf is SDK scripts a reader runs, so the corpus carries the client.
-    "dirigent-client==0.18.2",
-    "dirigent-plugin==0.18.2",
+    "dirigent-client==0.18.3",
+    "dirigent-plugin==0.18.3",
 ]
 
 [project.entry-points."dirigent.plugins.v1"]

{dirigent_examples-0.18.2 → dirigent_examples-0.18.3}/src/dirigent_examples/shelves/README.md

@@ -27,6 +27,7 @@ The documents live on topic shelves, each with its own README:
 | [`composition/`](composition) | Pipelines made of pipelines, and the handoff to a second instance. |
 | [`s3/`](s3) | Object storage through the `s3://` scheme, with no S3 block anywhere. |
 | [`demo/`](demo) | Surfaces shown off: the run form, rendered markdown, the requires preflight, the weekly-import shared-name pair. |
+| [`showcase/`](showcase) | Pipelines sized like the work: fifteen steps, eight-wide fan-outs, gates in the middle and a page at the end. |
 | [`open-data/`](open-data) | Real feeds against public, mostly keyless APIs: acme, health indicators, maps, earthquakes, humanitarian data. |
 | [`validate/`](validate) | A gate that checks a value's shape and passes it through: `validate.schema`, with the shape carried and named. |
 | [`schemas/`](schemas) | Not documents but the shapes they are held to: plain JSON Schemas, applied on their own and referenced by code. |
@@ -97,6 +98,7 @@ Not every one of them succeeds, and that is the point of three of them:
 | `failure/retry-budget.yaml` | `failed` | A command that always exits 1, given three attempts to prove it |
 | `failure/step-timeout.yaml` | `failed` | A thirty-second sleep against a two-second budget, so it fails in about two |
 | `graph/skip-diamond.yaml` | `succeeded` | Green, with one step skipped: the handler had nothing to handle |
+| `showcase/one-region-refuses.yaml` | `completed_with_errors` | One region's export answers 500 until its retry budget is spent; the other seven load |
 
 `dg run --local` applies and runs the document in a throwaway SQLite instance that is
 deleted afterwards -- no server, no Docker, no database. When a step fails it prints the
@@ -280,7 +282,7 @@ what a failure looks like, so the seeded one is deliberately mixed:
 
 | What lands | How many | Why |
 | --- | --- | --- |
-| Pipelines stored | 159 | Every document here that an instance will hold, including the ones that carry their own connections or schemas: the seed creates what they carry and applies the rest, which is the only form an instance stores |
+| Pipelines stored | 162 | Every document here that an instance will hold, including the ones that carry their own connections or schemas: the seed creates what they carry and applies the rest, which is the only form an instance stores |
 | Documents refused | 18 | Nine in [docker/](docker) and two in [git/](git) name a compose or a build block the seed does not allowlist, some of them also a connection it does not create; four name a connection that does not exist, one of them (`warehouse-nobody-created`) built by the seed on purpose; one names a schema no instance here holds; and two require a pipeline or a target applied after them |
 | Schedules | 17, all paused | `--paused` is what stops seventeen clocks starting to fire at somebody who has not looked at them |
 | Runs | 3 succeeded, 1 with errors, 2 failed | `hello-world`, `transform/jq-reshape.yaml` and `triggers/cron-windowed.yaml` settle green; `optional-step.yaml` settles `completed_with_errors`, which is a third status rather than a shade of failed; `error-handler.yaml` fails by design, and `s3-round-trip.yaml` cannot reach an object store nobody started |

dirigent_examples-0.18.3/src/dirigent_examples/shelves/showcase/README.md

@@ -0,0 +1,55 @@
+# Showcase
+
+Pipelines sized like the work, rather than cut down to one lesson. Every other shelf is
+deliberately small -- one behaviour per file, so nothing distracts from it. This one is the
+other extreme: documents with fifteen steps, eight-wide fan-outs, gates in the middle and a
+page at the end, because that is what an operated pipeline looks like and it is what the
+screens in [the screens page](../../docs/screens.md) are photographed on.
+
+Nothing here needs infrastructure, a credential, or an allowlist entry. The HTTP calls go to
+[Postman Echo](https://postman-echo.com), the schemas are carried in the documents, and the
+files land under the run's own scratch prefix.
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [nightly-regional-load.yaml](nightly-regional-load.yaml) | Fifteen steps: a maintenance window, a gated catalogue read, submit-then-probe per region, a per-region gate and write, two joins, and a page | `succeeded` |
+| [one-region-refuses.yaml](one-region-refuses.yaml) | Eight exports where one answers 500 until its retry budget is spent, the gap named rather than implied, and a report template of its own | `completed_with_errors` |
+| [morning-briefing.yaml](morning-briefing.yaml) | The three jq verbs one per hop -- `filter.jq`, `map.jq`, `transform.jq` -- four feeds each narrowed and banded, joined and gated | `succeeded` |
+
+```bash
+dg run --local examples/showcase/nightly-regional-load.yaml
+dg run --local examples/showcase/one-region-refuses.yaml     # completed_with_errors, by design
+dg run --local examples/showcase/morning-briefing.yaml
+```
+
+## Watching one happen
+
+A run that is green before the screen has drawn it teaches nothing about what a fan-out looks
+like while it is in flight. `nightly-regional-load.yaml` carries a `pace` for that: it is the
+seconds each region's export takes before its readiness probe answers, so eight items sit in
+progress for as long as you ask them to.
+
+```bash
+dg run --local examples/showcase/nightly-regional-load.yaml -p pace=6
+```
+
+On an instance, the same knob is what the run screen is photographed through:
+
+```bash
+dg apply examples/showcase/nightly-regional-load.yaml
+dg run nightly-regional-load -p pace=8 --watch
+```
+
+## What each one carries
+
+All three carry their own `schemas:`, so a `--local` run has the shapes without an instance
+holding them. An instance refuses a document that carries a schema, which is why
+`dg pipeline new` moves a carried section into `requires:` when it copies a starter.
+
+Two of them carry a `triggers:` section with a clock -- `nightly-regional-load` at 03:00 Oslo
+time, `morning-briefing` at 06:30 -- so applying either brings its schedule with it. `dg dev
+--seed` applies them paused.
+
+All three declare a `report:`, so every run of them writes its own account of itself:
+`one-region-refuses` brings a template that leads with the items that did not make it, and the
+other two take the page the engine ships.

dirigent_examples-0.18.3/src/dirigent_examples/shelves/showcase/morning-briefing.yaml

@@ -0,0 +1,258 @@
+# Four feeds, filtered and banded one feed at a time, joined into the page somebody reads.
+#
+# The other two documents on this shelf are about the night the data arrives. This is about
+# the morning after it: four feeds already collected, each narrowed to what is worth reading,
+# each reading labelled, and the four summaries joined into one briefing with a gate on it.
+#
+# In:  a day, and four feeds each carrying its own readings.
+# Out: a markdown briefing under the run's scratch prefix, read back and logged.
+#
+# THE DATA IS THE DOCUMENT'S OWN, AND IT MAKES A REAL ROUND TRIP. Postman Echo has no health
+# feed to serve, so each feed's readings are written here and posted to /post, which hands
+# them back. What is being taught is the shape of the flow, and nothing about it changes when
+# the url becomes a real one.
+#
+# THE JQ FAMILY IS THREE VERBS, AND EACH IS ONE HOP HERE:
+#
+#   filter.jq     keeps the elements a program answers true for. A list in, a shorter list out.
+#   map.jq        replaces every element with what a program makes of it. Same length, new shape.
+#   transform.jq  runs one program over the whole value, which is how a list becomes an object.
+#
+# HOP BY HOP:
+#
+#   pull            http.request, once per feed. The readings go out and come back.
+#   recent          filter.jq, once per feed: drop everything under the threshold.
+#   banded          map.jq, once per feed: label each surviving reading.
+#   feed_summary    transform.jq, once per feed: the list becomes one object.
+#   briefing        transform.jq, the join, with no for_each of its own.
+#   check_briefing  validate.schema, the gate the page is built from rather than around.
+#   page            report.render, the markdown.
+#   save            storage.write, the page under the run's scratch prefix.
+#   back            storage.read, the same URI, so the round trip is proven rather than assumed.
+#   announce        log.write, the page's text onto the run's own timeline.
+#
+# EXPECT THIS RUN TO SUCCEED in about a second, with four feeds in the briefing.
+#
+# TO CHANGE IT: raise `threshold` and watch feeds empty out, or hand it your own feeds. A feed
+# whose readings all fall below the threshold summarises as zero rather than failing, which is
+# what makes the gate below worth having: an empty feed is a shape, not an error.
+#
+#   dg run --local examples/showcase/morning-briefing.yaml
+#   dg run --local examples/showcase/morning-briefing.yaml -p threshold=70
+#
+#   dg apply examples/showcase/morning-briefing.yaml
+#   dg run morning-briefing --watch
+
+format: dirigent/v1
+kind: pipeline
+code: morning-briefing
+name: The morning briefing
+description: |
+  Four feeds, each filtered to what clears a threshold, each reading banded, each summarised,
+  and the four summaries joined into one gated briefing that is rendered, saved and read back.
+
+  The three jq verbs in one document: `filter.jq` narrows a list, `map.jq` reshapes its
+  elements, and `transform.jq` turns the list into an object.
+
+tags: [showcase, http, transform, validate, storage, report, fan-out, jq, filter, map, briefing, schedule, starter]
+
+requires:
+  blocks:
+    - http.request
+    - filter.jq
+    - map.jq
+    - transform.jq
+    - validate.schema
+    - storage.write
+    - storage.read
+    - report.render
+    - log.write
+
+params:
+  type: object
+  properties:
+    day:
+      type: string
+      format: date
+      default: "2026-03-01"
+      description: The day the briefing covers.
+    threshold:
+      type: integer
+      default: 40
+      minimum: 0
+      description: Readings under this are dropped before anything is said about them.
+    band_at:
+      type: integer
+      default: 60
+      minimum: 0
+      description: Readings at or above this are banded high rather than watch.
+    feeds:
+      type: array
+      description: One element per feed, each carrying the readings that feed reported.
+      minItems: 1
+      maxItems: 12
+      default:
+        - { feed: cases, readings: [18, 42, 61, 39, 77, 54, 23] }
+        - { feed: climate, readings: [31, 29, 44, 58, 66, 72, 19, 48] }
+        - { feed: stockouts, readings: [5, 12, 63, 81, 47, 22] }
+        - { feed: attendance, readings: [88, 91, 64, 59, 73, 45] }
+      items:
+        type: object
+        required: [feed, readings]
+        properties:
+          feed: { type: string }
+          readings:
+            type: array
+            items: { type: integer }
+
+# Carried, so `dg run --local` has the shape without an instance holding it.
+schemas:
+  daily-briefing:
+    type: object
+    required: [day, feeds]
+    additionalProperties: false
+    properties:
+      day: { type: string, format: date }
+      readings: { type: integer, minimum: 0 }
+      feeds:
+        type: array
+        minItems: 1
+        items:
+          type: object
+          required: [feed, reported, kept, high]
+          additionalProperties: false
+          properties:
+            feed: { type: string, minLength: 1 }
+            reported: { type: integer, minimum: 0 }
+            kept: { type: integer, minimum: 0 }
+            high: { type: integer, minimum: 0 }
+            peak: { type: [integer, "null"] }
+
+steps:
+  pull:
+    block: http.request
+    for_each: "${params.feeds}"
+    items: continue
+    retry:
+      max_attempts: 3
+      backoff: 1s
+      multiplier: 2.0
+      jitter: 0.2
+    config:
+      url: https://postman-echo.com/post
+      method: POST
+      body:
+        feed: "${item.feed}"
+        day: "${params.day}"
+        readings: "${item.readings}"
+
+  recent:
+    block: filter.jq
+    depends_on: [pull]
+    # pull's grid, so feed three here is feed three there.
+    for_each: "${steps.pull.items}"
+    config:
+      input: "${steps.pull.item.output.body.data.readings}"
+      # A filter program answers true or false for one element; the elements it answers true
+      # for are the output, in the order they arrived.
+      program: ". >= ${params.threshold}"
+
+  banded:
+    block: map.jq
+    depends_on: [recent]
+    for_each: "${steps.recent.items}"
+    config:
+      input: "${steps.recent.item.output.value}"
+      # A map program is run per element and its answer replaces the element, so an integer
+      # becomes the object the page wants to read.
+      program: "{value: ., band: (if . >= ${params.band_at} then \"high\" else \"watch\" end)}"
+
+  feed_summary:
+    block: transform.jq
+    depends_on: [pull, banded]
+    for_each: "${steps.banded.items}"
+    config:
+      input:
+        feed: "${item.feed}"
+        reported: "${steps.pull.item.output.body.data.readings}"
+        kept: "${steps.banded.item.output.value}"
+      # One program over the whole value, which is what turns a list into an object.
+      program: |
+        {feed: .feed,
+         reported: (.reported | length),
+         kept: (.kept | length),
+         high: ([.kept[] | select(.band == "high")] | length),
+         peak: (if (.kept | length) > 0 then ([.kept[].value] | max) else null end)}
+
+  briefing:
+    block: transform.jq
+    depends_on: [feed_summary]
+    # No for_each, so this is the join: one attempt over every feed's summary.
+    config:
+      input:
+        day: "${params.day}"
+        feeds: "${steps.feed_summary.output}"
+      program: |
+        {day: .day,
+         readings: ([.feeds[].value.kept] | add),
+         feeds: [.feeds[].value]}
+
+  check_briefing:
+    block: validate.schema
+    depends_on: [briefing]
+    config:
+      input: "${steps.briefing.output.value}"
+      schema: daily-briefing
+
+  page:
+    block: report.render
+    depends_on: [check_briefing]
+    config:
+      values:
+        # The gate's output, not the raw join: every value the page words is one the gate
+        # already passed.
+        briefing: "${steps.check_briefing.output.value}"
+        threshold: "${params.threshold}"
+      content_type: text/markdown
+      template: |
+        # Morning briefing for {{ briefing.day }}
+
+        {{ briefing.feeds | length }} feeds, and {{ briefing.readings }} readings that cleared {{ threshold }}.
+
+        | Feed | Reported | Kept | High | Peak |
+        | --- | --- | --- | --- | --- |
+        {% for feed in briefing.feeds %}
+        | {{ feed.feed }} | {{ feed.reported }} | {{ feed.kept }} | {{ feed.high }} | {{ feed.peak }} |
+        {% endfor %}
+
+  save:
+    block: storage.write
+    depends_on: [page]
+    config:
+      target: "${run.scratch}/briefing-${params.day}.md"
+      text: "${steps.page.output.text}"
+      content_type: "${steps.page.output.content_type}"
+
+  back:
+    block: storage.read
+    depends_on: [save]
+    config:
+      source: "${steps.save.output.uri}"
+      max_size: 1mb
+
+  announce:
+    block: log.write
+    depends_on: [back]
+    config:
+      message: the morning briefing, read back out of storage
+      value: "${steps.back.output.text}"
+
+report: {}
+
+triggers:
+  schedules:
+    - code: every-morning
+      name: Every morning, Oslo time
+      description: Fires once the night's loads have settled.
+      cron: "30 6 * * *"
+      timezone: Europe/Oslo