reason-rdn 0.4.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.
- reason_rdn-0.4.0/LICENSE +21 -0
- reason_rdn-0.4.0/PKG-INFO +321 -0
- reason_rdn-0.4.0/README.md +274 -0
- reason_rdn-0.4.0/pyproject.toml +68 -0
- reason_rdn-0.4.0/rdn/__init__.py +82 -0
- reason_rdn-0.4.0/rdn/cli.py +246 -0
- reason_rdn-0.4.0/rdn/client.py +833 -0
- reason_rdn-0.4.0/rdn/core/__init__.py +2 -0
- reason_rdn-0.4.0/rdn/dash.py +396 -0
- reason_rdn-0.4.0/rdn/handoff/__init__.py +30 -0
- reason_rdn-0.4.0/rdn/handoff/_pcf.py +69 -0
- reason_rdn-0.4.0/rdn/handoff/engine.py +31 -0
- reason_rdn-0.4.0/rdn/handoff/protocol.py +110 -0
- reason_rdn-0.4.0/rdn/handoff/sync.py +349 -0
- reason_rdn-0.4.0/rdn/mcp/__init__.py +6 -0
- reason_rdn-0.4.0/rdn/mcp/server.py +358 -0
- reason_rdn-0.4.0/rdn/node/__init__.py +30 -0
- reason_rdn-0.4.0/rdn/node/server.py +399 -0
- reason_rdn-0.4.0/rdn/reason.py +321 -0
- reason_rdn-0.4.0/reason_rdn.egg-info/PKG-INFO +321 -0
- reason_rdn-0.4.0/reason_rdn.egg-info/SOURCES.txt +26 -0
- reason_rdn-0.4.0/reason_rdn.egg-info/dependency_links.txt +1 -0
- reason_rdn-0.4.0/reason_rdn.egg-info/entry_points.txt +6 -0
- reason_rdn-0.4.0/reason_rdn.egg-info/requires.txt +24 -0
- reason_rdn-0.4.0/reason_rdn.egg-info/top_level.txt +1 -0
- reason_rdn-0.4.0/setup.cfg +4 -0
- reason_rdn-0.4.0/setup.py +20 -0
- reason_rdn-0.4.0/tests/test_coherent_memory.py +181 -0
reason_rdn-0.4.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Astrognosy
|
|
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,321 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: reason-rdn
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: ReasonRDN — the shared memory substrate for the agentic era. Local-first with seamless auto-deposit to the warf Xchange (https://warf.astrognosy.com). reason:// handoffs, protected structural fingerprints (PCF), unified client, embedded node, first-class MCP, and CLI.
|
|
5
|
+
Author-email: Astrognosy <info@astrognosy.com>
|
|
6
|
+
License: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/Astrognosy/reason-ecosystem
|
|
8
|
+
Project-URL: Documentation, https://github.com/Astrognosy/reason-ecosystem#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/Astrognosy/reason-ecosystem
|
|
10
|
+
Project-URL: Issues, https://github.com/Astrognosy/reason-ecosystem/issues
|
|
11
|
+
Keywords: memory,agent,mcp,warf,reason,handoff,xchange,shared-context,ai-agents
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
23
|
+
Classifier: Operating System :: OS Independent
|
|
24
|
+
Requires-Python: >=3.9
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: requests>=2.25.0
|
|
28
|
+
Provides-Extra: gui
|
|
29
|
+
Requires-Dist: customtkinter>=5.2.0; extra == "gui"
|
|
30
|
+
Provides-Extra: mcp
|
|
31
|
+
Requires-Dist: mcp>=1.0.0; extra == "mcp"
|
|
32
|
+
Provides-Extra: dash
|
|
33
|
+
Requires-Dist: streamlit>=1.30.0; extra == "dash"
|
|
34
|
+
Requires-Dist: plotly>=5.0.0; extra == "dash"
|
|
35
|
+
Provides-Extra: full
|
|
36
|
+
Requires-Dist: customtkinter>=5.2.0; extra == "full"
|
|
37
|
+
Requires-Dist: mcp>=1.0.0; extra == "full"
|
|
38
|
+
Requires-Dist: streamlit>=1.30.0; extra == "full"
|
|
39
|
+
Requires-Dist: plotly>=5.0.0; extra == "full"
|
|
40
|
+
Provides-Extra: dev
|
|
41
|
+
Requires-Dist: pytest; extra == "dev"
|
|
42
|
+
Requires-Dist: pyinstaller; extra == "dev"
|
|
43
|
+
Requires-Dist: httpx; extra == "dev"
|
|
44
|
+
Requires-Dist: black; extra == "dev"
|
|
45
|
+
Requires-Dist: ruff; extra == "dev"
|
|
46
|
+
Dynamic: license-file
|
|
47
|
+
|
|
48
|
+
# reason-rdn — reason:// The Shared Memory Substrate for the Agentic Era
|
|
49
|
+
|
|
50
|
+
**Local-first coherent memory with seamless participation in the global reason:// network.**
|
|
51
|
+
|
|
52
|
+
One import. Persistent high-signal context for humans *and* agents. Safe local fingerprints. Real token savings. A beautiful dashboard. And a clean path to the public Xchange where the best artifacts rise to the top.
|
|
53
|
+
|
|
54
|
+
```powershell
|
|
55
|
+
pip install 'reason-rdn[full]' && rdn start
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Tell any agent: **"install reason-rdn[full] and run rdn start"**.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Why reason:// exists
|
|
63
|
+
|
|
64
|
+
Every serious agentic workflow eventually hits the same wall: agents are stateless. They re-invent, re-debug, and re-decide the same things over and over.
|
|
65
|
+
|
|
66
|
+
`reason://` gives you **addressable, high-signal memory**:
|
|
67
|
+
|
|
68
|
+
- Deposit once with a stable `reason://` address.
|
|
69
|
+
- Later (same agent, different agent, next month) resolve it and pick up where the best prior reasoning left off.
|
|
70
|
+
- Local by default. Federated when you want it. Public canonicals when the network promotes a winner.
|
|
71
|
+
|
|
72
|
+
This package (`rdn`) is the **open, production-grade on-ramp** — the delightful local layer + bridge that makes participating in (and benefiting from) the larger reason:// ecosystem trivial and rewarding.
|
|
73
|
+
|
|
74
|
+
The advanced mathematics (Positional Correlation Fields / PCF and quality promotion) stay protected in the reference engine. You only ever see safe, useful outputs.
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Hero Quick Start
|
|
79
|
+
|
|
80
|
+
### The one command everyone should run
|
|
81
|
+
|
|
82
|
+
```powershell
|
|
83
|
+
pip install 'reason-rdn[full]' && rdn start
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
This gives you immediately:
|
|
87
|
+
|
|
88
|
+
- The full **harness dashboard** (metrics, deposit, resolve, prefix explorer)
|
|
89
|
+
- Real **token savings, velocity, ship rate, vibe stars**
|
|
90
|
+
- Workflow suggestions
|
|
91
|
+
- Xchange controls (feed the collective when you want)
|
|
92
|
+
- Full `rdn` CLI + MCP tools for agents
|
|
93
|
+
|
|
94
|
+
### CLI examples
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
rdn remember "Fixed the critical auth race under load" --tags infra,auth,pcf
|
|
98
|
+
rdn recall "auth race"
|
|
99
|
+
rdn resolve "reason://infra/auth/race-detection"
|
|
100
|
+
rdn --xchange status # see your impact + the network
|
|
101
|
+
rdn list reason://infra # browse everything under a prefix
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### For agents (Claude, Grok, Cursor, etc.)
|
|
105
|
+
|
|
106
|
+
Agents get powerful tools automatically via MCP:
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
import rdn as reason
|
|
110
|
+
|
|
111
|
+
reason.remember(
|
|
112
|
+
"The canonical solution for this class of outage",
|
|
113
|
+
tags=["infra", "outage", "ecs"],
|
|
114
|
+
reason_address="reason://ops/ecs/failures" # permanent prefix is handled for you
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
art = reason.resolve("reason://ops/ecs/failures")
|
|
118
|
+
print(art)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Just say in your agent prompt: *"Use the reason-rdn MCP tools to remember and resolve via reason:// URIs."*
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Features
|
|
126
|
+
|
|
127
|
+
- **Beautiful Streamlit harness dashboard** — metrics that actually mean something, tree-view prefix explorer, recent URIs with one-click copy, deposit forms with permanent `reason://` prefix, Xchange toggle.
|
|
128
|
+
- **First-class CLI** (`rdn`) — remember, recall, resolve, list prefixes, status, xchange flows, start the harness.
|
|
129
|
+
- **MCP server** — agents get `remember`, `resolve`, `status`, harness metrics, etc. out of the box.
|
|
130
|
+
- **reason:// URIs + powerful browsing** — `list_prefix("reason://infra")` returns everything under it. The dashboard renders it as a beautiful collapsible tree.
|
|
131
|
+
- **Real token accounting** — pass `tokens_used` on remember and `tokens_saved` on resolve. See your personal velocity and savings from network winners.
|
|
132
|
+
- **Xchange mode** (opt-in) — high-signal artifacts you create can flow to the public broker, get scored by the protected engine, and (if they win) become the canonical for that `reason://` URI on the Xport registry.
|
|
133
|
+
- **Local private node always works** — 8765 by default. Full offline capability + SQLite mirror. The dashboard lives at 8501.
|
|
134
|
+
- **One coherent Python surface** — `import rdn as reason`. Everything important is available at the top level.
|
|
135
|
+
- **Simplified Windows one-stop** — `package.py` produces `rdn.exe` + portable zip (CLI + local node + tray). The rich dashboard is the reliable pip path.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Architecture (Public Reference Network)
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
Your code / CLI / Dashboard / Agents (MCP)
|
|
143
|
+
│
|
|
144
|
+
▼
|
|
145
|
+
Local private node (this package, port 8765)
|
|
146
|
+
• Always available
|
|
147
|
+
• Local SQLite fallback/mirror
|
|
148
|
+
• Safe structural fingerprints (_pcf)
|
|
149
|
+
│
|
|
150
|
+
│ (when Xchange enabled)
|
|
151
|
+
▼
|
|
152
|
+
Public Xchange Broker (warf.astrognosy.com)
|
|
153
|
+
│
|
|
154
|
+
│ service-to-service scoring
|
|
155
|
+
▼
|
|
156
|
+
astragnostic-api (api.pcfic.com) ← Protected PCF engine + Xtend promotion
|
|
157
|
+
│
|
|
158
|
+
│ (winners only)
|
|
159
|
+
▼
|
|
160
|
+
Xport / reason:// Registry (reason.astrognosy.com + xport.astrognosy.com)
|
|
161
|
+
│
|
|
162
|
+
└─► Public canonical resolution for any agent
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
**This repo = the open on-ramp.**
|
|
166
|
+
The heavy protected engine and promotion logic live in the reference network. Your high-quality local artifacts can compete there when you flip on Xchange.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## The reason:// URI
|
|
171
|
+
|
|
172
|
+
This is the killer feature.
|
|
173
|
+
|
|
174
|
+
```text
|
|
175
|
+
reason://<authority>/<path>
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Examples:
|
|
179
|
+
|
|
180
|
+
- `reason://ops/ecs/failures`
|
|
181
|
+
- `reason://infra/auth/race-detection`
|
|
182
|
+
- `reason://research/positional-correlation`
|
|
183
|
+
|
|
184
|
+
**Permanent prefix in the UI/CLI** — you never have to type `reason://` every time.
|
|
185
|
+
|
|
186
|
+
**Prefix browsing is first-class** — incomplete URIs bring back everything below them (both locally and from the network when Xchange is on). The dashboard shows a live tree with folders and copy buttons.
|
|
187
|
+
|
|
188
|
+
Once an artifact is promoted through Xchange + the quality gate, resolving the URI gives you the current best-known reasoning instead of forcing the agent to rediscover it.
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Token Economics & the Flywheel (IP-Safe)
|
|
193
|
+
|
|
194
|
+
When you use `tokens_used=...` on remember and see `tokens_saved=...` on resolve, you're seeing the flywheel in action:
|
|
195
|
+
|
|
196
|
+
1. You create a high-signal artifact and give it a precise `reason://` address.
|
|
197
|
+
2. You (optionally) share it via Xchange.
|
|
198
|
+
3. The network scores it. Strong artifacts get promoted.
|
|
199
|
+
4. Later, you or anyone else resolves the same URI and the system tells you how many tokens you *didn't* have to spend.
|
|
200
|
+
|
|
201
|
+
The dashboard surfaces **velocity**, **ship rate**, and **vibe stars** so the value is visible in seconds.
|
|
202
|
+
|
|
203
|
+
This is deliberately designed so that contributing high-quality memory is personally rewarding.
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Installation
|
|
208
|
+
|
|
209
|
+
### Recommended (cross-platform, full experience)
|
|
210
|
+
|
|
211
|
+
```powershell
|
|
212
|
+
pip install 'reason-rdn[full]'
|
|
213
|
+
rdn start
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
`[full]` pulls in the dashboard (streamlit + plotly) and MCP support.
|
|
217
|
+
|
|
218
|
+
### Windows "download and run" (simplified)
|
|
219
|
+
|
|
220
|
+
```powershell
|
|
221
|
+
python package.py
|
|
222
|
+
# produces dist/rdn.exe + rdn-portable.zip
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
The executable gives you the node + full CLI + system tray. For the rich metrics dashboard, use the pip path above.
|
|
226
|
+
|
|
227
|
+
### From source (development)
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
pip install -e '.[full]'
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
See `install.py` and `bootstrap.py` for one-liner bootstrap options.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Xchange & Configuration
|
|
238
|
+
|
|
239
|
+
Turn on participation in the public network:
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
REASON_USE_XCHANGE=1 rdn start
|
|
243
|
+
# or
|
|
244
|
+
rdn --xchange remember "..." --reason-address "reason://my-project/..."
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Key environment variables:
|
|
248
|
+
|
|
249
|
+
- `REASON_USE_XCHANGE=1` — default to the public warf broker
|
|
250
|
+
- `REASON_NODE_URL=...` — point at any node (local or remote)
|
|
251
|
+
- Token accounting is passed explicitly in the API (`tokens_used`, `tokens_saved`)
|
|
252
|
+
|
|
253
|
+
All data lives under `~/.reason-rdn/`.
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Toward IETF Standardization
|
|
258
|
+
|
|
259
|
+
We believe `reason://` addressing + structured high-signal memory artifacts are a missing primitive for the agentic internet.
|
|
260
|
+
|
|
261
|
+
Exploratory draft work lives in the [`ietf-drafts/`](./ietf-drafts) directory:
|
|
262
|
+
|
|
263
|
+
- `draft-reason-uri-00.md` — early skeleton for the URI scheme itself (syntax, semantics, resolution, security considerations, IANA registration path).
|
|
264
|
+
|
|
265
|
+
These are **not yet submitted** IETF drafts. They are public working notes so the direction is visible early and the community can help shape them.
|
|
266
|
+
|
|
267
|
+
If you're interested in URI schemes, provenance, or agent memory protocols, we would love your input.
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## Vision
|
|
272
|
+
|
|
273
|
+
Inference should feel like resolution when the problem has been solved well before.
|
|
274
|
+
|
|
275
|
+
`reason-rdn` + the reason:// network is how we get there — one high-quality, addressable artifact at a time.
|
|
276
|
+
|
|
277
|
+
Local-first and private by default.
|
|
278
|
+
Federated and public when you choose.
|
|
279
|
+
Protected mathematics where it matters.
|
|
280
|
+
Visible economics so humans and agents actually use it.
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
## Status & Roadmap
|
|
285
|
+
|
|
286
|
+
- ✅ Coherent top-level API (`import rdn as reason`)
|
|
287
|
+
- ✅ Real token accounting + HarnessMetrics (velocity, ship rate, vibe stars)
|
|
288
|
+
- ✅ Prefix browsing + tree explorer + recent URIs with copy
|
|
289
|
+
- ✅ Xchange bridge + public reference endpoints
|
|
290
|
+
- ✅ MCP server for agents
|
|
291
|
+
- ✅ Beautiful dashboard + polished CLI
|
|
292
|
+
- ✅ Simplified reliable Windows channel
|
|
293
|
+
- 🚀 IETF draft skeletons published (public branch)
|
|
294
|
+
- Ongoing: more flywheel-aware suggestions, richer provenance, broader agent integrations
|
|
295
|
+
|
|
296
|
+
**License:** MIT (see `LICENSE`)
|
|
297
|
+
|
|
298
|
+
This package is the open surface. The deeper non-invertible transfer protocols and full engine implementations live in the reference closed components.
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## Contributing
|
|
303
|
+
|
|
304
|
+
Issues and PRs are welcome on the public branch.
|
|
305
|
+
|
|
306
|
+
When opening issues, please include:
|
|
307
|
+
- `rdn --version`
|
|
308
|
+
- Whether you are using Xchange mode
|
|
309
|
+
- A minimal reproduction for bugs
|
|
310
|
+
|
|
311
|
+
For larger discussions about the URI scheme or protocol, the `ietf-drafts/` notes are the right place to start.
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
**The memory layer for the agentic web starts here.**
|
|
316
|
+
|
|
317
|
+
```powershell
|
|
318
|
+
pip install 'reason-rdn[full]' && rdn start
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
Then give your agents (and yourself) the superpower of actually remembering.
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
# reason-rdn — reason:// The Shared Memory Substrate for the Agentic Era
|
|
2
|
+
|
|
3
|
+
**Local-first coherent memory with seamless participation in the global reason:// network.**
|
|
4
|
+
|
|
5
|
+
One import. Persistent high-signal context for humans *and* agents. Safe local fingerprints. Real token savings. A beautiful dashboard. And a clean path to the public Xchange where the best artifacts rise to the top.
|
|
6
|
+
|
|
7
|
+
```powershell
|
|
8
|
+
pip install 'reason-rdn[full]' && rdn start
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Tell any agent: **"install reason-rdn[full] and run rdn start"**.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Why reason:// exists
|
|
16
|
+
|
|
17
|
+
Every serious agentic workflow eventually hits the same wall: agents are stateless. They re-invent, re-debug, and re-decide the same things over and over.
|
|
18
|
+
|
|
19
|
+
`reason://` gives you **addressable, high-signal memory**:
|
|
20
|
+
|
|
21
|
+
- Deposit once with a stable `reason://` address.
|
|
22
|
+
- Later (same agent, different agent, next month) resolve it and pick up where the best prior reasoning left off.
|
|
23
|
+
- Local by default. Federated when you want it. Public canonicals when the network promotes a winner.
|
|
24
|
+
|
|
25
|
+
This package (`rdn`) is the **open, production-grade on-ramp** — the delightful local layer + bridge that makes participating in (and benefiting from) the larger reason:// ecosystem trivial and rewarding.
|
|
26
|
+
|
|
27
|
+
The advanced mathematics (Positional Correlation Fields / PCF and quality promotion) stay protected in the reference engine. You only ever see safe, useful outputs.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Hero Quick Start
|
|
32
|
+
|
|
33
|
+
### The one command everyone should run
|
|
34
|
+
|
|
35
|
+
```powershell
|
|
36
|
+
pip install 'reason-rdn[full]' && rdn start
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
This gives you immediately:
|
|
40
|
+
|
|
41
|
+
- The full **harness dashboard** (metrics, deposit, resolve, prefix explorer)
|
|
42
|
+
- Real **token savings, velocity, ship rate, vibe stars**
|
|
43
|
+
- Workflow suggestions
|
|
44
|
+
- Xchange controls (feed the collective when you want)
|
|
45
|
+
- Full `rdn` CLI + MCP tools for agents
|
|
46
|
+
|
|
47
|
+
### CLI examples
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
rdn remember "Fixed the critical auth race under load" --tags infra,auth,pcf
|
|
51
|
+
rdn recall "auth race"
|
|
52
|
+
rdn resolve "reason://infra/auth/race-detection"
|
|
53
|
+
rdn --xchange status # see your impact + the network
|
|
54
|
+
rdn list reason://infra # browse everything under a prefix
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### For agents (Claude, Grok, Cursor, etc.)
|
|
58
|
+
|
|
59
|
+
Agents get powerful tools automatically via MCP:
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import rdn as reason
|
|
63
|
+
|
|
64
|
+
reason.remember(
|
|
65
|
+
"The canonical solution for this class of outage",
|
|
66
|
+
tags=["infra", "outage", "ecs"],
|
|
67
|
+
reason_address="reason://ops/ecs/failures" # permanent prefix is handled for you
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
art = reason.resolve("reason://ops/ecs/failures")
|
|
71
|
+
print(art)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Just say in your agent prompt: *"Use the reason-rdn MCP tools to remember and resolve via reason:// URIs."*
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Features
|
|
79
|
+
|
|
80
|
+
- **Beautiful Streamlit harness dashboard** — metrics that actually mean something, tree-view prefix explorer, recent URIs with one-click copy, deposit forms with permanent `reason://` prefix, Xchange toggle.
|
|
81
|
+
- **First-class CLI** (`rdn`) — remember, recall, resolve, list prefixes, status, xchange flows, start the harness.
|
|
82
|
+
- **MCP server** — agents get `remember`, `resolve`, `status`, harness metrics, etc. out of the box.
|
|
83
|
+
- **reason:// URIs + powerful browsing** — `list_prefix("reason://infra")` returns everything under it. The dashboard renders it as a beautiful collapsible tree.
|
|
84
|
+
- **Real token accounting** — pass `tokens_used` on remember and `tokens_saved` on resolve. See your personal velocity and savings from network winners.
|
|
85
|
+
- **Xchange mode** (opt-in) — high-signal artifacts you create can flow to the public broker, get scored by the protected engine, and (if they win) become the canonical for that `reason://` URI on the Xport registry.
|
|
86
|
+
- **Local private node always works** — 8765 by default. Full offline capability + SQLite mirror. The dashboard lives at 8501.
|
|
87
|
+
- **One coherent Python surface** — `import rdn as reason`. Everything important is available at the top level.
|
|
88
|
+
- **Simplified Windows one-stop** — `package.py` produces `rdn.exe` + portable zip (CLI + local node + tray). The rich dashboard is the reliable pip path.
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Architecture (Public Reference Network)
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
Your code / CLI / Dashboard / Agents (MCP)
|
|
96
|
+
│
|
|
97
|
+
▼
|
|
98
|
+
Local private node (this package, port 8765)
|
|
99
|
+
• Always available
|
|
100
|
+
• Local SQLite fallback/mirror
|
|
101
|
+
• Safe structural fingerprints (_pcf)
|
|
102
|
+
│
|
|
103
|
+
│ (when Xchange enabled)
|
|
104
|
+
▼
|
|
105
|
+
Public Xchange Broker (warf.astrognosy.com)
|
|
106
|
+
│
|
|
107
|
+
│ service-to-service scoring
|
|
108
|
+
▼
|
|
109
|
+
astragnostic-api (api.pcfic.com) ← Protected PCF engine + Xtend promotion
|
|
110
|
+
│
|
|
111
|
+
│ (winners only)
|
|
112
|
+
▼
|
|
113
|
+
Xport / reason:// Registry (reason.astrognosy.com + xport.astrognosy.com)
|
|
114
|
+
│
|
|
115
|
+
└─► Public canonical resolution for any agent
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
**This repo = the open on-ramp.**
|
|
119
|
+
The heavy protected engine and promotion logic live in the reference network. Your high-quality local artifacts can compete there when you flip on Xchange.
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## The reason:// URI
|
|
124
|
+
|
|
125
|
+
This is the killer feature.
|
|
126
|
+
|
|
127
|
+
```text
|
|
128
|
+
reason://<authority>/<path>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Examples:
|
|
132
|
+
|
|
133
|
+
- `reason://ops/ecs/failures`
|
|
134
|
+
- `reason://infra/auth/race-detection`
|
|
135
|
+
- `reason://research/positional-correlation`
|
|
136
|
+
|
|
137
|
+
**Permanent prefix in the UI/CLI** — you never have to type `reason://` every time.
|
|
138
|
+
|
|
139
|
+
**Prefix browsing is first-class** — incomplete URIs bring back everything below them (both locally and from the network when Xchange is on). The dashboard shows a live tree with folders and copy buttons.
|
|
140
|
+
|
|
141
|
+
Once an artifact is promoted through Xchange + the quality gate, resolving the URI gives you the current best-known reasoning instead of forcing the agent to rediscover it.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Token Economics & the Flywheel (IP-Safe)
|
|
146
|
+
|
|
147
|
+
When you use `tokens_used=...` on remember and see `tokens_saved=...` on resolve, you're seeing the flywheel in action:
|
|
148
|
+
|
|
149
|
+
1. You create a high-signal artifact and give it a precise `reason://` address.
|
|
150
|
+
2. You (optionally) share it via Xchange.
|
|
151
|
+
3. The network scores it. Strong artifacts get promoted.
|
|
152
|
+
4. Later, you or anyone else resolves the same URI and the system tells you how many tokens you *didn't* have to spend.
|
|
153
|
+
|
|
154
|
+
The dashboard surfaces **velocity**, **ship rate**, and **vibe stars** so the value is visible in seconds.
|
|
155
|
+
|
|
156
|
+
This is deliberately designed so that contributing high-quality memory is personally rewarding.
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Installation
|
|
161
|
+
|
|
162
|
+
### Recommended (cross-platform, full experience)
|
|
163
|
+
|
|
164
|
+
```powershell
|
|
165
|
+
pip install 'reason-rdn[full]'
|
|
166
|
+
rdn start
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
`[full]` pulls in the dashboard (streamlit + plotly) and MCP support.
|
|
170
|
+
|
|
171
|
+
### Windows "download and run" (simplified)
|
|
172
|
+
|
|
173
|
+
```powershell
|
|
174
|
+
python package.py
|
|
175
|
+
# produces dist/rdn.exe + rdn-portable.zip
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The executable gives you the node + full CLI + system tray. For the rich metrics dashboard, use the pip path above.
|
|
179
|
+
|
|
180
|
+
### From source (development)
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
pip install -e '.[full]'
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
See `install.py` and `bootstrap.py` for one-liner bootstrap options.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Xchange & Configuration
|
|
191
|
+
|
|
192
|
+
Turn on participation in the public network:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
REASON_USE_XCHANGE=1 rdn start
|
|
196
|
+
# or
|
|
197
|
+
rdn --xchange remember "..." --reason-address "reason://my-project/..."
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Key environment variables:
|
|
201
|
+
|
|
202
|
+
- `REASON_USE_XCHANGE=1` — default to the public warf broker
|
|
203
|
+
- `REASON_NODE_URL=...` — point at any node (local or remote)
|
|
204
|
+
- Token accounting is passed explicitly in the API (`tokens_used`, `tokens_saved`)
|
|
205
|
+
|
|
206
|
+
All data lives under `~/.reason-rdn/`.
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Toward IETF Standardization
|
|
211
|
+
|
|
212
|
+
We believe `reason://` addressing + structured high-signal memory artifacts are a missing primitive for the agentic internet.
|
|
213
|
+
|
|
214
|
+
Exploratory draft work lives in the [`ietf-drafts/`](./ietf-drafts) directory:
|
|
215
|
+
|
|
216
|
+
- `draft-reason-uri-00.md` — early skeleton for the URI scheme itself (syntax, semantics, resolution, security considerations, IANA registration path).
|
|
217
|
+
|
|
218
|
+
These are **not yet submitted** IETF drafts. They are public working notes so the direction is visible early and the community can help shape them.
|
|
219
|
+
|
|
220
|
+
If you're interested in URI schemes, provenance, or agent memory protocols, we would love your input.
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Vision
|
|
225
|
+
|
|
226
|
+
Inference should feel like resolution when the problem has been solved well before.
|
|
227
|
+
|
|
228
|
+
`reason-rdn` + the reason:// network is how we get there — one high-quality, addressable artifact at a time.
|
|
229
|
+
|
|
230
|
+
Local-first and private by default.
|
|
231
|
+
Federated and public when you choose.
|
|
232
|
+
Protected mathematics where it matters.
|
|
233
|
+
Visible economics so humans and agents actually use it.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Status & Roadmap
|
|
238
|
+
|
|
239
|
+
- ✅ Coherent top-level API (`import rdn as reason`)
|
|
240
|
+
- ✅ Real token accounting + HarnessMetrics (velocity, ship rate, vibe stars)
|
|
241
|
+
- ✅ Prefix browsing + tree explorer + recent URIs with copy
|
|
242
|
+
- ✅ Xchange bridge + public reference endpoints
|
|
243
|
+
- ✅ MCP server for agents
|
|
244
|
+
- ✅ Beautiful dashboard + polished CLI
|
|
245
|
+
- ✅ Simplified reliable Windows channel
|
|
246
|
+
- 🚀 IETF draft skeletons published (public branch)
|
|
247
|
+
- Ongoing: more flywheel-aware suggestions, richer provenance, broader agent integrations
|
|
248
|
+
|
|
249
|
+
**License:** MIT (see `LICENSE`)
|
|
250
|
+
|
|
251
|
+
This package is the open surface. The deeper non-invertible transfer protocols and full engine implementations live in the reference closed components.
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## Contributing
|
|
256
|
+
|
|
257
|
+
Issues and PRs are welcome on the public branch.
|
|
258
|
+
|
|
259
|
+
When opening issues, please include:
|
|
260
|
+
- `rdn --version`
|
|
261
|
+
- Whether you are using Xchange mode
|
|
262
|
+
- A minimal reproduction for bugs
|
|
263
|
+
|
|
264
|
+
For larger discussions about the URI scheme or protocol, the `ietf-drafts/` notes are the right place to start.
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
**The memory layer for the agentic web starts here.**
|
|
269
|
+
|
|
270
|
+
```powershell
|
|
271
|
+
pip install 'reason-rdn[full]' && rdn start
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Then give your agents (and yourself) the superpower of actually remembering.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "reason-rdn"
|
|
7
|
+
version = "0.4.0"
|
|
8
|
+
description = "ReasonRDN — the shared memory substrate for the agentic era. Local-first with seamless auto-deposit to the warf Xchange (https://warf.astrognosy.com). reason:// handoffs, protected structural fingerprints (PCF), unified client, embedded node, first-class MCP, and CLI."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = {text = "Apache-2.0"}
|
|
12
|
+
authors = [
|
|
13
|
+
{name = "Astrognosy", email = "info@astrognosy.com"}
|
|
14
|
+
]
|
|
15
|
+
keywords = ["memory", "agent", "mcp", "warf", "reason", "handoff", "xchange", "shared-context", "ai-agents"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"License :: OSI Approved :: Apache Software License",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.9",
|
|
22
|
+
"Programming Language :: Python :: 3.10",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
27
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
28
|
+
"Operating System :: OS Independent",
|
|
29
|
+
]
|
|
30
|
+
dependencies = [
|
|
31
|
+
"requests>=2.25.0",
|
|
32
|
+
]
|
|
33
|
+
[project.optional-dependencies]
|
|
34
|
+
gui = ["customtkinter>=5.2.0"]
|
|
35
|
+
mcp = ["mcp>=1.0.0"]
|
|
36
|
+
dash = ["streamlit>=1.30.0", "plotly>=5.0.0"]
|
|
37
|
+
full = ["customtkinter>=5.2.0", "mcp>=1.0.0", "streamlit>=1.30.0", "plotly>=5.0.0"]
|
|
38
|
+
dev = ["pytest", "pyinstaller", "httpx", "black", "ruff"]
|
|
39
|
+
|
|
40
|
+
[project.scripts]
|
|
41
|
+
rdn = "rdn.cli:main"
|
|
42
|
+
rdn-sync = "rdn.handoff.sync:main"
|
|
43
|
+
rdn-node = "rdn.node.server:main"
|
|
44
|
+
rdn-mcp = "rdn.mcp.server:main"
|
|
45
|
+
rdn-dash = "rdn.dash:launch"
|
|
46
|
+
|
|
47
|
+
[project.urls]
|
|
48
|
+
Homepage = "https://github.com/Astrognosy/reason-ecosystem"
|
|
49
|
+
Documentation = "https://github.com/Astrognosy/reason-ecosystem#readme"
|
|
50
|
+
Repository = "https://github.com/Astrognosy/reason-ecosystem"
|
|
51
|
+
Issues = "https://github.com/Astrognosy/reason-ecosystem/issues"
|
|
52
|
+
|
|
53
|
+
[tool.setuptools.packages.find]
|
|
54
|
+
where = ["."]
|
|
55
|
+
include = ["rdn*"]
|
|
56
|
+
exclude = ["legacy-operator*", "tests*"]
|
|
57
|
+
|
|
58
|
+
[tool.setuptools.package-data]
|
|
59
|
+
rdn = ["*.md"]
|
|
60
|
+
|
|
61
|
+
[tool.ruff]
|
|
62
|
+
line-length = 100
|
|
63
|
+
target-version = "py39"
|
|
64
|
+
|
|
65
|
+
[tool.pytest.ini_options]
|
|
66
|
+
testpaths = ["tests"]
|
|
67
|
+
python_files = ["test_*.py"]
|
|
68
|
+
addopts = "-q --tb=short"
|