Build explicit supervisor and specialist interfaces

Pattern 04 companion: Python example · Behavioral tests · Example license

Run the standalone routing example

Download pattern_04.py and test_pattern_04.py into the same directory. Run python3 -B pattern_04.py on macOS or py -3 -B pattern_04.py on Windows. The deterministic output is status=review route=latency evidence=fixture:L1. Run the corresponding interpreter with -B -m unittest -v test_pattern_04.py for the behavior checks.

The tests were executed on Windows Python 3.13; macOS commands are guidance. The router is a lambda returning latency and the specialist is another lambda returning a fixture locator. These are explicit adapter seams, not language models. There are no external calls or credentials. The module demonstrates how to constrain dispatch around future adapters, without implying that the lambdas perform real incident classification or analysis.

Architecture and request sequence

Component diagram for Build explicit supervisor and specialist interfaces — Original reference architecture by Sandeep Belgavi. Arrows show the responsibilities and transitions described below.

Request sequence for Build explicit supervisor and specialist interfaces — Illustrative sequence for this design; failure and recovery variants are explained in the article.

Trace authorization before dispatch

Ticket is a frozen dataclass holding incident, service and symptom. dispatch rejects an invalid ticket or empty incident, then checks service membership in allowed_services. A denied service returns before the router runs. This ordering gives a future service wrapper a clear place to supply authenticated scope. The fixture trusts its caller to supply that scope; it does not authenticate users itself.

The router receives only the symptom. Ordinary router exceptions become route_error. A non-string output or a route outside latency and availability becomes escalate. If the route is valid but no corresponding callable exists in specialists, the result is unavailable. These statuses keep model output errors, unsupported requests and deployment configuration problems distinguishable. A production logging layer should retain sanitized diagnostic categories without leaking full incident text or provider exception payloads.

Inspect the actual specialist boundary

The supervisor constructs an envelope with incident and service only, then invokes the selected specialist. The test captures the envelope and asserts those exact keys. This is a meaningful handoff-minimization check: symptom text and arbitrary caller data do not automatically pass through. It is not a complete security boundary because all functions still run inside one Python process. A production service must enforce permissions in the specialist's tools and transport identity.

A specialist exception returns worker_error. A result that is not a string beginning with fixture: returns invalid_result. A matching string returns review with route and evidence. The prefix test does not resolve a reference or prove that its contents support any claim. Extend it with an authenticated resolver and a structured result schema before relying on evidence. The current result means only that the demonstration's accepted shape was returned.

Store routing decisions as versioned events

A proposed storage design records ticket identity, scope digest, routing taxonomy revision, router revision, selected specialist revision and outcome. Put the route decision and specialist invocation under a shared correlation identifier. A retry should preserve its original decision unless an explicit reclassification event changes it. Otherwise an operator may see one ticket move between specialties with no explanation of which evidence or policy caused the change.

Store specialist evidence locators and access metadata rather than embedding unlimited transcripts in the supervisor record. If a ticket crosses a data boundary, the receiving worker must have access to the specific referenced objects. A locator alone does not transfer permission. Record an unavailable-object result distinctly from a missing specialist. The downloadable example has no persistent event store, retry coordinator or cross-process identity; these are implementation requirements for the proposed service extension.

Package workers without sharing all authority

For a container reference, begin with one unprivileged Python image running the fixture and tests. A production split could place supervisor and specialists in separate services with distinct identities, but service separation is useful only if their permissions differ. Give the supervisor invocation rights to approved specialists, not their underlying administrative credentials. Give each specialist only the observation capabilities its task requires. Authenticate the envelope and validate service scope again on receipt.

Pin image and adapter versions so a route result can be reproduced against the same taxonomy and worker behavior. Add per-specialist concurrency limits, request deadlines and a maximum payload size. A specialist that stalls should not hold every supervisor connection indefinitely. This is a deployment reference design, not a tested cloud configuration. The Windows tests establish in-process routing behavior; they do not demonstrate network authorization, container isolation, evidence resolution or service-level availability.

Implementation references and acceptance gaps

The linked source and eight tests cover valid routing, unknown route, denied service, unavailable worker, malformed result, worker exception, minimized envelope and invalid router output type. Review the assertions before extending the module. A real model router needs its own labeled evaluation. A real specialist needs evidence and access tests, not merely the same successful fixture string.