langgraph-harness 0.1.1__py3-none-any.whl

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,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)
@@ -0,0 +1,150 @@
1
+ """The ``@harnessed`` node decorator — the primary form of this package."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import functools
6
+ import inspect
7
+ from typing import Any, Callable, TypeVar
8
+
9
+ from .context import reset_current_harness, set_current_harness
10
+ from .errors import HarnessViolation
11
+ from .harness import HarnessLike, load_harness
12
+ from .prompts import harness_messages
13
+ from .validation import validate_output
14
+
15
+ F = TypeVar("F", bound=Callable[..., Any])
16
+
17
+ _ON_VIOLATION = ("raise", "record")
18
+
19
+
20
+ def harnessed(
21
+ harness: HarnessLike,
22
+ *,
23
+ validate: bool = False,
24
+ on_violation: str = "raise",
25
+ inject_messages: bool = False,
26
+ name: str | None = None,
27
+ ) -> Callable[[F], F]:
28
+ """Bind a HARNESS to a LangGraph node.
29
+
30
+ Args:
31
+ harness: A :class:`~langgraph_harness.Harness`, a Markdown string, or a
32
+ path to a Markdown file.
33
+ validate: When ``True``, the node's returned text is checked against the
34
+ harness rules.
35
+ on_violation: ``"raise"`` (default) raises
36
+ :class:`~langgraph_harness.HarnessViolation`; ``"record"`` appends the
37
+ violations to ``harness_violations`` in the returned state dict.
38
+ inject_messages: When ``True`` and the node's first argument is a state
39
+ dict containing ``messages``, a ``SystemMessage`` with the rendered
40
+ harness is prepended to a copy of those messages.
41
+ name: Node name used in error messages (defaults to the function name).
42
+
43
+ Returns:
44
+ The decorated node. The original function is available as
45
+ ``wrapper.__wrapped__``.
46
+ """
47
+ parsed = load_harness(harness, name=name)
48
+ if on_violation not in _ON_VIOLATION:
49
+ raise ValueError(f"on_violation must be one of {_ON_VIOLATION}, got {on_violation!r}")
50
+
51
+ def decorator(fn: F) -> F:
52
+ node_name = name or getattr(fn, "__name__", "node")
53
+
54
+ if inspect.iscoroutinefunction(fn):
55
+
56
+ @functools.wraps(fn)
57
+ async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
58
+ token = set_current_harness(parsed)
59
+ try:
60
+ call_args = _maybe_inject(args, inject_messages)
61
+ result = await fn(*call_args, **kwargs)
62
+ finally:
63
+ reset_current_harness(token)
64
+ return _maybe_validate(result, parsed, node_name, validate, on_violation)
65
+
66
+ wrapper: Any = async_wrapper
67
+ else:
68
+
69
+ @functools.wraps(fn)
70
+ def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
71
+ token = set_current_harness(parsed)
72
+ try:
73
+ call_args = _maybe_inject(args, inject_messages)
74
+ result = fn(*call_args, **kwargs)
75
+ finally:
76
+ reset_current_harness(token)
77
+ return _maybe_validate(result, parsed, node_name, validate, on_violation)
78
+
79
+ wrapper = sync_wrapper
80
+
81
+ wrapper.__harness__ = parsed
82
+ wrapper.__harness_name__ = parsed.name
83
+ wrapper.__harness_node__ = node_name
84
+ return wrapper
85
+
86
+ return decorator
87
+
88
+
89
+ def _maybe_inject(args: tuple[Any, ...], enabled: bool) -> tuple[Any, ...]:
90
+ if not enabled or not args:
91
+ return args
92
+ state = args[0]
93
+ if isinstance(state, dict) and isinstance(state.get("messages"), list):
94
+ injected = dict(state)
95
+ injected["messages"] = [*harness_messages(), *state["messages"]]
96
+ return (injected, *args[1:])
97
+ return args
98
+
99
+
100
+ def _extract_text(result: Any) -> str | None:
101
+ if isinstance(result, str):
102
+ return result
103
+ if isinstance(result, dict):
104
+ messages = result.get("messages")
105
+ if messages:
106
+ last = messages[-1]
107
+ # Plain strings are accepted so the decorator also works with simple
108
+ # dict states that do not use LangChain message objects.
109
+ if isinstance(last, str):
110
+ return last
111
+ content = last.get("content") if isinstance(last, dict) else getattr(last, "content", None)
112
+ if isinstance(content, str):
113
+ return content
114
+ if isinstance(content, list):
115
+ return " ".join(str(part) for part in content)
116
+ content = getattr(result, "content", None)
117
+ if isinstance(content, str):
118
+ return content
119
+ return None
120
+
121
+
122
+ def _maybe_validate(
123
+ result: Any,
124
+ parsed: Any,
125
+ node_name: str,
126
+ validate: bool,
127
+ on_violation: str,
128
+ ) -> Any:
129
+ del node_name # kept for a clearer signature / future messages
130
+ if not validate:
131
+ return result
132
+
133
+ text = _extract_text(result)
134
+ if text is None:
135
+ return result
136
+
137
+ report = validate_output(text, parsed)
138
+ if report.ok:
139
+ return result
140
+
141
+ if on_violation == "raise":
142
+ raise HarnessViolation(parsed.name, report)
143
+
144
+ if isinstance(result, dict):
145
+ output = dict(result)
146
+ existing = list(output.get("harness_violations") or [])
147
+ output["harness_violations"] = [*existing, *report.as_dicts()]
148
+ return output
149
+
150
+ raise HarnessViolation(parsed.name, report)
@@ -0,0 +1,31 @@
1
+ """Optional EDGE form: route to a repair node when a node violated its harness."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Callable
6
+
7
+ from langgraph.graph import END
8
+
9
+ from .state import violations_of
10
+
11
+
12
+ def harness_gate(
13
+ *,
14
+ on_violation: str,
15
+ otherwise: Any = END,
16
+ ) -> Callable[[Any], Any]:
17
+ """Build a conditional-edge router.
18
+
19
+ Use it with ``add_conditional_edges(node, harness_gate(on_violation="repair"))``.
20
+ The router returns ``on_violation`` when ``state["harness_violations"]`` is
21
+ non-empty, else ``otherwise`` (``END`` by default).
22
+
23
+ Args:
24
+ on_violation: Name of the repair / fallback node to route to.
25
+ otherwise: Destination when there are no violations (default: ``END``).
26
+ """
27
+
28
+ def route(state: Any) -> Any:
29
+ return on_violation if violations_of(state) else otherwise
30
+
31
+ return route
@@ -0,0 +1,30 @@
1
+ """Exceptions raised by :mod:`langgraph_harness`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING
6
+
7
+ if TYPE_CHECKING: # pragma: no cover
8
+ from .validation import Report
9
+
10
+
11
+ class HarnessError(Exception):
12
+ """Base class for every error raised by this package."""
13
+
14
+
15
+ class HarnessParseError(HarnessError):
16
+ """Raised when a harness document cannot be parsed."""
17
+
18
+
19
+ class HarnessNotBound(HarnessError):
20
+ """Raised when current_harness() is called outside a harnessed node."""
21
+
22
+
23
+ class HarnessViolation(HarnessError):
24
+ """Raised when a node's output violates a MUST / MUST NOT rule."""
25
+
26
+ def __init__(self, harness_name: str, report: "Report") -> None:
27
+ self.harness_name = harness_name
28
+ self.report = report
29
+ details = "; ".join(f"{v.rule_id} [{v.level}] {v.message}" for v in report.violations)
30
+ super().__init__(f"node violated harness {harness_name!r}: {details}")
@@ -0,0 +1,153 @@
1
+ """Parse a Markdown HARNESS document into typed rules.
2
+
3
+ A harness is a small rules document, for example::
4
+
5
+ # Planner harness
6
+
7
+ ## Rules
8
+ - MUST: respond with a JSON object [require=\\{\\s*"steps"]
9
+ - MUST NOT: mention internal tool names [forbid=tool_]
10
+ - SHOULD: keep the plan under 200 words
11
+
12
+ Rules are ``MUST``, ``MUST NOT`` or ``SHOULD``. The optional ``[require=...]``
13
+ and ``[forbid=...]`` annotations are regular expressions used by
14
+ :func:`langgraph_harness.validate_output` to check a node's output.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import re
20
+ from dataclasses import dataclass
21
+ from pathlib import Path
22
+
23
+ from .errors import HarnessParseError
24
+
25
+ _RULE_RE = re.compile(r"^\s*[-*]\s*(MUST NOT|MUST|SHOULD)\s*[::]\s*(.+?)\s*$", re.IGNORECASE)
26
+ _ANNOTATION_RE = re.compile(r"\[(require|forbid)\s*=\s*(.+?)\]", re.IGNORECASE | re.DOTALL)
27
+
28
+ _LEVELS = ("MUST", "MUST NOT", "SHOULD")
29
+
30
+
31
+ @dataclass(frozen=True, slots=True)
32
+ class Rule:
33
+ """A single instruction line from a harness document."""
34
+
35
+ id: str
36
+ level: str
37
+ text: str
38
+ require: str | None = None
39
+ forbid: str | None = None
40
+
41
+ @property
42
+ def is_hard(self) -> bool:
43
+ """``MUST`` and ``MUST NOT`` are enforced; ``SHOULD`` is advisory."""
44
+ return self.level in ("MUST", "MUST NOT")
45
+
46
+
47
+ @dataclass(frozen=True, slots=True)
48
+ class Harness:
49
+ """A parsed harness document."""
50
+
51
+ name: str
52
+ raw: str
53
+ rules: tuple[Rule, ...]
54
+
55
+ @classmethod
56
+ def from_text(cls, text: str, *, name: str = "harness") -> "Harness":
57
+ """Parse ``text`` into a :class:`Harness`."""
58
+ return parse_harness(text, name=name)
59
+
60
+ @classmethod
61
+ def from_file(cls, path: str | Path, *, name: str | None = None) -> "Harness":
62
+ """Read and parse a harness file."""
63
+ p = Path(path)
64
+ try:
65
+ text = p.read_text(encoding="utf-8")
66
+ except OSError as exc: # pragma: no cover - defensive
67
+ raise HarnessParseError(f"cannot read harness file {p!s}: {exc}") from exc
68
+ return parse_harness(text, name=name or p.stem)
69
+
70
+ def rules_for(self, level: str) -> tuple[Rule, ...]:
71
+ """Return every rule with the given level."""
72
+ level = level.upper()
73
+ if level not in _LEVELS:
74
+ raise ValueError(f"unknown rule level {level!r}; expected one of {_LEVELS}")
75
+ return tuple(rule for rule in self.rules if rule.level == level)
76
+
77
+ def prompt(self) -> str:
78
+ """Render the harness as a compact system-prompt block."""
79
+ lines = [f"HARNESS: {self.name}", "Follow these rules for this node:"]
80
+ if not self.rules:
81
+ lines.append("- (no machine-readable rules found)")
82
+ for rule in self.rules:
83
+ lines.append(f"- [{rule.level}] {rule.text}")
84
+ return "\n".join(lines)
85
+
86
+ def __len__(self) -> int:
87
+ return len(self.rules)
88
+
89
+
90
+ def parse_harness(text: str, *, name: str = "harness") -> Harness:
91
+ """Parse Markdown ``text`` into a :class:`Harness`.
92
+
93
+ Raises:
94
+ HarnessParseError: if ``text`` is not a string.
95
+ """
96
+ if not isinstance(text, str):
97
+ raise HarnessParseError(f"harness source must be str, got {type(text).__name__}")
98
+
99
+ rules: list[Rule] = []
100
+ for line in text.splitlines():
101
+ match = _RULE_RE.match(line)
102
+ if match is None:
103
+ continue
104
+
105
+ level = " ".join(match.group(1).upper().split())
106
+ body = match.group(2).strip()
107
+
108
+ require: str | None = None
109
+ forbid: str | None = None
110
+ for annotation in _ANNOTATION_RE.finditer(body):
111
+ kind = annotation.group(1).lower()
112
+ value = annotation.group(2).strip()
113
+ if kind == "require":
114
+ require = value
115
+ else:
116
+ forbid = value
117
+
118
+ rules.append(
119
+ Rule(
120
+ id=f"R{len(rules) + 1}",
121
+ level=level,
122
+ text=_ANNOTATION_RE.sub("", body).strip(),
123
+ require=require,
124
+ forbid=forbid,
125
+ )
126
+ )
127
+
128
+ return Harness(name=name, raw=text, rules=tuple(rules))
129
+
130
+
131
+ HarnessLike = "str | Path | Harness"
132
+
133
+
134
+ def load_harness(source: str | Path | Harness, *, name: str | None = None) -> Harness:
135
+ """Resolve ``source`` (a path, a raw document or a :class:`Harness`)."""
136
+ if isinstance(source, Harness):
137
+ return source
138
+ if isinstance(source, Path):
139
+ return Harness.from_file(source, name=name)
140
+
141
+ if not isinstance(source, str):
142
+ raise HarnessParseError(f"harness source must be str, Path or Harness, got {type(source).__name__}")
143
+
144
+ # A short, single-line string that names an existing file is treated as a path.
145
+ if "\n" not in source and len(source) < 260:
146
+ try:
147
+ path = Path(source)
148
+ if path.is_file():
149
+ return Harness.from_file(path, name=name)
150
+ except (OSError, ValueError):
151
+ pass
152
+
153
+ return parse_harness(source, name=name or "harness")
@@ -0,0 +1,30 @@
1
+ """Helpers that turn a harness into prompt messages."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from .context import current_harness
8
+ from .harness import Harness
9
+
10
+
11
+ def harness_prompt(harness: Harness | None = None) -> str:
12
+ """Return the rendered prompt block for ``harness`` (default: current)."""
13
+ return (harness or current_harness()).prompt()
14
+
15
+
16
+ def harness_messages(harness: Harness | None = None) -> list[Any]:
17
+ """Return ``[SystemMessage(content=<harness prompt>)]``.
18
+
19
+ ``langchain-core`` is imported lazily so the rest of the package works
20
+ without LangChain installed.
21
+ """
22
+ try:
23
+ from langchain_core.messages import SystemMessage
24
+ except Exception as exc: # pragma: no cover - depends on the environment
25
+ raise RuntimeError(
26
+ "harness_messages() requires langchain-core, which ships with langgraph. "
27
+ "Install it with `pip install langgraph`."
28
+ ) from exc
29
+
30
+ return [SystemMessage(content=harness_prompt(harness))]
@@ -0,0 +1,62 @@
1
+ """State helpers: the per-node harness registry and recorded violations.
2
+
3
+ Inherit :class:`HarnessState` to add the two optional channels to a graph
4
+ state schema::
5
+
6
+ from typing import Annotated
7
+ from langgraph.graph.message import add_messages
8
+ from langgraph_harness import HarnessState
9
+
10
+ class State(HarnessState):
11
+ messages: Annotated[list, add_messages]
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from typing import Any
17
+
18
+ try: # Python 3.12+
19
+ from typing import TypedDict
20
+ except ImportError: # pragma: no cover
21
+ from typing_extensions import TypedDict
22
+
23
+
24
+ class HarnessState(TypedDict, total=False):
25
+ """Mix-in channels used by :mod:`langgraph_harness`.
26
+
27
+ Attributes:
28
+ harness: Mapping of node name to the raw harness text that was bound.
29
+ harness_violations: Violations recorded by nodes decorated with
30
+ ``@harnessed(..., validate=True, on_violation="record")``.
31
+ """
32
+
33
+ harness: dict[str, str]
34
+ harness_violations: list[dict[str, Any]]
35
+
36
+
37
+ def violations_of(state: Any) -> list[dict[str, Any]]:
38
+ """Return the recorded violations from ``state`` (dict or object)."""
39
+ if isinstance(state, dict):
40
+ return list(state.get("harness_violations") or [])
41
+ return list(getattr(state, "harness_violations", None) or [])
42
+
43
+
44
+ def harness_of(state: Any, node: str) -> str | None:
45
+ """Return the raw harness text bound to ``node`` in ``state``."""
46
+ if isinstance(state, dict):
47
+ return (state.get("harness") or {}).get(node)
48
+ harness = getattr(state, "harness", None) or {}
49
+ return harness.get(node)
50
+
51
+
52
+ def with_harness(state: Any, node: str, harness_text: str) -> dict[str, Any]:
53
+ """Return a copy of ``state`` with ``node`` mapped to ``harness_text``."""
54
+ if isinstance(state, dict):
55
+ current = dict(state.get("harness") or {})
56
+ current[node] = harness_text
57
+ output = dict(state)
58
+ output["harness"] = current
59
+ return output
60
+ current = dict(getattr(state, "harness", None) or {})
61
+ current[node] = harness_text
62
+ return {"harness": current}
@@ -0,0 +1,76 @@
1
+ """Check a node's output against the harness rules.
2
+
3
+ Only the ``require`` / ``forbid`` annotations are machine-checkable; a rule
4
+ without an annotation is still injected into the prompt but cannot be verified
5
+ automatically. ``MUST`` and ``MUST NOT`` failures are violations; ``SHOULD``
6
+ failures are warnings.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+ from dataclasses import dataclass
13
+
14
+ from .harness import Harness, Rule
15
+
16
+
17
+ @dataclass(frozen=True, slots=True)
18
+ class Violation:
19
+ """A single failed rule."""
20
+
21
+ rule_id: str
22
+ level: str
23
+ message: str
24
+ rule_text: str
25
+
26
+ def as_dict(self) -> dict[str, str]:
27
+ return {
28
+ "rule_id": self.rule_id,
29
+ "level": self.level,
30
+ "message": self.message,
31
+ "rule_text": self.rule_text,
32
+ }
33
+
34
+
35
+ @dataclass(frozen=True, slots=True)
36
+ class Report:
37
+ """Result of validating one node output."""
38
+
39
+ violations: tuple[Violation, ...] = ()
40
+ warnings: tuple[Violation, ...] = ()
41
+
42
+ @property
43
+ def ok(self) -> bool:
44
+ """``True`` when no hard rule failed."""
45
+ return not self.violations
46
+
47
+ def as_dicts(self) -> list[dict[str, str]]:
48
+ return [v.as_dict() for v in self.violations]
49
+
50
+
51
+ def _check_rule(rule: Rule, text: str) -> Violation | None:
52
+ if rule.require is not None and re.search(rule.require, text, re.IGNORECASE | re.DOTALL) is None:
53
+ return Violation(rule.id, rule.level, f"required pattern not found: {rule.require}", rule.text)
54
+ if rule.forbid is not None and re.search(rule.forbid, text, re.IGNORECASE | re.DOTALL) is not None:
55
+ return Violation(rule.id, rule.level, f"forbidden pattern found: {rule.forbid}", rule.text)
56
+ return None
57
+
58
+
59
+ def validate_output(text: str, harness: Harness) -> Report:
60
+ """Validate ``text`` against ``harness`` and return a :class:`Report`."""
61
+ if not isinstance(text, str):
62
+ raise TypeError(f"validate_output() expects str, got {type(text).__name__}")
63
+
64
+ violations: list[Violation] = []
65
+ warnings: list[Violation] = []
66
+
67
+ for rule in harness.rules:
68
+ failure = _check_rule(rule, text)
69
+ if failure is None:
70
+ continue
71
+ if rule.is_hard:
72
+ violations.append(failure)
73
+ else:
74
+ warnings.append(failure)
75
+
76
+ return Report(tuple(violations), tuple(warnings))
@@ -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,14 @@
1
+ langgraph_harness/__init__.py,sha256=AfhswBwkvdcNq4F8Ht5YdQrP0N-kl6fa7BBtFG4SMuQ,2205
2
+ langgraph_harness/context.py,sha256=TTJ5HTRsH94EvQErl8f3gK6qMihajT1t7etQ1yZcefY,1384
3
+ langgraph_harness/decorators.py,sha256=rWosakSiJdMCTwxFKb50hYMsjgK4zvNpCE3KgapfsV0,5260
4
+ langgraph_harness/edges.py,sha256=ok18XJPk9uefr-5uAPH7Gr8eMG2_KcjqEQMuG52dczM,906
5
+ langgraph_harness/errors.py,sha256=pfiJ5B2S3cIpb7V0evq9ZBNOn8kk0iqRMckgEEld5qQ,961
6
+ langgraph_harness/harness.py,sha256=IIJDDytzn00t2iMIEUEe-hiHL_3oC9E-HlAe2Lz_Yqg,5108
7
+ langgraph_harness/prompts.py,sha256=3XP4GSFTeJGR5HrLA4W5YrxQgseddiGQyJYOJndxLuw,1046
8
+ langgraph_harness/state.py,sha256=CopLZU40Z_TH790IIFwX9w931Lfa3_gFFDNIiARvd1M,2134
9
+ langgraph_harness/validation.py,sha256=ZN27NQ0xeiRxdTmS7snxfGAA_nMzauQ0y9L2Kcnyc4M,2404
10
+ langgraph_harness-0.1.1.dist-info/licenses/LICENSE,sha256=KF9v6dnPzxqsdDgTLGoFcUf8TV19qU2fsq0Lj4cdY48,1086
11
+ langgraph_harness-0.1.1.dist-info/METADATA,sha256=gSxSwnfWVB-Y45YD1prOSllJLacMF75won8sCak7jkU,8302
12
+ langgraph_harness-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
13
+ langgraph_harness-0.1.1.dist-info/top_level.txt,sha256=sQ3oqOUtz7CYNU5vSNXcNiTfaRt0hV2lHE8MuHc8ECA,18
14
+ langgraph_harness-0.1.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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 @@
1
+ langgraph_harness