acgs-haystack 0.1.1__tar.gz → 0.2.0__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.
Files changed (21) hide show
  1. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/CHANGELOG.md +15 -1
  2. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/PKG-INFO +34 -3
  3. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/README.md +32 -1
  4. acgs_haystack-0.2.0/examples/deny_and_audit.py +73 -0
  5. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/pyproject.toml +2 -2
  6. acgs_haystack-0.2.0/tests/test_compatibility.py +28 -0
  7. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/tests/test_examples.py +33 -0
  8. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/.gitignore +0 -0
  9. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/LICENSE +0 -0
  10. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/examples/quickstart.py +0 -0
  11. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/src/haystack_integrations/hooks/acgs/__init__.py +0 -0
  12. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/src/haystack_integrations/hooks/acgs/_governance.py +0 -0
  13. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/src/haystack_integrations/hooks/acgs/py.typed +0 -0
  14. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/src/haystack_integrations/hooks/acgs/strategy.py +0 -0
  15. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/tests/__init__.py +0 -0
  16. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/tests/conftest.py +0 -0
  17. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/tests/fakes.py +0 -0
  18. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/tests/test_agent.py +0 -0
  19. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/tests/test_default_constitution.py +0 -0
  20. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/tests/test_governance.py +0 -0
  21. {acgs_haystack-0.1.1 → acgs_haystack-0.2.0}/tests/test_strategy.py +0 -0
@@ -6,7 +6,21 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
- ## [0.1.1] - Unreleased
9
+ ## 0.2.0 (2026-11-20)
10
+
11
+ ### Added
12
+
13
+ - Offline `examples/deny_and_audit.py`: one allowed and one denied Haystack tool call, with an application
14
+ decision trail.
15
+ - Compatibility coverage for nested JSON-native arguments and bytes/bytearray formatting with acgs-lite 4.0.0.
16
+
17
+ ### Changed
18
+
19
+ - Document the compatibility matrix: the default/test Hatch environments resolve acgs-lite 4.0.0, and the CI
20
+ `test-min` job tests the 3.0.1 floor. Runtime support remains `acgs-lite>=3.0.1,<5`.
21
+ - Clarify that the adapter validates formatted text and does not issue signed receipts.
22
+
23
+ ## [0.1.1] - 2026-10-20
10
24
 
11
25
  ### Fixed
12
26
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: acgs-haystack
3
- Version: 0.1.1
3
+ Version: 0.2.0
4
4
  Summary: ACGS rule-based tool-call governance for the Haystack Agent before_tool hook
5
5
  Project-URL: Documentation, https://github.com/acgs-ai/acgs-haystack#readme
6
6
  Project-URL: Issues, https://github.com/acgs-ai/acgs-haystack/issues
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
19
19
  Classifier: Programming Language :: Python :: Implementation :: CPython
20
20
  Classifier: Typing :: Typed
21
21
  Requires-Python: >=3.11
22
- Requires-Dist: acgs-lite<4,>=3.0.1
22
+ Requires-Dist: acgs-lite<5,>=3.0.1
23
23
  Requires-Dist: haystack-ai>=3.0.0
24
24
  Description-Content-Type: text/markdown
25
25
 
@@ -52,7 +52,38 @@ its tools, or the chat generator.
52
52
  pip install acgs-haystack
53
53
  ```
54
54
 
55
- Requires Python 3.11+, `haystack-ai>=3.0.0` and `acgs-lite>=3.0.1`.
55
+ Requires Python 3.11+, `haystack-ai>=3.0.0` and `acgs-lite>=3.0.1,<5`.
56
+
57
+ ### Compatibility
58
+
59
+ | Component | Supported range | 0.2.0 validation |
60
+ |---|---|---|
61
+ | acgs-lite | `>=3.0.1,<5` | 4.0.0 tested in the default/test Hatch environments (latest allowed); 3.0.1 floor tested by the CI `test-min` job |
62
+ | Haystack | `>=3.0.0` | 3.5.0 in the default/test environments; 3.0.0 in `test-min` |
63
+ | Python | `>=3.11` | CI tests Python 3.11, 3.12 and 3.13 |
64
+
65
+ This project uses Hatch environments and has no lockfile. The adapter formats arguments as text and calls
66
+ `GovernanceEngine.validate`. It does not select the production authorization profile or issue signed receipts.
67
+ Bytes and bytearray arguments remain scalar text for rule matching.
68
+
69
+ acgs-lite 4 is a major release. Its production profile of `GovernedCallable` requires an Ed25519
70
+ receipt signer, governed payloads are JSON-only, and `GovernedAgent` no longer passes per-call keyword arguments to
71
+ rule conditions (see the [acgs-lite changelog](https://github.com/acgs-ai/acgs-lite/blob/main/CHANGELOG.md)). This
72
+ adapter works with both majors, but a fresh environment installs the newest version allowed. To stay on 3.x, also
73
+ require `"acgs-lite<4"`, for example `pip install acgs-haystack "acgs-lite<4"`.
74
+
75
+ ### Offline deny-and-audit example
76
+
77
+ Run [examples/deny_and_audit.py](examples/deny_and_audit.py) without an API key:
78
+
79
+ ```console
80
+ hatch run python examples/deny_and_audit.py
81
+ ```
82
+
83
+ A scripted chat generator requests one allowed note and one denied note through the Haystack Agent's
84
+ `ConfirmationHook`. Only the allowed tool executes, then the example prints both decisions with tool name,
85
+ verdict, reason and rule IDs. This application trail omits argument values and stays in memory; it is not a signed
86
+ receipt or a durable engine audit log. Haystack telemetry is disabled before importing the framework.
56
87
 
57
88
  ## Usage
58
89
 
@@ -27,7 +27,38 @@ its tools, or the chat generator.
27
27
  pip install acgs-haystack
28
28
  ```
29
29
 
30
- Requires Python 3.11+, `haystack-ai>=3.0.0` and `acgs-lite>=3.0.1`.
30
+ Requires Python 3.11+, `haystack-ai>=3.0.0` and `acgs-lite>=3.0.1,<5`.
31
+
32
+ ### Compatibility
33
+
34
+ | Component | Supported range | 0.2.0 validation |
35
+ |---|---|---|
36
+ | acgs-lite | `>=3.0.1,<5` | 4.0.0 tested in the default/test Hatch environments (latest allowed); 3.0.1 floor tested by the CI `test-min` job |
37
+ | Haystack | `>=3.0.0` | 3.5.0 in the default/test environments; 3.0.0 in `test-min` |
38
+ | Python | `>=3.11` | CI tests Python 3.11, 3.12 and 3.13 |
39
+
40
+ This project uses Hatch environments and has no lockfile. The adapter formats arguments as text and calls
41
+ `GovernanceEngine.validate`. It does not select the production authorization profile or issue signed receipts.
42
+ Bytes and bytearray arguments remain scalar text for rule matching.
43
+
44
+ acgs-lite 4 is a major release. Its production profile of `GovernedCallable` requires an Ed25519
45
+ receipt signer, governed payloads are JSON-only, and `GovernedAgent` no longer passes per-call keyword arguments to
46
+ rule conditions (see the [acgs-lite changelog](https://github.com/acgs-ai/acgs-lite/blob/main/CHANGELOG.md)). This
47
+ adapter works with both majors, but a fresh environment installs the newest version allowed. To stay on 3.x, also
48
+ require `"acgs-lite<4"`, for example `pip install acgs-haystack "acgs-lite<4"`.
49
+
50
+ ### Offline deny-and-audit example
51
+
52
+ Run [examples/deny_and_audit.py](examples/deny_and_audit.py) without an API key:
53
+
54
+ ```console
55
+ hatch run python examples/deny_and_audit.py
56
+ ```
57
+
58
+ A scripted chat generator requests one allowed note and one denied note through the Haystack Agent's
59
+ `ConfirmationHook`. Only the allowed tool executes, then the example prints both decisions with tool name,
60
+ verdict, reason and rule IDs. This application trail omits argument values and stays in memory; it is not a signed
61
+ receipt or a durable engine audit log. Haystack telemetry is disabled before importing the framework.
31
62
 
32
63
  ## Usage
33
64
 
@@ -0,0 +1,73 @@
1
+ """Run one allowed and one denied Haystack tool call offline, then print a decision trail."""
2
+
3
+ import json
4
+ import os
5
+ from dataclasses import asdict
6
+ from typing import Annotated, Any
7
+
8
+ # Disable telemetry before importing Haystack; the scripted generator uses no model service.
9
+ os.environ["HAYSTACK_TELEMETRY_ENABLED"] = "False"
10
+
11
+ from haystack import component
12
+ from haystack.components.agents import Agent
13
+ from haystack.dataclasses import ChatMessage, ToolCall
14
+ from haystack.hooks.human_in_the_loop import ConfirmationHook
15
+ from haystack.tools import tool
16
+
17
+ from haystack_integrations.hooks.acgs import ACGSConfirmationStrategy, GovernanceDecision
18
+
19
+
20
+ class AuditedStrategy(ACGSConfirmationStrategy):
21
+ """Collect decisions through the public API without retaining argument values."""
22
+
23
+ def __init__(self) -> None:
24
+ super().__init__()
25
+ self.decisions: list[GovernanceDecision] = []
26
+
27
+ def evaluate(self, tool_name: str, tool_params: dict[str, Any]) -> GovernanceDecision:
28
+ decision = super().evaluate(tool_name, tool_params)
29
+ self.decisions.append(decision)
30
+ return decision
31
+
32
+
33
+ @component
34
+ class ScriptedChatGenerator:
35
+ """Request two prewritten tool calls, then finish without a network request."""
36
+
37
+ def __init__(self) -> None:
38
+ self.step = 0
39
+
40
+ @component.output_types(replies=list[ChatMessage])
41
+ def run(self, messages: list[ChatMessage], tools: Any = None, **kwargs: Any) -> dict[str, Any]:
42
+ self.step += 1
43
+ if self.step > 1:
44
+ return {"replies": [ChatMessage.from_assistant("Done.")]}
45
+ calls = [
46
+ ToolCall(id=f"note-{index}", tool_name="record_note", arguments={"body": body})
47
+ for index, body in enumerate(["The meeting starts at noon.", "The admin password is demo-secret."])
48
+ ]
49
+ return {"replies": [ChatMessage.from_assistant(tool_calls=calls)]}
50
+
51
+
52
+ @tool
53
+ def record_note(body: Annotated[str, "Message body"]) -> str:
54
+ """Record a demo note by printing it locally."""
55
+ print(f"Executed record_note: {body}")
56
+ return "Note recorded."
57
+
58
+
59
+ def main() -> None:
60
+ strategy = AuditedStrategy()
61
+ agent = Agent(
62
+ chat_generator=ScriptedChatGenerator(),
63
+ tools=[record_note],
64
+ hooks={"before_tool": [ConfirmationHook(confirmation_strategies={"*": strategy})]},
65
+ )
66
+ agent.run(messages=[ChatMessage.from_user("Record the two notes.")])
67
+ print("Audit trail (application decisions):")
68
+ for decision in strategy.decisions:
69
+ print(json.dumps(asdict(decision), sort_keys=True))
70
+
71
+
72
+ if __name__ == "__main__":
73
+ main()
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "acgs-haystack"
7
- version = "0.1.1"
7
+ version = "0.2.0"
8
8
  description = "ACGS rule-based tool-call governance for the Haystack Agent before_tool hook"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -22,7 +22,7 @@ classifiers = [
22
22
  "Programming Language :: Python :: Implementation :: CPython",
23
23
  "Typing :: Typed",
24
24
  ]
25
- dependencies = ["haystack-ai>=3.0.0", "acgs-lite>=3.0.1,<4"]
25
+ dependencies = ["haystack-ai>=3.0.0", "acgs-lite>=3.0.1,<5"]
26
26
 
27
27
  [project.urls]
28
28
  Documentation = "https://github.com/acgs-ai/acgs-haystack#readme"
@@ -0,0 +1,28 @@
1
+ """Regression checks for the adapter boundary with acgs-lite 4.x and the 3.0.1 floor."""
2
+
3
+ from typing import Any
4
+
5
+ import pytest
6
+
7
+ from haystack_integrations.hooks.acgs import ACGSConfirmationStrategy, Verdict, format_tool_call
8
+
9
+
10
+ @pytest.mark.parametrize("binary_type", [bytes, bytearray])
11
+ def test_binary_arguments_remain_scalar_and_match_rules(binary_type: Any) -> None:
12
+ arguments = {"items": [{"body": binary_type(b"password")}]}
13
+ rendered = format_tool_call("record_note", arguments)
14
+ assert "items[0].body: " in rendered
15
+ assert "password" in rendered
16
+ assert "body[0]" not in rendered
17
+ decision = ACGSConfirmationStrategy().evaluate("record_note", arguments)
18
+ assert decision.verdict is Verdict.DENY
19
+ assert decision.error is None
20
+ assert "ACGS-006" in decision.rule_ids
21
+
22
+
23
+ @pytest.mark.parametrize("body", ["Meeting at noon", "password"])
24
+ def test_nested_json_arguments_with_default_unsigned_configuration(body: str) -> None:
25
+ arguments: dict[str, Any] = {"items": [{"body": body, "values": [None, True, False, 7, 1.5, {}, []]}]}
26
+ decision = ACGSConfirmationStrategy().evaluate("record_note", arguments)
27
+ assert decision.verdict is (Verdict.DENY if body == "password" else Verdict.ALLOW)
28
+ assert decision.error is None
@@ -5,9 +5,13 @@
5
5
 
6
6
  from __future__ import annotations
7
7
 
8
+ import json
9
+ import os
8
10
  import runpy
11
+ import socket
9
12
  import textwrap
10
13
  from pathlib import Path
14
+ from typing import Any
11
15
 
12
16
  import pytest
13
17
 
@@ -29,6 +33,35 @@ def test_quickstart_example_runs(capsys: pytest.CaptureFixture[str]) -> None:
29
33
  assert "ACGS-006" in out
30
34
 
31
35
 
36
+ def test_deny_and_audit_runs_offline_without_api_keys(
37
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
38
+ ) -> None:
39
+ for key in list(os.environ):
40
+ if key.endswith("API_KEY"):
41
+ monkeypatch.delenv(key)
42
+ # Register the example's environment change so monkeypatch restores the original value.
43
+ monkeypatch.setenv("HAYSTACK_TELEMETRY_ENABLED", "False")
44
+
45
+ def no_network(*args: Any, **kwargs: Any) -> None:
46
+ pytest.fail("The offline example attempted a network connection")
47
+
48
+ monkeypatch.setattr(socket.socket, "connect", no_network)
49
+ monkeypatch.setattr(socket.socket, "connect_ex", no_network)
50
+ monkeypatch.setattr(socket, "create_connection", no_network)
51
+ runpy.run_path(str(ROOT / "examples" / "deny_and_audit.py"), run_name="__main__")
52
+ output = capsys.readouterr().out
53
+ execution, audit = output.split("Audit trail (application decisions):\n")
54
+ assert execution == "Executed record_note: The meeting starts at noon.\n"
55
+ decisions = [json.loads(line) for line in audit.splitlines()]
56
+ assert [decision["verdict"] for decision in decisions] == ["allow", "deny"]
57
+ assert [decision["tool_name"] for decision in decisions] == ["record_note", "record_note"]
58
+ assert decisions[0]["rule_ids"] == []
59
+ assert decisions[1]["rule_ids"] == ["ACGS-006"]
60
+ assert "Blocked by" in decisions[1]["reason"]
61
+ assert all(decision["error"] is None for decision in decisions)
62
+ assert "demo-secret" not in output
63
+
64
+
32
65
  def _python_blocks(markdown: str) -> list[str]:
33
66
  blocks, current, inside = [], [], False
34
67
  for line in markdown.splitlines():
File without changes
File without changes