langgraph-harness 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AaronG18
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,230 @@
1
+ Metadata-Version: 2.4
2
+ Name: langgraph-harness
3
+ Version: 0.1.1
4
+ Summary: Per-node HARNESS parsing, injection and enforcement for LangGraph nodes.
5
+ Author: AaronG18
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/AaronG18/langgraph-harness
8
+ Project-URL: Repository, https://github.com/AaronG18/langgraph-harness
9
+ Project-URL: Issues, https://github.com/AaronG18/langgraph-harness/issues
10
+ Keywords: langgraph,llm,agents,guardrails,prompt,harness
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Libraries
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: langgraph>=1.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=8; extra == "dev"
25
+ Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
26
+ Dynamic: license-file
27
+
28
+ # langgraph-harness
29
+
30
+ **Per-node HARNESS parsing, injection and enforcement for LangGraph nodes.**
31
+
32
+ A [LangGraph](https://github.com/langchain-ai/langgraph) graph is a set of plain
33
+ callables. `StateGraph.add_node` accepts metadata, retry/cache policies, an input
34
+ schema, error handlers and timeouts — but it has **no notion of a per-node
35
+ instruction document**. `create_react_agent` has a single **graph-level** `prompt`
36
+ (plus `pre_model_hook` / `post_model_hook` for global interception). So today the
37
+ answer to *"can each node's agent parse its own HARNESS?"* is: **not natively.**
38
+
39
+ `langgraph-harness` adds that missing layer:
40
+
41
+ ```python
42
+ from langgraph_harness import Harness, harnessed, current_harness, harness_messages
43
+
44
+ PLANNER = Harness.from_text("""
45
+ - MUST: return a JSON object [require="steps"]
46
+ - MUST NOT: mention internal tool names [forbid=tool_]
47
+ - SHOULD: keep the plan under 200 words
48
+ """, name="planner")
49
+
50
+ @harnessed(PLANNER, validate=True)
51
+ def planner(state, config=None):
52
+ messages = [*harness_messages(), *state["messages"]]
53
+ response = llm.invoke(messages)
54
+ return {"messages": [response]}
55
+ ```
56
+
57
+ `current_harness()` inside the node returns *that node's* harness — not a global
58
+ prompt, and not another node's document.
59
+
60
+ ## Why a node decorator (and not only an edge or a state field)?
61
+
62
+ | Form | What it can do | Why it is not enough alone |
63
+ | --- | --- | --- |
64
+ | **Node decorator** | Binds the document to one node, exposes it inside the node, validates the output | — (this is the primary form) |
65
+ | **State field** | Carries the node→harness registry and violations across steps | Every node still has to read it manually |
66
+ | **Edge** | Routes to a repair/fallback node when rules fail | An edge runs *after* the node; it cannot inject instructions into the node's LLM call |
67
+
68
+ The package therefore ships all three, with the decorator as the entry point:
69
+ `@harnessed(...)` binds and injects, `HarnessState` records, and
70
+ `harness_gate(...)` routes.
71
+
72
+ ## Install
73
+
74
+ ```bash
75
+ pip install langgraph-harness
76
+ ```
77
+
78
+ Requires Python 3.10+ and `langgraph>=1.0`.
79
+
80
+ ## The HARNESS format
81
+
82
+ A harness is a small Markdown document. Only bullet lines that start with `MUST`,
83
+ `MUST NOT` or `SHOULD` are parsed as rules:
84
+
85
+ ```markdown
86
+ # Planner harness
87
+
88
+ - MUST: return a JSON object [require="steps"]
89
+ - MUST NOT: mention internal tool names [forbid=tool_]
90
+ - SHOULD: keep the plan short
91
+ ```
92
+
93
+ * `MUST` / `MUST NOT` are **enforced**; `SHOULD` failures are **warnings**.
94
+ * `[require=REGEX]` — the output must match the regex.
95
+ * `[forbid=REGEX]` — the output must not match the regex.
96
+ * Rules without an annotation are still injected into the prompt; they simply
97
+ cannot be verified automatically.
98
+
99
+ ## Three forms
100
+
101
+ ### 1. Node decorator (primary)
102
+
103
+ ```python
104
+ from langgraph_harness import harnessed, current_harness
105
+
106
+ @harnessed("harnesses/planner.md", validate=True)
107
+ def planner(state):
108
+ harness = current_harness() # this node's document
109
+ ...
110
+ ```
111
+
112
+ Options:
113
+
114
+ | Option | Default | Meaning |
115
+ | --- | --- | --- |
116
+ | `validate` | `False` | Check the node's returned text against `require` / `forbid` |
117
+ | `on_violation` | `"raise"` | `"raise"` → `HarnessViolation`; `"record"` → append to `harness_violations` |
118
+ | `inject_messages` | `False` | Prepend a `SystemMessage` with the harness to a copy of `state["messages"]` |
119
+ | `name` | function name | Node name used in errors |
120
+
121
+ ### 2. State
122
+
123
+ ```python
124
+ from typing import Annotated
125
+ from langgraph.graph.message import add_messages
126
+ from langgraph_harness import HarnessState
127
+
128
+ class State(HarnessState):
129
+ messages: Annotated[list, add_messages]
130
+ ```
131
+
132
+ `HarnessState` adds two optional channels: `harness` (node → raw text) and
133
+ `harness_violations` (recorded failures). Helpers: `harness_of`, `violations_of`,
134
+ `with_harness`.
135
+
136
+ ### 3. Edge gate
137
+
138
+ ```python
139
+ from langgraph.graph import END, START, StateGraph
140
+ from langgraph_harness import harness_gate
141
+
142
+ builder.add_conditional_edges(
143
+ "planner",
144
+ harness_gate(on_violation="repair", otherwise=END),
145
+ )
146
+ ```
147
+
148
+ When `state["harness_violations"]` is non-empty the router returns `"repair"`.
149
+
150
+ ## API at a glance
151
+
152
+ ```python
153
+ Harness.from_text(text, name=...) # parse Markdown
154
+ Harness.from_file(path, name=...) # parse a file
155
+ parse_harness(text, name=...) # same, functional form
156
+ load_harness(str | Path | Harness) # resolve any of the three
157
+
158
+ harnessed(harness, *, validate, on_violation, inject_messages, name)
159
+ current_harness() # inside a harnessed node
160
+ harness_messages() / harness_prompt() # render to a SystemMessage / str
161
+
162
+ HarnessState # TypedDict mix-in
163
+ violations_of(state) / harness_of(state, node) / with_harness(state, node, text)
164
+
165
+ harness_gate(on_violation="repair", otherwise=END)
166
+
167
+ validate_output(text, harness) -> Report(violations, warnings)
168
+ ```
169
+
170
+ ## How it works
171
+
172
+ `@harnessed` binds the parsed harness to a `contextvars.ContextVar` for the
173
+ duration of the call and resets it in a `finally` block. Context variables are
174
+ task-local, so concurrent nodes (sync or async) do not see each other's harness.
175
+ The decorated wrapper also exposes `__harness__`, `__harness_name__` and
176
+ `__harness_node__` for introspection.
177
+
178
+ ## Verification
179
+
180
+ ```bash
181
+ pytest -q
182
+ # 26 passed
183
+ ```
184
+
185
+ The integration tests build a real `StateGraph` with two nodes that each call
186
+ `current_harness()` and assert they see *only their own* document, and a graph
187
+ where a violating node is routed to a repair node by `harness_gate`.
188
+
189
+ ## Real-model demo
190
+
191
+ `examples/real_llm_demo.py` runs two nodes with conflicting harnesses and
192
+ asserts that each node answers with its own word:
193
+
194
+ ```bash
195
+ python examples/real_llm_demo.py --mock # deterministic, no key
196
+ OPENAI_API_KEY=... python examples/real_llm_demo.py --provider openai
197
+ DEEPSEEK_API_KEY=... python examples/real_llm_demo.py --provider deepseek
198
+ GEMINI_API_KEY=... python examples/real_llm_demo.py --provider gemini
199
+ python examples/real_llm_demo.py --provider ollama # local Ollama
200
+ ```
201
+
202
+ ## Publishing
203
+
204
+ * `.github/workflows/ci.yml` runs the test suite on Python 3.10–3.13.
205
+ * `.github/workflows/publish.yml` builds the sdist/wheel, runs `twine check`,
206
+ and uploads to PyPI on a GitHub release. It works with a `PYPI_API_TOKEN`
207
+ repository secret or with PyPI trusted publishing (no secret).
208
+
209
+ Locally:
210
+
211
+ ```bash
212
+ python -m build
213
+ twine check dist/*
214
+ TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... twine upload dist/*
215
+ ```
216
+
217
+ ## Limitations
218
+
219
+ * Regex checks are shallow: they prove a string contains (or avoids) a pattern,
220
+ not that the model *semantically* followed the rule. Use the harness as a
221
+ guardrail, not as a proof.
222
+ * `inject_messages=True` prepends a `SystemMessage` to the node's copy of
223
+ `state["messages"]`; the node owns the LLM call and should not echo that
224
+ message back into state.
225
+ * The package does not call an LLM. It parses, injects, validates and routes;
226
+ the model invocation stays in your node.
227
+
228
+ ## License
229
+
230
+ MIT
@@ -0,0 +1,203 @@
1
+ # langgraph-harness
2
+
3
+ **Per-node HARNESS parsing, injection and enforcement for LangGraph nodes.**
4
+
5
+ A [LangGraph](https://github.com/langchain-ai/langgraph) graph is a set of plain
6
+ callables. `StateGraph.add_node` accepts metadata, retry/cache policies, an input
7
+ schema, error handlers and timeouts — but it has **no notion of a per-node
8
+ instruction document**. `create_react_agent` has a single **graph-level** `prompt`
9
+ (plus `pre_model_hook` / `post_model_hook` for global interception). So today the
10
+ answer to *"can each node's agent parse its own HARNESS?"* is: **not natively.**
11
+
12
+ `langgraph-harness` adds that missing layer:
13
+
14
+ ```python
15
+ from langgraph_harness import Harness, harnessed, current_harness, harness_messages
16
+
17
+ PLANNER = Harness.from_text("""
18
+ - MUST: return a JSON object [require="steps"]
19
+ - MUST NOT: mention internal tool names [forbid=tool_]
20
+ - SHOULD: keep the plan under 200 words
21
+ """, name="planner")
22
+
23
+ @harnessed(PLANNER, validate=True)
24
+ def planner(state, config=None):
25
+ messages = [*harness_messages(), *state["messages"]]
26
+ response = llm.invoke(messages)
27
+ return {"messages": [response]}
28
+ ```
29
+
30
+ `current_harness()` inside the node returns *that node's* harness — not a global
31
+ prompt, and not another node's document.
32
+
33
+ ## Why a node decorator (and not only an edge or a state field)?
34
+
35
+ | Form | What it can do | Why it is not enough alone |
36
+ | --- | --- | --- |
37
+ | **Node decorator** | Binds the document to one node, exposes it inside the node, validates the output | — (this is the primary form) |
38
+ | **State field** | Carries the node→harness registry and violations across steps | Every node still has to read it manually |
39
+ | **Edge** | Routes to a repair/fallback node when rules fail | An edge runs *after* the node; it cannot inject instructions into the node's LLM call |
40
+
41
+ The package therefore ships all three, with the decorator as the entry point:
42
+ `@harnessed(...)` binds and injects, `HarnessState` records, and
43
+ `harness_gate(...)` routes.
44
+
45
+ ## Install
46
+
47
+ ```bash
48
+ pip install langgraph-harness
49
+ ```
50
+
51
+ Requires Python 3.10+ and `langgraph>=1.0`.
52
+
53
+ ## The HARNESS format
54
+
55
+ A harness is a small Markdown document. Only bullet lines that start with `MUST`,
56
+ `MUST NOT` or `SHOULD` are parsed as rules:
57
+
58
+ ```markdown
59
+ # Planner harness
60
+
61
+ - MUST: return a JSON object [require="steps"]
62
+ - MUST NOT: mention internal tool names [forbid=tool_]
63
+ - SHOULD: keep the plan short
64
+ ```
65
+
66
+ * `MUST` / `MUST NOT` are **enforced**; `SHOULD` failures are **warnings**.
67
+ * `[require=REGEX]` — the output must match the regex.
68
+ * `[forbid=REGEX]` — the output must not match the regex.
69
+ * Rules without an annotation are still injected into the prompt; they simply
70
+ cannot be verified automatically.
71
+
72
+ ## Three forms
73
+
74
+ ### 1. Node decorator (primary)
75
+
76
+ ```python
77
+ from langgraph_harness import harnessed, current_harness
78
+
79
+ @harnessed("harnesses/planner.md", validate=True)
80
+ def planner(state):
81
+ harness = current_harness() # this node's document
82
+ ...
83
+ ```
84
+
85
+ Options:
86
+
87
+ | Option | Default | Meaning |
88
+ | --- | --- | --- |
89
+ | `validate` | `False` | Check the node's returned text against `require` / `forbid` |
90
+ | `on_violation` | `"raise"` | `"raise"` → `HarnessViolation`; `"record"` → append to `harness_violations` |
91
+ | `inject_messages` | `False` | Prepend a `SystemMessage` with the harness to a copy of `state["messages"]` |
92
+ | `name` | function name | Node name used in errors |
93
+
94
+ ### 2. State
95
+
96
+ ```python
97
+ from typing import Annotated
98
+ from langgraph.graph.message import add_messages
99
+ from langgraph_harness import HarnessState
100
+
101
+ class State(HarnessState):
102
+ messages: Annotated[list, add_messages]
103
+ ```
104
+
105
+ `HarnessState` adds two optional channels: `harness` (node → raw text) and
106
+ `harness_violations` (recorded failures). Helpers: `harness_of`, `violations_of`,
107
+ `with_harness`.
108
+
109
+ ### 3. Edge gate
110
+
111
+ ```python
112
+ from langgraph.graph import END, START, StateGraph
113
+ from langgraph_harness import harness_gate
114
+
115
+ builder.add_conditional_edges(
116
+ "planner",
117
+ harness_gate(on_violation="repair", otherwise=END),
118
+ )
119
+ ```
120
+
121
+ When `state["harness_violations"]` is non-empty the router returns `"repair"`.
122
+
123
+ ## API at a glance
124
+
125
+ ```python
126
+ Harness.from_text(text, name=...) # parse Markdown
127
+ Harness.from_file(path, name=...) # parse a file
128
+ parse_harness(text, name=...) # same, functional form
129
+ load_harness(str | Path | Harness) # resolve any of the three
130
+
131
+ harnessed(harness, *, validate, on_violation, inject_messages, name)
132
+ current_harness() # inside a harnessed node
133
+ harness_messages() / harness_prompt() # render to a SystemMessage / str
134
+
135
+ HarnessState # TypedDict mix-in
136
+ violations_of(state) / harness_of(state, node) / with_harness(state, node, text)
137
+
138
+ harness_gate(on_violation="repair", otherwise=END)
139
+
140
+ validate_output(text, harness) -> Report(violations, warnings)
141
+ ```
142
+
143
+ ## How it works
144
+
145
+ `@harnessed` binds the parsed harness to a `contextvars.ContextVar` for the
146
+ duration of the call and resets it in a `finally` block. Context variables are
147
+ task-local, so concurrent nodes (sync or async) do not see each other's harness.
148
+ The decorated wrapper also exposes `__harness__`, `__harness_name__` and
149
+ `__harness_node__` for introspection.
150
+
151
+ ## Verification
152
+
153
+ ```bash
154
+ pytest -q
155
+ # 26 passed
156
+ ```
157
+
158
+ The integration tests build a real `StateGraph` with two nodes that each call
159
+ `current_harness()` and assert they see *only their own* document, and a graph
160
+ where a violating node is routed to a repair node by `harness_gate`.
161
+
162
+ ## Real-model demo
163
+
164
+ `examples/real_llm_demo.py` runs two nodes with conflicting harnesses and
165
+ asserts that each node answers with its own word:
166
+
167
+ ```bash
168
+ python examples/real_llm_demo.py --mock # deterministic, no key
169
+ OPENAI_API_KEY=... python examples/real_llm_demo.py --provider openai
170
+ DEEPSEEK_API_KEY=... python examples/real_llm_demo.py --provider deepseek
171
+ GEMINI_API_KEY=... python examples/real_llm_demo.py --provider gemini
172
+ python examples/real_llm_demo.py --provider ollama # local Ollama
173
+ ```
174
+
175
+ ## Publishing
176
+
177
+ * `.github/workflows/ci.yml` runs the test suite on Python 3.10–3.13.
178
+ * `.github/workflows/publish.yml` builds the sdist/wheel, runs `twine check`,
179
+ and uploads to PyPI on a GitHub release. It works with a `PYPI_API_TOKEN`
180
+ repository secret or with PyPI trusted publishing (no secret).
181
+
182
+ Locally:
183
+
184
+ ```bash
185
+ python -m build
186
+ twine check dist/*
187
+ TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... twine upload dist/*
188
+ ```
189
+
190
+ ## Limitations
191
+
192
+ * Regex checks are shallow: they prove a string contains (or avoids) a pattern,
193
+ not that the model *semantically* followed the rule. Use the harness as a
194
+ guardrail, not as a proof.
195
+ * `inject_messages=True` prepends a `SystemMessage` to the node's copy of
196
+ `state["messages"]`; the node owns the LLM call and should not echo that
197
+ message back into state.
198
+ * The package does not call an LLM. It parses, injects, validates and routes;
199
+ the model invocation stays in your node.
200
+
201
+ ## License
202
+
203
+ MIT
@@ -0,0 +1,68 @@
1
+ """langgraph-harness — per-node HARNESS parsing, injection and enforcement for LangGraph.
2
+
3
+ LangGraph nodes are plain callables: ``StateGraph.add_node`` accepts metadata,
4
+ retry/cache policies and an input schema, but it has no notion of a per-node
5
+ instruction document. ``create_react_agent`` has a single graph-level prompt.
6
+
7
+ This package adds the missing piece: bind a small Markdown HARNESS document to a
8
+ node, expose it inside the node body, optionally validate the node's output, and
9
+ optionally gate an edge on violations.
10
+
11
+ Quick start::
12
+
13
+ from langgraph_harness import Harness, harnessed, current_harness, harness_messages
14
+
15
+ PLANNER = Harness.from_text('''
16
+ - MUST: return a JSON object [require="steps"]
17
+ - MUST NOT: mention internal tool names [forbid=tool_]
18
+ ''', name="planner")
19
+
20
+ @harnessed(PLANNER, validate=True)
21
+ def planner(state, config=None):
22
+ messages = [*harness_messages(), *state["messages"]]
23
+ response = llm.invoke(messages)
24
+ return {"messages": [response]}
25
+ """
26
+
27
+ from .context import current_harness, reset_current_harness, set_current_harness
28
+ from .decorators import harnessed
29
+ from .edges import harness_gate
30
+ from .errors import HarnessError, HarnessNotBound, HarnessParseError, HarnessViolation
31
+ from .harness import Harness, Rule, load_harness, parse_harness
32
+ from .prompts import harness_messages, harness_prompt
33
+ from .state import HarnessState, harness_of, violations_of, with_harness
34
+ from .validation import Report, Violation, validate_output
35
+
36
+ __version__ = "0.1.1"
37
+
38
+ __all__ = [
39
+ # parsing
40
+ "Harness",
41
+ "Rule",
42
+ "load_harness",
43
+ "parse_harness",
44
+ # node decorator (primary form)
45
+ "harnessed",
46
+ "current_harness",
47
+ "set_current_harness",
48
+ "reset_current_harness",
49
+ "harness_messages",
50
+ "harness_prompt",
51
+ # state form
52
+ "HarnessState",
53
+ "harness_of",
54
+ "violations_of",
55
+ "with_harness",
56
+ # edge form
57
+ "harness_gate",
58
+ # validation
59
+ "validate_output",
60
+ "Report",
61
+ "Violation",
62
+ # errors
63
+ "HarnessError",
64
+ "HarnessParseError",
65
+ "HarnessNotBound",
66
+ "HarnessViolation",
67
+ "__version__",
68
+ ]
@@ -0,0 +1,41 @@
1
+ """Per-node harness binding through a :class:`contextvars.ContextVar`.
2
+
3
+ ``@harnessed`` sets the current harness for the duration of the node call, so
4
+ the node body can call :func:`current_harness` without threading the document
5
+ through its arguments. Context variables are task-local, so concurrent node
6
+ executions do not see each other's harness.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from contextvars import ContextVar, Token
12
+
13
+ from .errors import HarnessNotBound
14
+ from .harness import Harness
15
+
16
+ _CURRENT: ContextVar[Harness | None] = ContextVar("langgraph_harness_current", default=None)
17
+
18
+
19
+ def current_harness() -> Harness:
20
+ """Return the harness bound to the currently executing node.
21
+
22
+ Raises:
23
+ HarnessNotBound: if called outside a ``@harnessed`` node.
24
+ """
25
+ harness = _CURRENT.get()
26
+ if harness is None:
27
+ raise HarnessNotBound(
28
+ "current_harness() was called outside a @harnessed node. "
29
+ "Decorate the node with @harnessed(...) first."
30
+ )
31
+ return harness
32
+
33
+
34
+ def set_current_harness(harness: Harness) -> Token[Harness | None]:
35
+ """Bind ``harness`` to the current context and return a reset token."""
36
+ return _CURRENT.set(harness)
37
+
38
+
39
+ def reset_current_harness(token: Token[Harness | None]) -> None:
40
+ """Restore the previous harness binding."""
41
+ _CURRENT.reset(token)