handoffpack 0.1.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 (24) hide show
  1. handoffpack-0.1.0/PKG-INFO +145 -0
  2. handoffpack-0.1.0/README.md +119 -0
  3. handoffpack-0.1.0/pyproject.toml +63 -0
  4. handoffpack-0.1.0/setup.cfg +4 -0
  5. handoffpack-0.1.0/src/handoffpack/__init__.py +3 -0
  6. handoffpack-0.1.0/src/handoffpack/adapter_instructions.py +492 -0
  7. handoffpack-0.1.0/src/handoffpack/codec.py +249 -0
  8. handoffpack-0.1.0/src/handoffpack/guards.py +148 -0
  9. handoffpack-0.1.0/src/handoffpack/legend.json +21 -0
  10. handoffpack-0.1.0/src/handoffpack/license.py +194 -0
  11. handoffpack-0.1.0/src/handoffpack/server.py +692 -0
  12. handoffpack-0.1.0/src/handoffpack.egg-info/PKG-INFO +145 -0
  13. handoffpack-0.1.0/src/handoffpack.egg-info/SOURCES.txt +22 -0
  14. handoffpack-0.1.0/src/handoffpack.egg-info/dependency_links.txt +1 -0
  15. handoffpack-0.1.0/src/handoffpack.egg-info/entry_points.txt +3 -0
  16. handoffpack-0.1.0/src/handoffpack.egg-info/requires.txt +5 -0
  17. handoffpack-0.1.0/src/handoffpack.egg-info/top_level.txt +1 -0
  18. handoffpack-0.1.0/tests/test_adapter_instructions.py +230 -0
  19. handoffpack-0.1.0/tests/test_codec.py +130 -0
  20. handoffpack-0.1.0/tests/test_guards.py +88 -0
  21. handoffpack-0.1.0/tests/test_license.py +262 -0
  22. handoffpack-0.1.0/tests/test_sampling_optin.py +41 -0
  23. handoffpack-0.1.0/tests/test_security_side_effects.py +80 -0
  24. handoffpack-0.1.0/tests/test_server_units.py +94 -0
handoffpack-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,145 @@
1
+ Metadata-Version: 2.4
2
+ Name: handoffpack
3
+ Version: 0.1.0
4
+ Summary: Deterministic structured handoff-card codec + MCP translator server for agent handoffs, session compaction, and instruction compilation (client-side sampling for semantics; zero server-side LLM cost).
5
+ Author: Myeong Jun Jo
6
+ License: LicenseRef-Proprietary
7
+ Project-URL: Homepage, https://github.com/myeongjunjo/handoffpack
8
+ Project-URL: Repository, https://github.com/myeongjunjo/handoffpack
9
+ Keywords: mcp,model-context-protocol,llm,agent,handoff,context-compaction,prompt-compression,claude
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: Other/Proprietary License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
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
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown
22
+ Requires-Dist: mcp>=1.0
23
+ Requires-Dist: cryptography>=42
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest>=8.0; extra == "dev"
26
+
27
+ # handoffpack — MCP structured-card translator
28
+
29
+ Deterministic codec + guards + MCP server for HP1 structured handoff cards.
30
+ Turns agent handoffs, session logs, and recurring-instruction files into
31
+ compact structured cards. All deterministic work runs locally; the server
32
+ never calls an LLM API and holds no API keys.
33
+
34
+ ## Install
35
+
36
+ Python 3.11+ required.
37
+
38
+ ```bash
39
+ # From PyPI (once published):
40
+ pip install handoffpack
41
+
42
+ # Pre-publish / local: from the package directory
43
+ pip install .
44
+ # or editable, with test deps:
45
+ pip install -e .[dev]
46
+ ```
47
+
48
+ Core codec/guards tests run with stdlib + pytest only; the `mcp` package
49
+ is needed only to run `server.py`.
50
+
51
+ ## Register the MCP server (Claude Code)
52
+
53
+ ```bash
54
+ python -m handoffpack.server # stdio transport, run directly
55
+ claude mcp add handoffpack -- python -m handoffpack.server
56
+ ```
57
+
58
+ Other clients (Cursor, etc.): use the same command in their MCP server
59
+ registration UI. A `handoffpack` console script is also installed as an
60
+ alias for `python -m handoffpack.server`.
61
+
62
+ ## License key (paid add-ons only)
63
+
64
+ The 4 MCP tools (`encode` / `decode` / `compact_to_l2l` / `verify`) are
65
+ FREE and unlimited. Only paid add-ons (e.g. the full `hp-instructions`
66
+ conversion run) require a key. The verifier is fully offline (embedded
67
+ Ed25519 public key, no phone-home). Key discovery precedence:
68
+
69
+ ```bash
70
+ export HP_LICENSE=HP1.xxxxx... # macOS/Linux
71
+ set HP_LICENSE=HP1.xxxxx... # Windows
72
+ # or place the key on the first line of ~/.handoffpack/license
73
+ # or pass --license <KEY> to hp-instructions
74
+ ```
75
+
76
+ `hp-instructions --check` (drift scan) is free; a full conversion run
77
+ requires a `plus`-tier key.
78
+
79
+ ## Layout
80
+
81
+ ```
82
+ mcp-translator/
83
+ ├── pyproject.toml
84
+ ├── src/handoffpack/
85
+ │ ├── legend.json # public card schema (typed slots + kv pairs)
86
+ │ ├── codec.py # assemble/parse/validate + chars/4 token estimator
87
+ │ ├── guards.py # breakeven passthrough, BAN-field rule, nuance heuristic
88
+ │ ├── license.py # offline Ed25519 license verifier (paid add-ons)
89
+ │ ├── adapter_instructions.py # hp-instructions CLI (CLAUDE.md -> HP1 cards)
90
+ │ └── server.py # MCP server: encode / decode / compact_to_l2l / verify
91
+ └── tests/
92
+ ```
93
+
94
+ ## Run tests
95
+
96
+ ```bash
97
+ pytest # 114 tests
98
+ ```
99
+
100
+ ## Build & publish (maintainer)
101
+
102
+ ```bash
103
+ python -m build # produces dist/*.whl + dist/*.tar.gz
104
+ python -m twine upload dist/*
105
+ ```
106
+
107
+ If `build` is unavailable offline, an equivalent wheel can be produced
108
+ with `python -m pip wheel . -w dist --no-deps --no-build-isolation`.
109
+
110
+ ## Architecture notes (caller-does-semantics)
111
+
112
+ - Deterministic work (card assembly, parsing, schema validation, guards,
113
+ token estimation) is local and pure. The server never calls an LLM API
114
+ and holds no API keys (zero-server-cost invariant).
115
+ - Semantic work (slot extraction, compaction keep/drop judgment) belongs
116
+ to the CALLING model:
117
+ - `encode(slots={...})` — the caller extracts TASK/ROLE/IN/DO/OUT/LIM/BAN
118
+ from its own context and passes them directly (`mode: "slots"`,
119
+ `confidence: "caller"`). Pass `text` too for token metrics.
120
+ - `compact_to_l2l` — two-call protocol. Call 1 (`session_text` only)
121
+ returns a per-segment `scaffold` + `fill_slots_and_recall` +
122
+ a crude deterministic fallback. Call 2 adds
123
+ `segment_slots={"<seg>": {slots} | "TASK string"}`.
124
+ - `decode` / `verify` — deterministic.
125
+ - Freeform `encode(text=...)` without caller slots returns a deterministic
126
+ skeleton card plus `fill_slots_and_recall` guidance for a second call.
127
+ - MCP sampling (`session.create_message`) survives only as an OPTIONAL,
128
+ capability-detected upgrade path (deprecated upstream: MCP 2026-07-28
129
+ spec RC, SEP-2577; replaced by Multi Round-Trip Requests, SEP-2322;
130
+ Claude Code never implemented it, anthropics/claude-code#1785). It is
131
+ OFF unless the operator sets `HP_ENABLE_SAMPLING=1` AND the client
132
+ advertises the capability; results are always deterministically
133
+ re-validated. Nothing depends on sampling.
134
+ - Token estimates use ceil(chars/4). Crude by design; never used for
135
+ claims or billing.
136
+
137
+ ## Guard behavior
138
+
139
+ - Inputs under ~70 estimated tokens are returned unchanged with a reason
140
+ (encoding overhead exceeds savings below breakeven).
141
+ - BAN slots accept plain forbidden actions only. Conditional negation
142
+ ("X unless Y", "only outside Z") is rejected; express the condition as
143
+ a positive LIM constraint instead.
144
+ - Prose with high conditional-clause density gets an advise-skip verdict
145
+ instead of a lossy card.
handoffpack-0.1.0/README.md ADDED
@@ -0,0 +1,119 @@
1
+ # handoffpack — MCP structured-card translator
2
+
3
+ Deterministic codec + guards + MCP server for HP1 structured handoff cards.
4
+ Turns agent handoffs, session logs, and recurring-instruction files into
5
+ compact structured cards. All deterministic work runs locally; the server
6
+ never calls an LLM API and holds no API keys.
7
+
8
+ ## Install
9
+
10
+ Python 3.11+ required.
11
+
12
+ ```bash
13
+ # From PyPI (once published):
14
+ pip install handoffpack
15
+
16
+ # Pre-publish / local: from the package directory
17
+ pip install .
18
+ # or editable, with test deps:
19
+ pip install -e .[dev]
20
+ ```
21
+
22
+ Core codec/guards tests run with stdlib + pytest only; the `mcp` package
23
+ is needed only to run `server.py`.
24
+
25
+ ## Register the MCP server (Claude Code)
26
+
27
+ ```bash
28
+ python -m handoffpack.server # stdio transport, run directly
29
+ claude mcp add handoffpack -- python -m handoffpack.server
30
+ ```
31
+
32
+ Other clients (Cursor, etc.): use the same command in their MCP server
33
+ registration UI. A `handoffpack` console script is also installed as an
34
+ alias for `python -m handoffpack.server`.
35
+
36
+ ## License key (paid add-ons only)
37
+
38
+ The 4 MCP tools (`encode` / `decode` / `compact_to_l2l` / `verify`) are
39
+ FREE and unlimited. Only paid add-ons (e.g. the full `hp-instructions`
40
+ conversion run) require a key. The verifier is fully offline (embedded
41
+ Ed25519 public key, no phone-home). Key discovery precedence:
42
+
43
+ ```bash
44
+ export HP_LICENSE=HP1.xxxxx... # macOS/Linux
45
+ set HP_LICENSE=HP1.xxxxx... # Windows
46
+ # or place the key on the first line of ~/.handoffpack/license
47
+ # or pass --license <KEY> to hp-instructions
48
+ ```
49
+
50
+ `hp-instructions --check` (drift scan) is free; a full conversion run
51
+ requires a `plus`-tier key.
52
+
53
+ ## Layout
54
+
55
+ ```
56
+ mcp-translator/
57
+ ├── pyproject.toml
58
+ ├── src/handoffpack/
59
+ │ ├── legend.json # public card schema (typed slots + kv pairs)
60
+ │ ├── codec.py # assemble/parse/validate + chars/4 token estimator
61
+ │ ├── guards.py # breakeven passthrough, BAN-field rule, nuance heuristic
62
+ │ ├── license.py # offline Ed25519 license verifier (paid add-ons)
63
+ │ ├── adapter_instructions.py # hp-instructions CLI (CLAUDE.md -> HP1 cards)
64
+ │ └── server.py # MCP server: encode / decode / compact_to_l2l / verify
65
+ └── tests/
66
+ ```
67
+
68
+ ## Run tests
69
+
70
+ ```bash
71
+ pytest # 114 tests
72
+ ```
73
+
74
+ ## Build & publish (maintainer)
75
+
76
+ ```bash
77
+ python -m build # produces dist/*.whl + dist/*.tar.gz
78
+ python -m twine upload dist/*
79
+ ```
80
+
81
+ If `build` is unavailable offline, an equivalent wheel can be produced
82
+ with `python -m pip wheel . -w dist --no-deps --no-build-isolation`.
83
+
84
+ ## Architecture notes (caller-does-semantics)
85
+
86
+ - Deterministic work (card assembly, parsing, schema validation, guards,
87
+ token estimation) is local and pure. The server never calls an LLM API
88
+ and holds no API keys (zero-server-cost invariant).
89
+ - Semantic work (slot extraction, compaction keep/drop judgment) belongs
90
+ to the CALLING model:
91
+ - `encode(slots={...})` — the caller extracts TASK/ROLE/IN/DO/OUT/LIM/BAN
92
+ from its own context and passes them directly (`mode: "slots"`,
93
+ `confidence: "caller"`). Pass `text` too for token metrics.
94
+ - `compact_to_l2l` — two-call protocol. Call 1 (`session_text` only)
95
+ returns a per-segment `scaffold` + `fill_slots_and_recall` +
96
+ a crude deterministic fallback. Call 2 adds
97
+ `segment_slots={"<seg>": {slots} | "TASK string"}`.
98
+ - `decode` / `verify` — deterministic.
99
+ - Freeform `encode(text=...)` without caller slots returns a deterministic
100
+ skeleton card plus `fill_slots_and_recall` guidance for a second call.
101
+ - MCP sampling (`session.create_message`) survives only as an OPTIONAL,
102
+ capability-detected upgrade path (deprecated upstream: MCP 2026-07-28
103
+ spec RC, SEP-2577; replaced by Multi Round-Trip Requests, SEP-2322;
104
+ Claude Code never implemented it, anthropics/claude-code#1785). It is
105
+ OFF unless the operator sets `HP_ENABLE_SAMPLING=1` AND the client
106
+ advertises the capability; results are always deterministically
107
+ re-validated. Nothing depends on sampling.
108
+ - Token estimates use ceil(chars/4). Crude by design; never used for
109
+ claims or billing.
110
+
111
+ ## Guard behavior
112
+
113
+ - Inputs under ~70 estimated tokens are returned unchanged with a reason
114
+ (encoding overhead exceeds savings below breakeven).
115
+ - BAN slots accept plain forbidden actions only. Conditional negation
116
+ ("X unless Y", "only outside Z") is rejected; express the condition as
117
+ a positive LIM constraint instead.
118
+ - Prose with high conditional-clause density gets an advise-skip verdict
119
+ instead of a lossy card.
handoffpack-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,63 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "handoffpack"
7
+ version = "0.1.0"
8
+ description = "Deterministic structured handoff-card codec + MCP translator server for agent handoffs, session compaction, and instruction compilation (client-side sampling for semantics; zero server-side LLM cost)."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = { text = "LicenseRef-Proprietary" }
12
+ authors = [
13
+ { name = "Myeong Jun Jo" },
14
+ ]
15
+ keywords = [
16
+ "mcp",
17
+ "model-context-protocol",
18
+ "llm",
19
+ "agent",
20
+ "handoff",
21
+ "context-compaction",
22
+ "prompt-compression",
23
+ "claude",
24
+ ]
25
+ classifiers = [
26
+ "Development Status :: 4 - Beta",
27
+ "Intended Audience :: Developers",
28
+ "License :: Other/Proprietary License",
29
+ "Operating System :: OS Independent",
30
+ "Programming Language :: Python :: 3",
31
+ "Programming Language :: Python :: 3.11",
32
+ "Programming Language :: Python :: 3.12",
33
+ "Programming Language :: Python :: 3.13",
34
+ "Topic :: Software Development :: Libraries",
35
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
36
+ ]
37
+ dependencies = [
38
+ "mcp>=1.0",
39
+ "cryptography>=42",
40
+ ]
41
+
42
+ [project.optional-dependencies]
43
+ dev = [
44
+ "pytest>=8.0",
45
+ ]
46
+
47
+ [project.urls]
48
+ Homepage = "https://github.com/myeongjunjo/handoffpack"
49
+ Repository = "https://github.com/myeongjunjo/handoffpack"
50
+
51
+ [project.scripts]
52
+ hp-instructions = "handoffpack.adapter_instructions:main"
53
+ handoffpack = "handoffpack.server:main"
54
+
55
+ [tool.setuptools.packages.find]
56
+ where = ["src"]
57
+
58
+ [tool.setuptools.package-data]
59
+ handoffpack = ["legend.json"]
60
+
61
+ [tool.pytest.ini_options]
62
+ pythonpath = ["src"]
63
+ testpaths = ["tests"]
handoffpack-0.1.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
handoffpack-0.1.0/src/handoffpack/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """handoffpack — deterministic structured-card codec + guards + MCP translator server."""
2
+
3
+ __version__ = "0.1.0"