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.
- langgraph_harness-0.1.1/LICENSE +21 -0
- langgraph_harness-0.1.1/PKG-INFO +230 -0
- langgraph_harness-0.1.1/README.md +203 -0
- langgraph_harness-0.1.1/langgraph_harness/__init__.py +68 -0
- langgraph_harness-0.1.1/langgraph_harness/context.py +41 -0
- langgraph_harness-0.1.1/langgraph_harness/decorators.py +150 -0
- langgraph_harness-0.1.1/langgraph_harness/edges.py +31 -0
- langgraph_harness-0.1.1/langgraph_harness/errors.py +30 -0
- langgraph_harness-0.1.1/langgraph_harness/harness.py +153 -0
- langgraph_harness-0.1.1/langgraph_harness/prompts.py +30 -0
- langgraph_harness-0.1.1/langgraph_harness/state.py +62 -0
- langgraph_harness-0.1.1/langgraph_harness/validation.py +76 -0
- langgraph_harness-0.1.1/langgraph_harness.egg-info/PKG-INFO +230 -0
- langgraph_harness-0.1.1/langgraph_harness.egg-info/SOURCES.txt +23 -0
- langgraph_harness-0.1.1/langgraph_harness.egg-info/dependency_links.txt +1 -0
- langgraph_harness-0.1.1/langgraph_harness.egg-info/requires.txt +5 -0
- langgraph_harness-0.1.1/langgraph_harness.egg-info/top_level.txt +1 -0
- langgraph_harness-0.1.1/pyproject.toml +40 -0
- langgraph_harness-0.1.1/setup.cfg +4 -0
- langgraph_harness-0.1.1/tests/test_decorator.py +87 -0
- langgraph_harness-0.1.1/tests/test_harness.py +73 -0
- langgraph_harness-0.1.1/tests/test_integration.py +72 -0
- langgraph_harness-0.1.1/tests/test_llm_end_to_end.py +65 -0
- langgraph_harness-0.1.1/tests/test_state_edges.py +28 -0
- langgraph_harness-0.1.1/tests/test_validation.py +42 -0
|
@@ -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)
|