fpf-thinking-map 2.0.2__tar.gz → 2.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.
Potentially problematic release.
This version of fpf-thinking-map might be problematic. Click here for more details.
- fpf_thinking_map-2.1.0/PKG-INFO +273 -0
- fpf_thinking_map-2.1.0/README.md +237 -0
- fpf_thinking_map-2.1.0/fpf_thinking_map.egg-info/PKG-INFO +273 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/pyproject.toml +2 -2
- fpf_thinking_map-2.0.2/PKG-INFO +0 -241
- fpf_thinking_map-2.0.2/README.md +0 -205
- fpf_thinking_map-2.0.2/fpf_thinking_map.egg-info/PKG-INFO +0 -241
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/LICENSE +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/NOTICE +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/__init__.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/agentic_structure.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/authorization.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/checkpoint.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/examples.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/guards.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/logic.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/move_intent.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/pending_input.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/primitives.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/py.typed +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/reachability.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/state.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/traversal.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map/verify.py +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map.egg-info/SOURCES.txt +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map.egg-info/dependency_links.txt +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/fpf_thinking_map.egg-info/top_level.txt +0 -0
- {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.1.0}/setup.cfg +0 -0
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fpf-thinking-map
|
|
3
|
+
Version: 2.1.0
|
|
4
|
+
Summary: Deterministic Python runtime for lawful agent traversal with explicit state, evidence, authorization, waiting, and move identity.
|
|
5
|
+
Author-email: "CONSOLIDARE CONTINUUM S.R.L." <info@consolidare-continuum.com>
|
|
6
|
+
Maintainer-email: "CONSOLIDARE CONTINUUM S.R.L." <info@consolidare-continuum.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Project-URL: Homepage, https://consolidare-continuum.com/fpf-thinking-map/
|
|
9
|
+
Project-URL: Repository, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map
|
|
10
|
+
Project-URL: Documentation, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map#readme
|
|
11
|
+
Project-URL: Issues, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/issues
|
|
12
|
+
Project-URL: Architecture, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/ARCHITECTURE.md
|
|
13
|
+
Project-URL: Changelog, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/CHANGELOG.md
|
|
14
|
+
Project-URL: Contributing, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/CONTRIBUTING.md
|
|
15
|
+
Project-URL: Advisories, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/docs/deep/ADVISORIES.md
|
|
16
|
+
Project-URL: Website, https://consolidare-continuum.com
|
|
17
|
+
Project-URL: GitHub, https://github.com/Consolidare-Continuum
|
|
18
|
+
Project-URL: Telegram, https://t.me/igareosh
|
|
19
|
+
Project-URL: Demo, https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html
|
|
20
|
+
Keywords: agentic,thinking-map,llm,reasoning,propositional-logic,evidence-decay,ttl,guards,gates,semantic-map,fpf,human-in-the-loop,ignition-lock,hitl,safety,authorization,await,move-intent,workflow
|
|
21
|
+
Classifier: Development Status :: 4 - Beta
|
|
22
|
+
Classifier: Intended Audience :: Developers
|
|
23
|
+
Classifier: Intended Audience :: Science/Research
|
|
24
|
+
Classifier: Operating System :: OS Independent
|
|
25
|
+
Classifier: Programming Language :: Python :: 3
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
28
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
29
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
30
|
+
Classifier: Typing :: Typed
|
|
31
|
+
Requires-Python: >=3.12
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
License-File: LICENSE
|
|
34
|
+
License-File: NOTICE
|
|
35
|
+
Dynamic: license-file
|
|
36
|
+
|
|
37
|
+
# fpf-thinking-map
|
|
38
|
+
|
|
39
|
+
A small Python library that tracks the state of a multi-step agent workflow
|
|
40
|
+
and answers one question: *is this next move allowed right now, and if not,
|
|
41
|
+
why?*
|
|
42
|
+
|
|
43
|
+
You describe a workflow as a graph (contexts, roles, evidence, gates,
|
|
44
|
+
transitions). Your agent harness feeds the library the current state and the
|
|
45
|
+
move the agent proposes. The library returns a legal/illegal outcome with the
|
|
46
|
+
reason and a trace. It does not call a model, run tools, poll, or schedule
|
|
47
|
+
anything.
|
|
48
|
+
|
|
49
|
+
**PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.1.0** · **License:** MIT
|
|
50
|
+
|
|
51
|
+
[](https://pypi.org/project/fpf-thinking-map/)
|
|
52
|
+
[](pyproject.toml)
|
|
53
|
+
[](LICENSE)
|
|
54
|
+
|
|
55
|
+
## Install
|
|
56
|
+
|
|
57
|
+
Requires **Python ≥ 3.12**. No runtime dependencies.
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pip install "fpf-thinking-map==2.1.0"
|
|
61
|
+
python -m fpf_thinking_map.verify # the package's own self-tests, 40 checks
|
|
62
|
+
python -m fpf_thinking_map.examples
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Other releases on the index: [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/), [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/).
|
|
66
|
+
|
|
67
|
+
## Minimal example
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
from fpf_thinking_map import (
|
|
71
|
+
SemanticMap,
|
|
72
|
+
ContextPrimitive,
|
|
73
|
+
RolePrimitive,
|
|
74
|
+
GatePrimitive,
|
|
75
|
+
GateCheck,
|
|
76
|
+
TransitionPrimitive,
|
|
77
|
+
RuntimeBinding,
|
|
78
|
+
ThinkingMapTraversal,
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
semantic_map = SemanticMap()
|
|
82
|
+
semantic_map.register_context(ContextPrimitive("deploy", "Deploy"))
|
|
83
|
+
semantic_map.register_role(RolePrimitive("owner", "Owner", "deploy"))
|
|
84
|
+
semantic_map.register_gate(
|
|
85
|
+
GatePrimitive(
|
|
86
|
+
"release_gate",
|
|
87
|
+
"Release gate",
|
|
88
|
+
"deploy",
|
|
89
|
+
checks=[
|
|
90
|
+
GateCheck(
|
|
91
|
+
"tests",
|
|
92
|
+
"Tests are green",
|
|
93
|
+
required_evidence=["test_results"],
|
|
94
|
+
)
|
|
95
|
+
],
|
|
96
|
+
)
|
|
97
|
+
)
|
|
98
|
+
semantic_map.register_transition(
|
|
99
|
+
TransitionPrimitive(
|
|
100
|
+
"ship",
|
|
101
|
+
"Ship release",
|
|
102
|
+
"deploy",
|
|
103
|
+
"candidate",
|
|
104
|
+
"released",
|
|
105
|
+
required_gate_id="release_gate",
|
|
106
|
+
required_evidence=["test_results"],
|
|
107
|
+
)
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
traversal = ThinkingMapTraversal(semantic_map)
|
|
111
|
+
state = traversal.build_active_state(
|
|
112
|
+
RuntimeBinding(
|
|
113
|
+
task="release",
|
|
114
|
+
actor_role_ids=["owner"],
|
|
115
|
+
active_context_id="deploy",
|
|
116
|
+
current_evidence=["test_results"],
|
|
117
|
+
),
|
|
118
|
+
current_state="candidate",
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
inspection = traversal.step(state)
|
|
122
|
+
result = traversal.attempt_transition(state, "ship")
|
|
123
|
+
print(inspection.kind, result.kind, state.current_state)
|
|
124
|
+
# OutcomeKind.CONTINUE OutcomeKind.CONTINUE released
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Replace the deploy vocabulary with your own contexts, roles, evidence and gates.
|
|
128
|
+
|
|
129
|
+
## What it does
|
|
130
|
+
|
|
131
|
+
- Holds explicit traversal state: current context, state, and evidence.
|
|
132
|
+
- Checks evidence presence and freshness. Freshness decays over **traversal
|
|
133
|
+
steps**, not wall-clock time.
|
|
134
|
+
- Evaluates gates, guards and transitions and says which moves are legal.
|
|
135
|
+
- Supports cross-context bridges with validated writeback.
|
|
136
|
+
- Supports human authorization (`AuthorizationReceipt`): scoped, non-replayable.
|
|
137
|
+
- Distinguishes waiting on external input (`PendingInput` / `AWAIT`) from idle.
|
|
138
|
+
- Gives a proposed move a concrete identity (`MoveIntent`) that can be inspected.
|
|
139
|
+
- Can checkpoint and restore a paused traversal (`ActiveState.checkpoint()`,
|
|
140
|
+
`from_checkpoint()`); restore is all-or-nothing and never repairs.
|
|
141
|
+
|
|
142
|
+
Given the same map, state, evidence and receipts, it returns the same result.
|
|
143
|
+
The core modules call no clock, random source, network or model.
|
|
144
|
+
|
|
145
|
+
## Division of work
|
|
146
|
+
|
|
147
|
+
| Agent / host | This library |
|
|
148
|
+
| --- | --- |
|
|
149
|
+
| Interprets the task | Holds explicit traversal state |
|
|
150
|
+
| Generates options | Computes which moves are legal |
|
|
151
|
+
| Collects evidence | Checks presence and freshness |
|
|
152
|
+
| Proposes a move | Inspects or attempts that move |
|
|
153
|
+
| Explains the result | Returns a bounded outcome and trace |
|
|
154
|
+
| Requests human input | Enforces the authorization boundary |
|
|
155
|
+
| Runs tools and jobs | Never executes, polls or schedules them |
|
|
156
|
+
|
|
157
|
+
## Limits
|
|
158
|
+
|
|
159
|
+
- **It only constrains what is routed through it.** A harness or agent that
|
|
160
|
+
does not call the library is not constrained. There is no sandbox.
|
|
161
|
+
- **State lives in the host process.** The library keeps no storage of its
|
|
162
|
+
own; use `checkpoint()` to persist a paused traversal.
|
|
163
|
+
- **Several inputs are self-asserted.** For example `active_context_id`
|
|
164
|
+
(advisory ADV-03): the harness must own continuity.
|
|
165
|
+
- **Defaults are minimal.** Stale evidence warns but does not block unless a
|
|
166
|
+
gate requires it, and `requires_human_authorization` defaults off.
|
|
167
|
+
- **It is not a universal reasoner,** a vector store, a tool runner or
|
|
168
|
+
scheduler, or a certificate that an agent system is safe.
|
|
169
|
+
|
|
170
|
+
Full list of integrator boundaries: [ADVISORIES.md](docs/deep/ADVISORIES.md).
|
|
171
|
+
|
|
172
|
+
## What the evidence shows
|
|
173
|
+
|
|
174
|
+
- **Self-tests.** `python -m fpf_thinking_map.verify` (40 checks) and
|
|
175
|
+
`dev_mcp/test_server.py` (45 checks) are written and run by the authors. They
|
|
176
|
+
check that the library does what it is specified to do. They have not been
|
|
177
|
+
audited by a third party.
|
|
178
|
+
- **Does it make agents safer?** One small benchmark exists
|
|
179
|
+
([bench/RESULTS.md](bench/RESULTS.md)): two tasks, one frontier-model class,
|
|
180
|
+
5 runs per condition, 20 runs total. The model made **no policy violations
|
|
181
|
+
with or without** the library, so there is **no measured compliance
|
|
182
|
+
improvement** for a cooperative model on a clearly stated task. With the
|
|
183
|
+
library the model made *more* tool calls (4.4 vs 1.0 and 2.0 vs 1.0), because
|
|
184
|
+
it used the inspection calls before acting. Weaker or adversarial models were
|
|
185
|
+
not tested.
|
|
186
|
+
- **ISO.** [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) maps
|
|
187
|
+
release 2.0.1 against ISO/IEC 25010, 27001 and 9001 as a self-assessed
|
|
188
|
+
checklist. It is **not** an audit and **not** a certification.
|
|
189
|
+
|
|
190
|
+
## Shipped structures
|
|
191
|
+
|
|
192
|
+
| Concern | Structures | Effect |
|
|
193
|
+
| --- | --- | --- |
|
|
194
|
+
| Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
|
|
195
|
+
| Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
|
|
196
|
+
| Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; failure → `ESCALATE` |
|
|
197
|
+
| Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
|
|
198
|
+
| Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
|
|
199
|
+
| Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
|
|
200
|
+
| Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | A confirmed-absent percept clears declared neighbours |
|
|
201
|
+
| Continuity (2.0.2) | `ActiveState.checkpoint()`, `from_checkpoint()` | Persist and restore a paused traversal |
|
|
202
|
+
|
|
203
|
+
### Gate join
|
|
204
|
+
|
|
205
|
+
| Gate result | Meaning | Typical outcome |
|
|
206
|
+
| --- | --- | --- |
|
|
207
|
+
| `ABSTAIN` (`insufficient`) | Not enough basis to say yes | `COLLECT_EVIDENCE` when evidence is declared |
|
|
208
|
+
| `BLOCK` | Declared policy says no for this evaluation | Denied with `cause=GATE_BLOCK` |
|
|
209
|
+
|
|
210
|
+
`BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
|
|
211
|
+
opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
|
|
212
|
+
|
|
213
|
+
## Demo
|
|
214
|
+
|
|
215
|
+
[Four interactive traces](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
|
|
216
|
+
(evidence recovery, `AWAIT`, `MoveIntent` with authorization, `ABSTAIN` vs
|
|
217
|
+
`BLOCK`). They follow behavior covered by the test suite as of v1.9.5; they are
|
|
218
|
+
not a recording of a live model run and do not show later features.
|
|
219
|
+
|
|
220
|
+
## Releases
|
|
221
|
+
|
|
222
|
+
| Line | Change |
|
|
223
|
+
| --- | --- |
|
|
224
|
+
| v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
|
|
225
|
+
| v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
|
|
226
|
+
| v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
|
|
227
|
+
| v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
|
|
228
|
+
| v2.0.0 | Adjacency clearance (`ADV-17`) |
|
|
229
|
+
| v2.0.1 | Docs and metadata only; runtime identical to 2.0.0 |
|
|
230
|
+
| v2.0.2 | Copyright and SPDX notices on every source file (license unchanged); includes traversal checkpoint and restore (`ADV-08`) |
|
|
231
|
+
| v2.0.3 | Docs and metadata only; runtime identical to 2.0.2. Removes the upstream-intake advisory (`ADV-16`) and every named reference to the external specification this package was historically informed by; independence disclaimer reworded |
|
|
232
|
+
| **v2.1.0** | Docs only; runtime identical to 2.0.3. Fixes a stale doc line claiming checkpoint/restore was unbuilt |
|
|
233
|
+
|
|
234
|
+
History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
|
|
235
|
+
|
|
236
|
+
## Integrator notes
|
|
237
|
+
|
|
238
|
+
| Priority | Advisory | One line |
|
|
239
|
+
| --- | --- | --- |
|
|
240
|
+
| Sharp | **ADV-03** | `active_context_id` is self-asserted: the harness must own continuity |
|
|
241
|
+
| Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silently |
|
|
242
|
+
| Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
|
|
243
|
+
| Common | **ADV-10** | `requires_human_authorization` defaults off |
|
|
244
|
+
| 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
|
|
245
|
+
|
|
246
|
+
MCP test harness: [`dev_mcp/`](dev_mcp/) (`run_scenario`, `get_advisories`, `run_verify`).
|
|
247
|
+
|
|
248
|
+
## Repository
|
|
249
|
+
|
|
250
|
+
| Path | Purpose |
|
|
251
|
+
| --- | --- |
|
|
252
|
+
| [`fpf_thinking_map/`](fpf_thinking_map/) | The runtime (no dependencies) |
|
|
253
|
+
| [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
|
|
254
|
+
| [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
|
|
255
|
+
| [bench/](bench/) | The ablation benchmark and its raw results |
|
|
256
|
+
| [SHA256SUMS](SHA256SUMS) | Source file checksums |
|
|
257
|
+
|
|
258
|
+
## License and ownership
|
|
259
|
+
|
|
260
|
+
MIT. Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L.
|
|
261
|
+
|
|
262
|
+
Copyrighted build: release **2.0.2**, commit
|
|
263
|
+
[`f0a17a543a23cbc8a33071b170a02ccf41fd33b7`](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/commit/f0a17a543a23cbc8a33071b170a02ccf41fd33b7)
|
|
264
|
+
(signed tag `v2.0.2`). Every source file in that commit carries the copyright
|
|
265
|
+
and SPDX notice.
|
|
266
|
+
|
|
267
|
+
The MIT license requires
|
|
268
|
+
that the copyright notice and license text be kept in copies and substantial
|
|
269
|
+
portions of the software; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
|
|
270
|
+
|
|
271
|
+
This is an independent implementation, out of scope of and not derived from
|
|
272
|
+
any third-party framework's document or ontology. It is not affiliated
|
|
273
|
+
with, sponsored by, or endorsed by any such project.
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
# fpf-thinking-map
|
|
2
|
+
|
|
3
|
+
A small Python library that tracks the state of a multi-step agent workflow
|
|
4
|
+
and answers one question: *is this next move allowed right now, and if not,
|
|
5
|
+
why?*
|
|
6
|
+
|
|
7
|
+
You describe a workflow as a graph (contexts, roles, evidence, gates,
|
|
8
|
+
transitions). Your agent harness feeds the library the current state and the
|
|
9
|
+
move the agent proposes. The library returns a legal/illegal outcome with the
|
|
10
|
+
reason and a trace. It does not call a model, run tools, poll, or schedule
|
|
11
|
+
anything.
|
|
12
|
+
|
|
13
|
+
**PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.1.0** · **License:** MIT
|
|
14
|
+
|
|
15
|
+
[](https://pypi.org/project/fpf-thinking-map/)
|
|
16
|
+
[](pyproject.toml)
|
|
17
|
+
[](LICENSE)
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
Requires **Python ≥ 3.12**. No runtime dependencies.
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install "fpf-thinking-map==2.1.0"
|
|
25
|
+
python -m fpf_thinking_map.verify # the package's own self-tests, 40 checks
|
|
26
|
+
python -m fpf_thinking_map.examples
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Other releases on the index: [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/), [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/).
|
|
30
|
+
|
|
31
|
+
## Minimal example
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
from fpf_thinking_map import (
|
|
35
|
+
SemanticMap,
|
|
36
|
+
ContextPrimitive,
|
|
37
|
+
RolePrimitive,
|
|
38
|
+
GatePrimitive,
|
|
39
|
+
GateCheck,
|
|
40
|
+
TransitionPrimitive,
|
|
41
|
+
RuntimeBinding,
|
|
42
|
+
ThinkingMapTraversal,
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
semantic_map = SemanticMap()
|
|
46
|
+
semantic_map.register_context(ContextPrimitive("deploy", "Deploy"))
|
|
47
|
+
semantic_map.register_role(RolePrimitive("owner", "Owner", "deploy"))
|
|
48
|
+
semantic_map.register_gate(
|
|
49
|
+
GatePrimitive(
|
|
50
|
+
"release_gate",
|
|
51
|
+
"Release gate",
|
|
52
|
+
"deploy",
|
|
53
|
+
checks=[
|
|
54
|
+
GateCheck(
|
|
55
|
+
"tests",
|
|
56
|
+
"Tests are green",
|
|
57
|
+
required_evidence=["test_results"],
|
|
58
|
+
)
|
|
59
|
+
],
|
|
60
|
+
)
|
|
61
|
+
)
|
|
62
|
+
semantic_map.register_transition(
|
|
63
|
+
TransitionPrimitive(
|
|
64
|
+
"ship",
|
|
65
|
+
"Ship release",
|
|
66
|
+
"deploy",
|
|
67
|
+
"candidate",
|
|
68
|
+
"released",
|
|
69
|
+
required_gate_id="release_gate",
|
|
70
|
+
required_evidence=["test_results"],
|
|
71
|
+
)
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
traversal = ThinkingMapTraversal(semantic_map)
|
|
75
|
+
state = traversal.build_active_state(
|
|
76
|
+
RuntimeBinding(
|
|
77
|
+
task="release",
|
|
78
|
+
actor_role_ids=["owner"],
|
|
79
|
+
active_context_id="deploy",
|
|
80
|
+
current_evidence=["test_results"],
|
|
81
|
+
),
|
|
82
|
+
current_state="candidate",
|
|
83
|
+
)
|
|
84
|
+
|
|
85
|
+
inspection = traversal.step(state)
|
|
86
|
+
result = traversal.attempt_transition(state, "ship")
|
|
87
|
+
print(inspection.kind, result.kind, state.current_state)
|
|
88
|
+
# OutcomeKind.CONTINUE OutcomeKind.CONTINUE released
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Replace the deploy vocabulary with your own contexts, roles, evidence and gates.
|
|
92
|
+
|
|
93
|
+
## What it does
|
|
94
|
+
|
|
95
|
+
- Holds explicit traversal state: current context, state, and evidence.
|
|
96
|
+
- Checks evidence presence and freshness. Freshness decays over **traversal
|
|
97
|
+
steps**, not wall-clock time.
|
|
98
|
+
- Evaluates gates, guards and transitions and says which moves are legal.
|
|
99
|
+
- Supports cross-context bridges with validated writeback.
|
|
100
|
+
- Supports human authorization (`AuthorizationReceipt`): scoped, non-replayable.
|
|
101
|
+
- Distinguishes waiting on external input (`PendingInput` / `AWAIT`) from idle.
|
|
102
|
+
- Gives a proposed move a concrete identity (`MoveIntent`) that can be inspected.
|
|
103
|
+
- Can checkpoint and restore a paused traversal (`ActiveState.checkpoint()`,
|
|
104
|
+
`from_checkpoint()`); restore is all-or-nothing and never repairs.
|
|
105
|
+
|
|
106
|
+
Given the same map, state, evidence and receipts, it returns the same result.
|
|
107
|
+
The core modules call no clock, random source, network or model.
|
|
108
|
+
|
|
109
|
+
## Division of work
|
|
110
|
+
|
|
111
|
+
| Agent / host | This library |
|
|
112
|
+
| --- | --- |
|
|
113
|
+
| Interprets the task | Holds explicit traversal state |
|
|
114
|
+
| Generates options | Computes which moves are legal |
|
|
115
|
+
| Collects evidence | Checks presence and freshness |
|
|
116
|
+
| Proposes a move | Inspects or attempts that move |
|
|
117
|
+
| Explains the result | Returns a bounded outcome and trace |
|
|
118
|
+
| Requests human input | Enforces the authorization boundary |
|
|
119
|
+
| Runs tools and jobs | Never executes, polls or schedules them |
|
|
120
|
+
|
|
121
|
+
## Limits
|
|
122
|
+
|
|
123
|
+
- **It only constrains what is routed through it.** A harness or agent that
|
|
124
|
+
does not call the library is not constrained. There is no sandbox.
|
|
125
|
+
- **State lives in the host process.** The library keeps no storage of its
|
|
126
|
+
own; use `checkpoint()` to persist a paused traversal.
|
|
127
|
+
- **Several inputs are self-asserted.** For example `active_context_id`
|
|
128
|
+
(advisory ADV-03): the harness must own continuity.
|
|
129
|
+
- **Defaults are minimal.** Stale evidence warns but does not block unless a
|
|
130
|
+
gate requires it, and `requires_human_authorization` defaults off.
|
|
131
|
+
- **It is not a universal reasoner,** a vector store, a tool runner or
|
|
132
|
+
scheduler, or a certificate that an agent system is safe.
|
|
133
|
+
|
|
134
|
+
Full list of integrator boundaries: [ADVISORIES.md](docs/deep/ADVISORIES.md).
|
|
135
|
+
|
|
136
|
+
## What the evidence shows
|
|
137
|
+
|
|
138
|
+
- **Self-tests.** `python -m fpf_thinking_map.verify` (40 checks) and
|
|
139
|
+
`dev_mcp/test_server.py` (45 checks) are written and run by the authors. They
|
|
140
|
+
check that the library does what it is specified to do. They have not been
|
|
141
|
+
audited by a third party.
|
|
142
|
+
- **Does it make agents safer?** One small benchmark exists
|
|
143
|
+
([bench/RESULTS.md](bench/RESULTS.md)): two tasks, one frontier-model class,
|
|
144
|
+
5 runs per condition, 20 runs total. The model made **no policy violations
|
|
145
|
+
with or without** the library, so there is **no measured compliance
|
|
146
|
+
improvement** for a cooperative model on a clearly stated task. With the
|
|
147
|
+
library the model made *more* tool calls (4.4 vs 1.0 and 2.0 vs 1.0), because
|
|
148
|
+
it used the inspection calls before acting. Weaker or adversarial models were
|
|
149
|
+
not tested.
|
|
150
|
+
- **ISO.** [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) maps
|
|
151
|
+
release 2.0.1 against ISO/IEC 25010, 27001 and 9001 as a self-assessed
|
|
152
|
+
checklist. It is **not** an audit and **not** a certification.
|
|
153
|
+
|
|
154
|
+
## Shipped structures
|
|
155
|
+
|
|
156
|
+
| Concern | Structures | Effect |
|
|
157
|
+
| --- | --- | --- |
|
|
158
|
+
| Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
|
|
159
|
+
| Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
|
|
160
|
+
| Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; failure → `ESCALATE` |
|
|
161
|
+
| Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
|
|
162
|
+
| Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
|
|
163
|
+
| Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
|
|
164
|
+
| Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | A confirmed-absent percept clears declared neighbours |
|
|
165
|
+
| Continuity (2.0.2) | `ActiveState.checkpoint()`, `from_checkpoint()` | Persist and restore a paused traversal |
|
|
166
|
+
|
|
167
|
+
### Gate join
|
|
168
|
+
|
|
169
|
+
| Gate result | Meaning | Typical outcome |
|
|
170
|
+
| --- | --- | --- |
|
|
171
|
+
| `ABSTAIN` (`insufficient`) | Not enough basis to say yes | `COLLECT_EVIDENCE` when evidence is declared |
|
|
172
|
+
| `BLOCK` | Declared policy says no for this evaluation | Denied with `cause=GATE_BLOCK` |
|
|
173
|
+
|
|
174
|
+
`BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
|
|
175
|
+
opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
|
|
176
|
+
|
|
177
|
+
## Demo
|
|
178
|
+
|
|
179
|
+
[Four interactive traces](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
|
|
180
|
+
(evidence recovery, `AWAIT`, `MoveIntent` with authorization, `ABSTAIN` vs
|
|
181
|
+
`BLOCK`). They follow behavior covered by the test suite as of v1.9.5; they are
|
|
182
|
+
not a recording of a live model run and do not show later features.
|
|
183
|
+
|
|
184
|
+
## Releases
|
|
185
|
+
|
|
186
|
+
| Line | Change |
|
|
187
|
+
| --- | --- |
|
|
188
|
+
| v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
|
|
189
|
+
| v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
|
|
190
|
+
| v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
|
|
191
|
+
| v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
|
|
192
|
+
| v2.0.0 | Adjacency clearance (`ADV-17`) |
|
|
193
|
+
| v2.0.1 | Docs and metadata only; runtime identical to 2.0.0 |
|
|
194
|
+
| v2.0.2 | Copyright and SPDX notices on every source file (license unchanged); includes traversal checkpoint and restore (`ADV-08`) |
|
|
195
|
+
| v2.0.3 | Docs and metadata only; runtime identical to 2.0.2. Removes the upstream-intake advisory (`ADV-16`) and every named reference to the external specification this package was historically informed by; independence disclaimer reworded |
|
|
196
|
+
| **v2.1.0** | Docs only; runtime identical to 2.0.3. Fixes a stale doc line claiming checkpoint/restore was unbuilt |
|
|
197
|
+
|
|
198
|
+
History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
|
|
199
|
+
|
|
200
|
+
## Integrator notes
|
|
201
|
+
|
|
202
|
+
| Priority | Advisory | One line |
|
|
203
|
+
| --- | --- | --- |
|
|
204
|
+
| Sharp | **ADV-03** | `active_context_id` is self-asserted: the harness must own continuity |
|
|
205
|
+
| Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silently |
|
|
206
|
+
| Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
|
|
207
|
+
| Common | **ADV-10** | `requires_human_authorization` defaults off |
|
|
208
|
+
| 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
|
|
209
|
+
|
|
210
|
+
MCP test harness: [`dev_mcp/`](dev_mcp/) (`run_scenario`, `get_advisories`, `run_verify`).
|
|
211
|
+
|
|
212
|
+
## Repository
|
|
213
|
+
|
|
214
|
+
| Path | Purpose |
|
|
215
|
+
| --- | --- |
|
|
216
|
+
| [`fpf_thinking_map/`](fpf_thinking_map/) | The runtime (no dependencies) |
|
|
217
|
+
| [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
|
|
218
|
+
| [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
|
|
219
|
+
| [bench/](bench/) | The ablation benchmark and its raw results |
|
|
220
|
+
| [SHA256SUMS](SHA256SUMS) | Source file checksums |
|
|
221
|
+
|
|
222
|
+
## License and ownership
|
|
223
|
+
|
|
224
|
+
MIT. Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L.
|
|
225
|
+
|
|
226
|
+
Copyrighted build: release **2.0.2**, commit
|
|
227
|
+
[`f0a17a543a23cbc8a33071b170a02ccf41fd33b7`](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/commit/f0a17a543a23cbc8a33071b170a02ccf41fd33b7)
|
|
228
|
+
(signed tag `v2.0.2`). Every source file in that commit carries the copyright
|
|
229
|
+
and SPDX notice.
|
|
230
|
+
|
|
231
|
+
The MIT license requires
|
|
232
|
+
that the copyright notice and license text be kept in copies and substantial
|
|
233
|
+
portions of the software; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
|
|
234
|
+
|
|
235
|
+
This is an independent implementation, out of scope of and not derived from
|
|
236
|
+
any third-party framework's document or ontology. It is not affiliated
|
|
237
|
+
with, sponsored by, or endorsed by any such project.
|