simplicio-prompt 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Wesley Simplicio. All rights reserved.
+
+This software and its documentation (the "Work") are proprietary and
+confidential. The Work is provided for internal use only by Wesley
+Simplicio and explicitly authorized collaborators.
+
+No part of the Work may be reproduced, distributed, transmitted, modified,
+or used in derivative works, in whole or in part, without prior written
+permission from the copyright holder.
+
+THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM USE OF THE WORK.

package/README.md

@@ -0,0 +1,173 @@
+# simplicio-prompt
+
+![simplicio-prompt — AI with 1,000,000+ subagents](docs/assets/simplicio-prompt-hero.png)
+
+> Capability-addressing pattern: **yool** (atomic action) wrapped in **tuples** (addressable envelopes) over an **HAMT** (Hash Array Mapped Trie) registry, coordinated through a **tuple-space** with **content-addressable receipts**.
+
+This repo is the canonical spec. Vendor it into any project that wants the pattern.
+
+## V2 safe-speed infographics
+
+### English
+![YOOL V2 Safe-Speed Runtime infographic in English](docs/assets/yool-v2-safe-speed-infographic-en.png)
+
+### Portuguese Brazil
+![Infografico YOOL V2 Safe-Speed Runtime em portugues](docs/assets/yool-v2-safe-speed-infographic-pt.png)
+
+### Texto de explicacao do infografico
+
+The infographics compare a loose prompt flow against the `simplicio-prompt` V2
+safe-speed runtime. The left side shows the old failure modes: flat agent lists,
+sequential work, repeated provider calls, no cache, fixed concurrency, retry
+storms, large LLM context, and weak audit trails.
+
+The right side shows the V2 path: tuple-space routing, lazy `batch_spawn`,
+adaptive `LaneWorkerPool`, receipt/input cache, small-task batching, circuit
+breakers, backoff with jitter, context compression, local yool routing, and
+speculative execution only for idempotent work. The practical result is faster
+delivery through avoided repeat work and safer provider behavior, not through
+unbounded calls.
+
+Measured V2 benchmark highlights:
+
+- Scale representation: `2,833.75x` faster than a normal instruction flow.
+- Active execution: `26.93x` faster than normal sequential execution.
+- Cache: `4x` fewer provider calls, a `75%` reduction.
+- Batching: `32x` fewer small-task calls, a `96.88%` reduction.
+- Circuit breaker: `64x` fewer failure attempts, a `98.44%` reduction.
+- Token economy: `76.32%` estimated savings through context compression.
+
+## Quick read
+
+- `YOOL_TUPLE_HAMT.md` — full spec with diagrams, algorithms, examples, guardrails.
+- `kernel/yool_tuple_kernel.py` — reference Python kernel with lazy `batch_spawn`,
+  `compress_token`, hookwall, indexed tuple-space scans, and lane worker fan-out.
+- `prompts/agent-runtime-execution-prompt.md` — ready prompt for Claude, Codex,
+  Hermes, and other coding agents.
+- `examples/` — runnable minimal implementations (Python, Node).
+- `guardrails/` — CPU throttle + disk GC reference implementations.
+- `adopters.md` — projects that vendor this spec.
+
+## How to use the prompt
+
+Use `simplicio-prompt` as a canonical execution prompt for coding agents such as
+Claude, Codex, Hermes, Cursor, Cline, or any assistant that can read repository
+instructions.
+
+1. Open [`prompts/agent-runtime-execution-prompt.md`](prompts/agent-runtime-execution-prompt.md).
+2. Copy the full `## Prompt` section into the target agent instructions. Good
+   places are `AGENTS.md`, `CLAUDE.md`, a custom system prompt, or the first
+   message of a new implementation session.
+3. In the target repository, ask for work using a direct instruction such as
+   `Implement X`, `Fix X`, or `Build X`.
+4. The agent should read the canonical files listed in the prompt, decompose the
+   task into a Hilbert-indexed tuple graph, create a root tuple, route active
+   work through tuple-space primitives, and use `LaneWorkerPool` plus the V2
+   safe-speed controls.
+5. Keep the output shape stable so progress is easy to audit:
+
+```text
+[Tuple Space Snapshot]
+[Active Agents/Subagents]
+[Total Agents/Subagents]
+[Proximo Yool a executar]
+[Resultado parcial]
+```
+
+For high-throughput local runs, set the runtime environment variables before
+starting the agent or scripts:
+
+```powershell
+$env:YOOL_TUPLE_LANE_CONCURRENCY="32"
+$env:YOOL_TUPLE_MAX_LANE_CONCURRENCY="64"
+$env:YOOL_TUPLE_CPU_QUOTA_PCT="95"
+$env:YOOL_TUPLE_QUEUE_MAXSIZE="8192"
+$env:YOOL_TUPLE_COMPRESSION_THRESHOLD="1024"
+$env:YOOL_TUPLE_CACHE_MAX_ENTRIES="16384"
+$env:YOOL_TUPLE_CACHE_TTL_S="3600"
+$env:YOOL_TUPLE_API_MAX_RETRIES="3"
+$env:YOOL_TUPLE_API_BACKOFF_BASE_MS="100"
+$env:YOOL_TUPLE_API_BACKOFF_MAX_MS="5000"
+$env:YOOL_TUPLE_CIRCUIT_FAILURE_THRESHOLD="5"
+$env:YOOL_TUPLE_CIRCUIT_COOLDOWN_S="30"
+$env:YOOL_TUPLE_BATCH_SMALL_TASK_SIZE="32"
+$env:YOOL_TUPLE_CONTEXT_COMPRESSION_CHARS="6000"
+```
+
+Run the reference kernel and tests:
+
+```bash
+python kernel/yool_tuple_kernel.py
+python -m unittest discover -s tests -p "test_*.py"
+```
+
+## V2 benchmark report
+
+The V2 report is the main evidence for the safe-speed runtime. Read it before
+adopting the prompt in another project:
+
+- [V2 Markdown report](benchmarks/v2_safe_speed_results.md)
+- [V2 PDF report](benchmarks/v2_safe_speed_benchmark.pdf)
+- [V2 benchmark script](benchmarks/v2_safe_speed_benchmark.py)
+- [V2 PDF generator](benchmarks/generate_v2_benchmark_pdf.py)
+
+What the V2 report shows:
+
+- `2,833.75x` faster scale representation than normal instruction flow.
+- `26.93x` faster active execution than normal sequential execution.
+- `4x` fewer repeated provider calls through receipt/input cache.
+- `32x` fewer small-task calls through batching.
+- `64x` fewer provider failure attempts through circuit breakers.
+- `76.32%` estimated token savings through context compression.
+
+The key point: V2 speeds up by avoiding repeated work and controlling provider
+pressure. It does not depend on unsafe infinite calls, unbounded concurrency, or
+retry storms.
+
+## High-throughput runtime defaults
+
+The reference kernel is tuned for speed while keeping host guardrails explicit:
+
+| Env var | Default | Purpose |
+|---|---:|---|
+| `YOOL_TUPLE_LANE_CONCURRENCY` / `YOOL_LANE_CONCURRENCY` | `32` | Preferred workers per lane. |
+| `YOOL_TUPLE_MAX_LANE_CONCURRENCY` / `YOOL_MAX_LANE_CONCURRENCY` | `64` | Ceiling for workers per lane. |
+| `YOOL_TUPLE_CPU_QUOTA_PCT` / `YOOL_CPU_QUOTA_PCT` | `95` | Default per-yool CPU budget. |
+| `YOOL_TUPLE_QUEUE_MAXSIZE` / `YOOL_QUEUE_MAXSIZE` | `8192` | Lane queue scan cap. |
+| `YOOL_TUPLE_COMPRESSION_THRESHOLD` / `YOOL_COMPRESSION_THRESHOLD` | `1024` | Active materialized agents before pruning. |
+| `YOOL_TUPLE_CACHE_MAX_ENTRIES` / `YOOL_CACHE_MAX_ENTRIES` | `16384` | Receipt/input-hash cache size. |
+| `YOOL_TUPLE_CACHE_TTL_S` / `YOOL_CACHE_TTL_S` | `3600` | Cache TTL in seconds. |
+| `YOOL_TUPLE_API_MAX_RETRIES` / `YOOL_API_MAX_RETRIES` | `3` | Retry budget for transient API/LLM failures. |
+| `YOOL_TUPLE_API_BACKOFF_BASE_MS` / `YOOL_API_BACKOFF_BASE_MS` | `100` | Initial jittered backoff delay. |
+| `YOOL_TUPLE_API_BACKOFF_MAX_MS` / `YOOL_API_BACKOFF_MAX_MS` | `5000` | Backoff ceiling. |
+| `YOOL_TUPLE_CIRCUIT_FAILURE_THRESHOLD` / `YOOL_CIRCUIT_FAILURE_THRESHOLD` | `5` | Failures before opening provider breaker. |
+| `YOOL_TUPLE_CIRCUIT_COOLDOWN_S` / `YOOL_CIRCUIT_COOLDOWN_S` | `30` | Provider cooldown after breaker opens. |
+| `YOOL_TUPLE_BATCH_SMALL_TASK_SIZE` / `YOOL_BATCH_SMALL_TASK_SIZE` | `32` | Default small-task batch size. |
+| `YOOL_TUPLE_CONTEXT_COMPRESSION_CHARS` / `YOOL_CONTEXT_COMPRESSION_CHARS` | `6000` | Large LLM context compression threshold. |
+
+Safe speedups now live in the kernel, not only in the prompt: receipt/input
+cache, adaptive lane concurrency, jittered backoff, provider circuit breakers,
+small-task batching, prompt/context compression, local yool routing, and
+speculative execution only for tuples marked `idempotent=True`.
+
+Run the reference kernel and tests:
+
+```bash
+python kernel/yool_tuple_kernel.py
+python -m unittest discover -s tests -p "test_*.py"
+```
+
+Benchmark reports:
+
+- [Prompt vs normal Markdown](benchmarks/prompt_vs_normal_results.md)
+- [Prompt vs normal PDF](benchmarks/prompt_vs_normal_benchmark.pdf)
+- [V2 safe-speed Markdown](benchmarks/v2_safe_speed_results.md)
+- [V2 safe-speed PDF](benchmarks/v2_safe_speed_benchmark.pdf)
+
+## Why a separate repo
+
+The pattern is cross-project. SendSprint, llm-project-mapper, future agents — all consume the same spec. One source of truth, vendored on demand.
+
+## License
+
+Private. Internal use only.