fpf-thinking-map 2.0.0__tar.gz → 2.0.2__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.
- fpf_thinking_map-2.0.2/NOTICE +16 -0
- fpf_thinking_map-2.0.2/PKG-INFO +241 -0
- fpf_thinking_map-2.0.2/README.md +205 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/__init__.py +10 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/agentic_structure.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/authorization.py +2 -0
- fpf_thinking_map-2.0.2/fpf_thinking_map/checkpoint.py +312 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/examples.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/guards.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/logic.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/move_intent.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/pending_input.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/primitives.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/reachability.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/state.py +35 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/traversal.py +2 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/verify.py +129 -0
- fpf_thinking_map-2.0.2/fpf_thinking_map.egg-info/PKG-INFO +241 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map.egg-info/SOURCES.txt +1 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/pyproject.toml +1 -1
- fpf_thinking_map-2.0.0/NOTICE +0 -36
- fpf_thinking_map-2.0.0/PKG-INFO +0 -431
- fpf_thinking_map-2.0.0/README.md +0 -395
- fpf_thinking_map-2.0.0/fpf_thinking_map.egg-info/PKG-INFO +0 -431
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/LICENSE +0 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map/py.typed +0 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map.egg-info/dependency_links.txt +0 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/fpf_thinking_map.egg-info/top_level.txt +0 -0
- {fpf_thinking_map-2.0.0 → fpf_thinking_map-2.0.2}/setup.cfg +0 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
FPF Thinking Map
|
|
2
|
+
================
|
|
3
|
+
|
|
4
|
+
Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L. <info@consolidare-continuum.com>
|
|
5
|
+
GitHub: @Consolidare-Continuum · https://consolidare-continuum.com
|
|
6
|
+
|
|
7
|
+
This runtime is a CONSOLIDARE CONTINUUM product: designed, owned, and published
|
|
8
|
+
for company and client delivery. It is not affiliated with any third-party
|
|
9
|
+
framework project.
|
|
10
|
+
|
|
11
|
+
Scope
|
|
12
|
+
-----
|
|
13
|
+
|
|
14
|
+
Independent traversal runtime with its own design boundaries, verification
|
|
15
|
+
suite, and release line. See docs/DECISIONS_REJECTIONS_ADOPTIONS.md for the
|
|
16
|
+
internal adoption record.
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fpf-thinking-map
|
|
3
|
+
Version: 2.0.2
|
|
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://github.com/Consolidare-Continuum/fpf-agentic-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
|
+
<p align="center">
|
|
38
|
+
<img src="https://raw.githubusercontent.com/Consolidare-Continuum/fpf-agentic-thinking-map/main/docs/assets/fpf-agentic-thinking-map-header-v20260818.png" alt="FPF Agentic Thinking Map — Agent freedom. Explicit movement rules." width="100%" />
|
|
39
|
+
</p>
|
|
40
|
+
|
|
41
|
+
# FPF Agentic Thinking Map
|
|
42
|
+
|
|
43
|
+
Deterministic Python runtime for agents that may reason freely but must move
|
|
44
|
+
through a workflow lawfully.
|
|
45
|
+
|
|
46
|
+
Operational state, evidence freshness, transition legality, authorization,
|
|
47
|
+
waiting, and move identity live **outside** model prose. The model proposes;
|
|
48
|
+
the runtime decides whether the move is valid.
|
|
49
|
+
|
|
50
|
+
**PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.2**
|
|
51
|
+
|
|
52
|
+
[](https://pypi.org/project/fpf-thinking-map/)
|
|
53
|
+
[](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
|
|
54
|
+
[](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
|
|
55
|
+
[](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/fpf_thinking_map/verify.py)
|
|
56
|
+
[](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
|
|
57
|
+
|
|
58
|
+
## Install
|
|
59
|
+
|
|
60
|
+
Requires **Python ≥ 3.12**. Zero runtime dependencies.
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install "fpf-thinking-map==2.0.1"
|
|
64
|
+
python -m fpf_thinking_map.verify # 40/40 (39/39 at v2.0.1)
|
|
65
|
+
python -m fpf_thinking_map.examples
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Full 2.0 line is on the index: [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/) (also [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/)).
|
|
69
|
+
|
|
70
|
+
## What it is
|
|
71
|
+
|
|
72
|
+
Agents lose workflow rules in long runs. This package moves the non-negotiable
|
|
73
|
+
parts into ordinary code:
|
|
74
|
+
|
|
75
|
+
- current context and state
|
|
76
|
+
- evidence presence and TTL freshness
|
|
77
|
+
- gates, guards, and lawful transitions
|
|
78
|
+
- cross-context bridges
|
|
79
|
+
- human authorization (`AuthorizationReceipt`)
|
|
80
|
+
- external wait (`PendingInput` / `AWAIT`)
|
|
81
|
+
- concrete move identity (`MoveIntent`)
|
|
82
|
+
- typed claim scope / pathwise reliability
|
|
83
|
+
- tool-call plan closure and autonomy budgets
|
|
84
|
+
|
|
85
|
+
Not a prompt. A compact **control surface** around reasoning.
|
|
86
|
+
|
|
87
|
+
## Contract
|
|
88
|
+
|
|
89
|
+
| Agent / host | This runtime |
|
|
90
|
+
| --- | --- |
|
|
91
|
+
| Interprets the task | Holds explicit traversal state |
|
|
92
|
+
| Generates options | Computes which moves are legal |
|
|
93
|
+
| Collects evidence | Checks presence and freshness |
|
|
94
|
+
| Proposes a move | Inspects or attempts that move |
|
|
95
|
+
| Explains the result | Returns a bounded outcome and trace |
|
|
96
|
+
| Requests human input | Enforces the authorization boundary |
|
|
97
|
+
| Runs tools and jobs | Never executes, polls, or schedules them |
|
|
98
|
+
|
|
99
|
+
## Structural controls (shipped)
|
|
100
|
+
|
|
101
|
+
| Concern | Structures | Effect |
|
|
102
|
+
| --- | --- | --- |
|
|
103
|
+
| Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
|
|
104
|
+
| Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
|
|
105
|
+
| Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; fail → `ESCALATE` |
|
|
106
|
+
| Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
|
|
107
|
+
| Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
|
|
108
|
+
| Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
|
|
109
|
+
| Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | Confirmed-absent percept clears declared neighbors |
|
|
110
|
+
|
|
111
|
+
## Demo
|
|
112
|
+
|
|
113
|
+
[](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
|
|
114
|
+
|
|
115
|
+
**[Interactive four-run trace](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)** — evidence recovery, `AWAIT`, `MoveIntent`, authorization, and `ABSTAIN` vs `BLOCK`.
|
|
116
|
+
|
|
117
|
+
## Minimal example
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
from fpf_thinking_map import (
|
|
121
|
+
SemanticMap,
|
|
122
|
+
ContextPrimitive,
|
|
123
|
+
RolePrimitive,
|
|
124
|
+
GatePrimitive,
|
|
125
|
+
GateCheck,
|
|
126
|
+
TransitionPrimitive,
|
|
127
|
+
RuntimeBinding,
|
|
128
|
+
ThinkingMapTraversal,
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
semantic_map = SemanticMap()
|
|
132
|
+
semantic_map.register_context(ContextPrimitive("deploy", "Deploy"))
|
|
133
|
+
semantic_map.register_role(RolePrimitive("owner", "Owner", "deploy"))
|
|
134
|
+
semantic_map.register_gate(
|
|
135
|
+
GatePrimitive(
|
|
136
|
+
"release_gate",
|
|
137
|
+
"Release gate",
|
|
138
|
+
"deploy",
|
|
139
|
+
checks=[
|
|
140
|
+
GateCheck(
|
|
141
|
+
"tests",
|
|
142
|
+
"Tests are green",
|
|
143
|
+
required_evidence=["test_results"],
|
|
144
|
+
)
|
|
145
|
+
],
|
|
146
|
+
)
|
|
147
|
+
)
|
|
148
|
+
semantic_map.register_transition(
|
|
149
|
+
TransitionPrimitive(
|
|
150
|
+
"ship",
|
|
151
|
+
"Ship release",
|
|
152
|
+
"deploy",
|
|
153
|
+
"candidate",
|
|
154
|
+
"released",
|
|
155
|
+
required_gate_id="release_gate",
|
|
156
|
+
required_evidence=["test_results"],
|
|
157
|
+
)
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
traversal = ThinkingMapTraversal(semantic_map)
|
|
161
|
+
state = traversal.build_active_state(
|
|
162
|
+
RuntimeBinding(
|
|
163
|
+
task="release",
|
|
164
|
+
actor_role_ids=["owner"],
|
|
165
|
+
active_context_id="deploy",
|
|
166
|
+
current_evidence=["test_results"],
|
|
167
|
+
),
|
|
168
|
+
current_state="candidate",
|
|
169
|
+
)
|
|
170
|
+
|
|
171
|
+
inspection = traversal.step(state)
|
|
172
|
+
result = traversal.attempt_transition(state, "ship")
|
|
173
|
+
print(inspection.kind, result.kind, state.current_state)
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Replace the deploy vocabulary with your own contexts, roles, evidence, and gates.
|
|
177
|
+
|
|
178
|
+
## Gate join (keep these apart)
|
|
179
|
+
|
|
180
|
+
| Gate result | Meaning | Typical outcome |
|
|
181
|
+
| --- | --- | --- |
|
|
182
|
+
| `ABSTAIN` (`insufficient`) | Not enough basis to say yes | `COLLECT_EVIDENCE` when evidence is declared |
|
|
183
|
+
| `BLOCK` | Declared policy says no for this evaluation | Denied with `cause=GATE_BLOCK` |
|
|
184
|
+
|
|
185
|
+
`BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
|
|
186
|
+
opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
|
|
187
|
+
|
|
188
|
+
## Release line
|
|
189
|
+
|
|
190
|
+
| Line | Capability |
|
|
191
|
+
| --- | --- |
|
|
192
|
+
| v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
|
|
193
|
+
| v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
|
|
194
|
+
| v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
|
|
195
|
+
| v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
|
|
196
|
+
| **v2.0.0** | Adjacency Clearance (`ADV-17`) |
|
|
197
|
+
| **v2.0.1** | Current — docs/metadata/reference hardware; runtime verify **39/39** |
|
|
198
|
+
|
|
199
|
+
History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
|
|
200
|
+
|
|
201
|
+
## Integrator notes (read before production)
|
|
202
|
+
|
|
203
|
+
Deliberate minimal defaults — not defects. Full text: [ADVISORIES.md](docs/deep/ADVISORIES.md).
|
|
204
|
+
|
|
205
|
+
| Priority | Advisory | One line |
|
|
206
|
+
| --- | --- | --- |
|
|
207
|
+
| Sharp | **ADV-03** | `active_context_id` is self-asserted — harness must own continuity |
|
|
208
|
+
| Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silent |
|
|
209
|
+
| Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
|
|
210
|
+
| Common | **ADV-10** | `requires_human_authorization` defaults off |
|
|
211
|
+
| 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
|
|
212
|
+
|
|
213
|
+
MCP harness: [`dev_mcp/`](dev_mcp/) — `run_scenario`, `get_advisories`, `run_verify`.
|
|
214
|
+
|
|
215
|
+
## Scope
|
|
216
|
+
|
|
217
|
+
**Use when you need:** bounded multi-step legality, evidence-aware state,
|
|
218
|
+
inspectable block/escalate reasons, human authorization, wait vs idle,
|
|
219
|
+
compact LLM state slices.
|
|
220
|
+
|
|
221
|
+
**Do not use as:** a universal reasoner, vector store, tool runner/scheduler,
|
|
222
|
+
or a certificate that an entire agent system is safe.
|
|
223
|
+
|
|
224
|
+
## Docs
|
|
225
|
+
|
|
226
|
+
| Path | Purpose |
|
|
227
|
+
| --- | --- |
|
|
228
|
+
| [`fpf_thinking_map/`](fpf_thinking_map/) | Zero-dependency runtime (PyPI **2.0.1**) |
|
|
229
|
+
| [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
|
|
230
|
+
| [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
|
|
231
|
+
| [SHA256SUMS](SHA256SUMS) | Source fingerprints |
|
|
232
|
+
|
|
233
|
+
## Product continuation
|
|
234
|
+
|
|
235
|
+
**CONSOLIDARE CONTINUUM S.R.L.** designs, owns, and ships this runtime for its own products and client work. No third-party framework affiliation. No external attribution required for use of this package.
|
|
236
|
+
|
|
237
|
+
## ISO evidence
|
|
238
|
+
|
|
239
|
+
[docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) — ISO/IEC 25010 · 27001 · 9001 alignment for **v2.0.1** (**not** certification).
|
|
240
|
+
|
|
241
|
+
**Agent freedom. Explicit movement rules.**
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/Consolidare-Continuum/fpf-agentic-thinking-map/main/docs/assets/fpf-agentic-thinking-map-header-v20260818.png" alt="FPF Agentic Thinking Map — Agent freedom. Explicit movement rules." width="100%" />
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# FPF Agentic Thinking Map
|
|
6
|
+
|
|
7
|
+
Deterministic Python runtime for agents that may reason freely but must move
|
|
8
|
+
through a workflow lawfully.
|
|
9
|
+
|
|
10
|
+
Operational state, evidence freshness, transition legality, authorization,
|
|
11
|
+
waiting, and move identity live **outside** model prose. The model proposes;
|
|
12
|
+
the runtime decides whether the move is valid.
|
|
13
|
+
|
|
14
|
+
**PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.2**
|
|
15
|
+
|
|
16
|
+
[](https://pypi.org/project/fpf-thinking-map/)
|
|
17
|
+
[](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
|
|
18
|
+
[](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
|
|
19
|
+
[](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/fpf_thinking_map/verify.py)
|
|
20
|
+
[](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
Requires **Python ≥ 3.12**. Zero runtime dependencies.
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install "fpf-thinking-map==2.0.1"
|
|
28
|
+
python -m fpf_thinking_map.verify # 40/40 (39/39 at v2.0.1)
|
|
29
|
+
python -m fpf_thinking_map.examples
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Full 2.0 line is on the index: [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/) (also [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/)).
|
|
33
|
+
|
|
34
|
+
## What it is
|
|
35
|
+
|
|
36
|
+
Agents lose workflow rules in long runs. This package moves the non-negotiable
|
|
37
|
+
parts into ordinary code:
|
|
38
|
+
|
|
39
|
+
- current context and state
|
|
40
|
+
- evidence presence and TTL freshness
|
|
41
|
+
- gates, guards, and lawful transitions
|
|
42
|
+
- cross-context bridges
|
|
43
|
+
- human authorization (`AuthorizationReceipt`)
|
|
44
|
+
- external wait (`PendingInput` / `AWAIT`)
|
|
45
|
+
- concrete move identity (`MoveIntent`)
|
|
46
|
+
- typed claim scope / pathwise reliability
|
|
47
|
+
- tool-call plan closure and autonomy budgets
|
|
48
|
+
|
|
49
|
+
Not a prompt. A compact **control surface** around reasoning.
|
|
50
|
+
|
|
51
|
+
## Contract
|
|
52
|
+
|
|
53
|
+
| Agent / host | This runtime |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| Interprets the task | Holds explicit traversal state |
|
|
56
|
+
| Generates options | Computes which moves are legal |
|
|
57
|
+
| Collects evidence | Checks presence and freshness |
|
|
58
|
+
| Proposes a move | Inspects or attempts that move |
|
|
59
|
+
| Explains the result | Returns a bounded outcome and trace |
|
|
60
|
+
| Requests human input | Enforces the authorization boundary |
|
|
61
|
+
| Runs tools and jobs | Never executes, polls, or schedules them |
|
|
62
|
+
|
|
63
|
+
## Structural controls (shipped)
|
|
64
|
+
|
|
65
|
+
| Concern | Structures | Effect |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
|
|
68
|
+
| Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
|
|
69
|
+
| Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; fail → `ESCALATE` |
|
|
70
|
+
| Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
|
|
71
|
+
| Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
|
|
72
|
+
| Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
|
|
73
|
+
| Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | Confirmed-absent percept clears declared neighbors |
|
|
74
|
+
|
|
75
|
+
## Demo
|
|
76
|
+
|
|
77
|
+
[](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
|
|
78
|
+
|
|
79
|
+
**[Interactive four-run trace](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)** — evidence recovery, `AWAIT`, `MoveIntent`, authorization, and `ABSTAIN` vs `BLOCK`.
|
|
80
|
+
|
|
81
|
+
## Minimal example
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
from fpf_thinking_map import (
|
|
85
|
+
SemanticMap,
|
|
86
|
+
ContextPrimitive,
|
|
87
|
+
RolePrimitive,
|
|
88
|
+
GatePrimitive,
|
|
89
|
+
GateCheck,
|
|
90
|
+
TransitionPrimitive,
|
|
91
|
+
RuntimeBinding,
|
|
92
|
+
ThinkingMapTraversal,
|
|
93
|
+
)
|
|
94
|
+
|
|
95
|
+
semantic_map = SemanticMap()
|
|
96
|
+
semantic_map.register_context(ContextPrimitive("deploy", "Deploy"))
|
|
97
|
+
semantic_map.register_role(RolePrimitive("owner", "Owner", "deploy"))
|
|
98
|
+
semantic_map.register_gate(
|
|
99
|
+
GatePrimitive(
|
|
100
|
+
"release_gate",
|
|
101
|
+
"Release gate",
|
|
102
|
+
"deploy",
|
|
103
|
+
checks=[
|
|
104
|
+
GateCheck(
|
|
105
|
+
"tests",
|
|
106
|
+
"Tests are green",
|
|
107
|
+
required_evidence=["test_results"],
|
|
108
|
+
)
|
|
109
|
+
],
|
|
110
|
+
)
|
|
111
|
+
)
|
|
112
|
+
semantic_map.register_transition(
|
|
113
|
+
TransitionPrimitive(
|
|
114
|
+
"ship",
|
|
115
|
+
"Ship release",
|
|
116
|
+
"deploy",
|
|
117
|
+
"candidate",
|
|
118
|
+
"released",
|
|
119
|
+
required_gate_id="release_gate",
|
|
120
|
+
required_evidence=["test_results"],
|
|
121
|
+
)
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
traversal = ThinkingMapTraversal(semantic_map)
|
|
125
|
+
state = traversal.build_active_state(
|
|
126
|
+
RuntimeBinding(
|
|
127
|
+
task="release",
|
|
128
|
+
actor_role_ids=["owner"],
|
|
129
|
+
active_context_id="deploy",
|
|
130
|
+
current_evidence=["test_results"],
|
|
131
|
+
),
|
|
132
|
+
current_state="candidate",
|
|
133
|
+
)
|
|
134
|
+
|
|
135
|
+
inspection = traversal.step(state)
|
|
136
|
+
result = traversal.attempt_transition(state, "ship")
|
|
137
|
+
print(inspection.kind, result.kind, state.current_state)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Replace the deploy vocabulary with your own contexts, roles, evidence, and gates.
|
|
141
|
+
|
|
142
|
+
## Gate join (keep these apart)
|
|
143
|
+
|
|
144
|
+
| Gate result | Meaning | Typical outcome |
|
|
145
|
+
| --- | --- | --- |
|
|
146
|
+
| `ABSTAIN` (`insufficient`) | Not enough basis to say yes | `COLLECT_EVIDENCE` when evidence is declared |
|
|
147
|
+
| `BLOCK` | Declared policy says no for this evaluation | Denied with `cause=GATE_BLOCK` |
|
|
148
|
+
|
|
149
|
+
`BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
|
|
150
|
+
opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
|
|
151
|
+
|
|
152
|
+
## Release line
|
|
153
|
+
|
|
154
|
+
| Line | Capability |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
|
|
157
|
+
| v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
|
|
158
|
+
| v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
|
|
159
|
+
| v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
|
|
160
|
+
| **v2.0.0** | Adjacency Clearance (`ADV-17`) |
|
|
161
|
+
| **v2.0.1** | Current — docs/metadata/reference hardware; runtime verify **39/39** |
|
|
162
|
+
|
|
163
|
+
History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
|
|
164
|
+
|
|
165
|
+
## Integrator notes (read before production)
|
|
166
|
+
|
|
167
|
+
Deliberate minimal defaults — not defects. Full text: [ADVISORIES.md](docs/deep/ADVISORIES.md).
|
|
168
|
+
|
|
169
|
+
| Priority | Advisory | One line |
|
|
170
|
+
| --- | --- | --- |
|
|
171
|
+
| Sharp | **ADV-03** | `active_context_id` is self-asserted — harness must own continuity |
|
|
172
|
+
| Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silent |
|
|
173
|
+
| Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
|
|
174
|
+
| Common | **ADV-10** | `requires_human_authorization` defaults off |
|
|
175
|
+
| 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
|
|
176
|
+
|
|
177
|
+
MCP harness: [`dev_mcp/`](dev_mcp/) — `run_scenario`, `get_advisories`, `run_verify`.
|
|
178
|
+
|
|
179
|
+
## Scope
|
|
180
|
+
|
|
181
|
+
**Use when you need:** bounded multi-step legality, evidence-aware state,
|
|
182
|
+
inspectable block/escalate reasons, human authorization, wait vs idle,
|
|
183
|
+
compact LLM state slices.
|
|
184
|
+
|
|
185
|
+
**Do not use as:** a universal reasoner, vector store, tool runner/scheduler,
|
|
186
|
+
or a certificate that an entire agent system is safe.
|
|
187
|
+
|
|
188
|
+
## Docs
|
|
189
|
+
|
|
190
|
+
| Path | Purpose |
|
|
191
|
+
| --- | --- |
|
|
192
|
+
| [`fpf_thinking_map/`](fpf_thinking_map/) | Zero-dependency runtime (PyPI **2.0.1**) |
|
|
193
|
+
| [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
|
|
194
|
+
| [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
|
|
195
|
+
| [SHA256SUMS](SHA256SUMS) | Source fingerprints |
|
|
196
|
+
|
|
197
|
+
## Product continuation
|
|
198
|
+
|
|
199
|
+
**CONSOLIDARE CONTINUUM S.R.L.** designs, owns, and ships this runtime for its own products and client work. No third-party framework affiliation. No external attribution required for use of this package.
|
|
200
|
+
|
|
201
|
+
## ISO evidence
|
|
202
|
+
|
|
203
|
+
[docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) — ISO/IEC 25010 · 27001 · 9001 alignment for **v2.0.1** (**not** certification).
|
|
204
|
+
|
|
205
|
+
**Agent freedom. Explicit movement rules.**
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
# Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L. <info@consolidare-continuum.com>
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
1
3
|
"""FPF Thinking Map — compiled semantic substrate for agentic traversal.
|
|
2
4
|
|
|
3
5
|
A structured board for LLM reasoning: the model navigates a pre-shaped
|
|
@@ -41,6 +43,14 @@ from fpf_thinking_map.authorization import (
|
|
|
41
43
|
issue_authorization_receipt,
|
|
42
44
|
)
|
|
43
45
|
|
|
46
|
+
# --- Checkpoint: supported round trip for a paused traversal (ADV-08) ---
|
|
47
|
+
from fpf_thinking_map.checkpoint import (
|
|
48
|
+
CheckpointError,
|
|
49
|
+
InvalidCheckpointState,
|
|
50
|
+
MapFingerprintMismatch,
|
|
51
|
+
UnsupportedCheckpointVersion,
|
|
52
|
+
)
|
|
53
|
+
|
|
44
54
|
# --- Guards: deterministic hard constraints ---
|
|
45
55
|
from fpf_thinking_map.guards import (
|
|
46
56
|
Guard,
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
# Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L. <info@consolidare-continuum.com>
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
1
3
|
"""Authorization receipts — a human's yes, scoped to the exact state it was given for.
|
|
2
4
|
|
|
3
5
|
`attempt_transition(state, "publish", authorized=True)` is an ambient boolean:
|