llm-workflow-router 0.3.0__py3-none-any.whl

llm_workflow_router-0.3.0.dist-info/METADATA

@@ -0,0 +1,409 @@
+Metadata-Version: 2.4
+Name: llm-workflow-router
+Version: 0.3.0
+Summary: Deterministic workflow topology enforcement for LLM-powered systems.
+Author: Doby Baxter
+License: MIT
+Keywords: llm,agents,workflow,topology,validation,determinism
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: coverage>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: opentelemetry-api>=1.20; extra == "dev"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "dev"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.18; extra == "openai-agents"
+Dynamic: license-file
+
+# LLM Workflow Router
+
+Deterministic workflow topology enforcement for LLM-powered systems.
+
+LLM Workflow Router is a stateless middleware engine designed to enforce explicit execution topology in AI systems that rely on large language models. It evaluates structured interaction metadata against strictly declared workflow rules and returns a terminal state.
+
+It controls structure — not content.
+
+---
+
+## Overview
+
+Modern LLM-driven systems frequently suffer from:
+
+- Recursive tool invocation loops  
+- Circular container transitions  
+- Cross-container contamination  
+- Implicit fallback behavior  
+- Unbounded workflow escalation  
+- Inconsistent refusal logic  
+
+Most mitigation strategies limit volume (timeouts, max tool calls, retries).  
+LLM Workflow Router enforces topology explicitly.
+
+The engine evaluates structured interaction metadata and returns one of three terminal states:
+
+- PROCEED  
+- REFUSE  
+- PAUSE  
+
+No content inspection.  
+No moderation.  
+No orchestration.  
+No mutation of input.  
+
+Only structural enforcement.
+
+---
+
+## Core Design Principles
+
+- Deterministic evaluation  
+- Stateless per evaluation  
+- Metadata-only inspection  
+- Explicit transitions only  
+- Static configuration (v1)  
+- Strict validation at load time  
+- No silent fallback  
+- Host application retains execution control  
+
+Same input → same output.
+
+---
+
+## Architecture
+
+Application  
+↓  
+WorkflowEngine.evaluate(metadata)  
+↓  
+[ PROCEED | REFUSE | PAUSE ]  
+↓  
+Application decides next action  
+
+The router does not:
+
+- Execute tools  
+- Retry calls  
+- Modify prompts  
+- Orchestrate sessions  
+
+It enforces topology and returns a decision.
+
+---
+
+## Configuration
+
+Workflow rules are defined using static YAML configuration.
+
+```yaml
+entrypoints:
+  - entry
+
+containers:
+  entry:
+    allow_transitions:
+      - support
+      - REFUSE
+    allow_reentry: false
+    max_invocations: 2
+
+  support:
+    allow_transitions:
+      - faq
+      - REFUSE
+    allow_reentry: false
+    max_invocations: 3
+
+  faq:
+    allow_transitions:
+      - REFUSE
+    allow_reentry: true
+    max_invocations: 5
+```
+
+Each container defines:
+
+- Explicit allowed transitions  
+- Whether re-entry is permitted  
+- Maximum invocation depth  
+
+Implicit transitions are not allowed.
+
+### Entrypoints
+
+The optional top-level `entrypoints` list declares the authoritative root
+containers. A workflow may have several roots — a support flow, a sales flow,
+and an FAQ flow can each start in their own container — so `entrypoints` is a
+list. When declared, any indegree-0 container that is *not* listed is treated
+as an orphan and rejected. If `entrypoints` is omitted, roots are inferred from
+graph shape (indegree 0) for backward compatibility, and an ambiguity warning
+is raised when more than one root is inferred. See
+`examples/multi_entry_config.yaml`.
+
+---
+
+## Topology Validation
+
+At configuration load time, the router performs strict validation:
+
+- Invalid transition targets  
+- Unknown containers  
+- Unknown declared entrypoints  
+- Dead-end containers  
+- Missing entry points  
+- Orphan containers (indegree 0, not a declared entrypoint)  
+- Unreachable containers  
+- Self-transition contradictions  
+- Cycle detection  
+- Re-entry safety enforcement  
+
+Configuration errors raise exceptions immediately.
+
+Fail loudly at load time.  
+Never fail silently at runtime.
+
+---
+
+## Runtime Evaluation
+
+The engine evaluates an immutable metadata structure:
+
+```python
+InteractionMetadata:
+    container: str
+    previous_state: InteractionState
+    transition_history: List[str]
+    invocation_depth: Dict[str, int]
+    requested_action: str
+    trace_id: Optional[str]
+```
+
+Returns:
+
+```python
+EvaluationResult:
+    state: InteractionState
+    container: str
+    reason: Optional[ReasonCode]
+    trace_id: Optional[str]
+```
+
+No exceptions during normal evaluation.  
+Only terminal states are returned.
+
+---
+
+## CLI Usage
+
+Install:
+
+```bash
+pip install llm-workflow-router
+```
+
+Validate configuration:
+
+```bash
+llm-router validate config.yaml
+```
+
+Analyze topology:
+
+```bash
+llm-router analyze config.yaml
+```
+
+Evaluate metadata:
+
+```bash
+llm-router run --config config.yaml --metadata metadata.json
+```
+
+---
+
+Render the topology as a diagram:
+
+```bash
+llm-router graph config.yaml                # Mermaid (paste into any Mermaid renderer)
+llm-router graph config.yaml --format dot   # Graphviz DOT
+```
+
+Like `analyze`, `graph` renders broken topologies too — unknown transition
+targets are drawn and flagged, which is exactly what you want while debugging
+a config.
+
+---
+
+## Session Layer (optional)
+
+The engine is stateless by design: every `evaluate()` receives a complete
+metadata snapshot. If you'd rather not do that bookkeeping yourself,
+`WorkflowSession` does it for you — and only advances on `PROCEED`:
+
+```python
+from router import WorkflowEngine, WorkflowSession
+
+engine = WorkflowEngine(cfg)
+session = WorkflowSession(engine, entry="entry", trace_id="req-42")
+
+result = session.request("support")   # entry -> support
+result = session.request("faq")       # support -> faq
+result = session.request("REFUSE")    # terminal; session closes
+
+session.history           # ("entry", "support")
+session.invocation_depth  # {"entry": 1, "support": 1, "faq": 1}
+```
+
+A `REFUSE` closes the session. A `PAUSE` suspends it until `resume()`.
+`session.snapshot(target)` exposes the exact metadata the next request would
+evaluate, so the session is fully auditable and you can drop down to raw
+`engine.evaluate()` at any time. The engine itself remains pure and stateless.
+
+---
+
+## OpenAI Agents SDK Integration
+
+Agents are containers. Handoffs are transitions. Attach a `TopologyGuard` to
+a run and every handoff is structurally evaluated **before** the next agent
+executes — a refused handoff raises `TopologyViolation` and aborts the run
+loudly instead of letting the agent graph wander:
+
+```bash
+pip install "llm-workflow-router[openai-agents]"
+```
+
+```python
+from agents import Agent, Runner
+from router import WorkflowEngine
+from router.integrations.openai_agents import TopologyGuard, TopologyViolation
+
+guard = TopologyGuard(engine, entry="triage", trace_id="run-001")
+
+try:
+    result = await Runner.run(triage_agent, "I was double-charged.", hooks=guard)
+except TopologyViolation as violation:
+    print("Refused:", violation.result.reason)
+
+# Full structural audit trail of the run:
+print(guard.session.history, guard.session.invocation_depth)
+```
+
+By default an agent's `name` is its container name; pass `container_for=` to
+map differently. The guard is content-blind — it never reads prompts,
+messages, or tool arguments. See
+[`examples/openai_agents_example.py`](examples/openai_agents_example.py) for a
+complete runnable triage → billing → refunds system.
+
+---
+
+## Why not just LangGraph (or my orchestrator's built-in graph)?
+
+Orchestrators *describe* structure. This engine *enforces* it — as a separate,
+framework-agnostic layer with properties orchestrators don't give you:
+
+- **Independent enforcement.** The topology lives outside your agent
+  framework, so a prompt-induced detour, a buggy handoff, or a framework
+  upgrade can't silently widen what's reachable. The declared graph is a
+  contract, and violations fail loudly with structured reason codes.
+- **Framework-agnostic.** The same YAML config governs an OpenAI Agents SDK
+  app today and whatever you migrate to next year. Adapters are thin; the
+  contract is portable.
+- **Auditable determinism.** Same metadata + same config → same decision,
+  every time. Combined with the `wfrouter.*` OpenTelemetry conventions, you
+  get compliance-grade answers to "why was this transition refused?" — a
+  reason code, not a vibe.
+- **Load-time topology analysis.** Cycles, orphans, dead ends, and
+  unreachable states are caught before anything runs — the kind of static
+  validation industrial control systems have had for decades and agent
+  frameworks mostly don't.
+
+If you're happy inside one orchestrator and don't need independent structural
+guarantees, its built-in graph may be enough. This tool exists for when
+"probably follows the graph" isn't good enough.
+
+---
+
+## Intended Audience
+
+- AI SaaS developers  
+- Internal LLM tooling teams  
+- Agent orchestration builders  
+- Platform engineering teams  
+- Infrastructure-focused AI developers  
+
+Not intended for content moderation or prompt filtering.
+
+---
+
+## Observability
+
+Optional OpenTelemetry instrumentation is provided under a dedicated,
+versioned namespace (`wfrouter.*`) that this project owns — it is deliberately
+independent of the upstream `gen_ai.*` conventions, which assume a model at the
+center of every span and do not fit a content-blind topology engine.
+
+Install the extra:
+
+```bash
+pip install "llm-workflow-router[otel]"
+```
+
+Wrap evaluation:
+
+```python
+from router.observability.otel import traced_evaluate
+result = traced_evaluate(engine, metadata)
+```
+
+If `opentelemetry-api` is not installed, instrumentation degrades to a no-op
+and the engine behaves identically. A `PROCEED`, `REFUSE`, or `PAUSE` outcome
+is a successful decision (span status OK); only genuine failures are errors.
+See `OBSERVABILITY.md` for the full attribute and span conventions.
+
+---
+
+# License
+
+MIT. Use it, ship it, build on it. See [LICENSE](LICENSE).
+
+If you deploy this in production, a note about your use case is always
+appreciated (and helps prioritize the roadmap) — but never required.
+
+---
+
+## Version
+
+Current version: 0.3.0
+
+- Static configuration model
+- Explicit multi-entrypoint declaration (with inferred fallback)
+- Optional stateful `WorkflowSession` convenience layer
+- OpenAI Agents SDK adapter (`TopologyGuard`)
+- Mermaid / DOT topology export (`llm-router graph`)
+- MIT licensed
+
+No inheritance. No dynamic rule composition. See [CHANGELOG.md](CHANGELOG.md).
+
+Future versions may extend topology modeling capabilities.
+
+---
+
+## Author
+
+Doby Baxter  
+Software systems developer focused on deterministic infrastructure and human-centered tooling.

llm_workflow_router-0.3.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+llm_workflow_router-0.3.0.dist-info/licenses/LICENSE,sha256=l2WB-wKhVb72IHjFy_GJTpm2IAxnOOQLVg13K86Tg6E,1068
+router/__init__.py,sha256=ezXbO4rcNhYwmhY0_-ekV2fZsS622HxovWAW6Ogqxyo,170
+router/_version.py,sha256=i0zotH1JX-8jrPYa-b2bJb3NBuV8UIOybVIvYOx8bjU,227
+router/cli.py,sha256=oMM656-kFDTguyfv217Dmfs_KpSuSJmqlvc54JF8tNU,7183
+router/engine.py,sha256=EfuwdR5dgwm5M1x5kAF6XNHuCUC0mFkQELqdKgqlfY0,2596
+router/graphing.py,sha256=LcCsjCXFs1_nSCwxXWazy69KwUEgICOzqvxf7cFh9u0,4353
+router/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+router/session.py,sha256=3i62WPzjiLv2xPkVtQ6AujM63ohcQyOMj1mkHm-gPrU,6238
+router/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+router/integrations/openai_agents.py,sha256=HLiFvRfAQeekdkYNtwhZ7HBolQddy7Kx8uZXalUFIkw,6617
+router/logging/schema.py,sha256=_weVBQHsPop1vkJsGfkiOgVF5qBcC10LtbHirZ8kuqI,2519
+router/models/config.py,sha256=ZJyvr4eMxE2HippBzhPOzc4F4bsXGxpDZN1ght6LvU8,799
+router/models/enums.py,sha256=zvf-HAwrfngmxjLP6p7pSac19crowdeysRGPw6FfuVU,398
+router/models/metadata.py,sha256=0X_6ip52uIUfKw-pwxGqrdfCxnA0P5iQXCPYpkgOzuY,388
+router/models/result.py,sha256=qgD-XzcJW-xf_s-x_TyYPLjR-sJhwTGov6rXO7WdXQ8,319
+router/observability/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+router/observability/otel.py,sha256=ieSS2gfhzM7r7IR1MlyUhH0q5vZBGlnDVK5ALwbraVI,9316
+router/validation/config_validator.py,sha256=9uV19hvQr_3K0zuXW3JDmGObsw6qj-qGaWJc4j2GhYE,1744
+router/validation/transition_validator.py,sha256=qXye6AkEPz9F0vYWrFLjKPYjwnQBAiv33Ni6sHk3HgI,10441
+llm_workflow_router-0.3.0.dist-info/METADATA,sha256=S8IgS2VqgYfBYgw7fay9lMO4_uYiLKRuJreYNmTW_fA,11317
+llm_workflow_router-0.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+llm_workflow_router-0.3.0.dist-info/entry_points.txt,sha256=cMfEK5p65b63p0r8CbqUIymSXD5ogpaRWb8pK69IXtE,47
+llm_workflow_router-0.3.0.dist-info/top_level.txt,sha256=e5Y_z2oozHN0yGfFuQJVJuk4MJhhfEisD1rcbh8986g,7
+llm_workflow_router-0.3.0.dist-info/RECORD,,

llm_workflow_router-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

llm_workflow_router-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+llm-router = router.cli:main

llm_workflow_router-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doby Baxter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_workflow_router-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+router

router/__init__.py

@@ -0,0 +1,5 @@
+from ._version import __version__
+from .engine import WorkflowEngine
+from .session import WorkflowSession
+
+__all__ = ["WorkflowEngine", "WorkflowSession", "__version__"]

router/_version.py

@@ -0,0 +1,7 @@
+"""Single source of truth for the engine version.
+
+Referenced by packaging metadata, the structured logging schema, and the
+OpenTelemetry instrumentation, so the version can never drift between them.
+"""
+
+__version__ = "0.3.0"