piensalo 0.1.0a5

A cognitive operating layer for AI models: bounded loops, observable-defect inspection, targeted repair, and layered verification.

PIÉNSALO

Give any AI a better way to think.

The open artificial cortex for AI. Use less context. Lose none of the intelligence.

PIÉNSALO selects the smallest context required for the current task, runs the AI model you choose, verifies whether the response still satisfies the task, expands the context when information is missing, and safely falls back to full context when optimization would be unsafe.

Created by Rafael “Ralph” Peña. Piénsalo — "think it through." Pronounced: pee-EN-sa-lo.

Status: public alpha. Tested runtime, packaging, and evaluation harness. Live experimental evidence is from one Claude-family model; independent replication and cross-model validation are pending — in public.

What PIÉNSALO does

One cortex, three systems, all model-independent and offline-first:

• CONTEXT — cut context tokens, verify the answer, expand when needed, fall back safely. (The sharpest wedge — start here.)
• THINK — compile a hard task into a bounded cognitive program before any model runs.
• CHECK — inspect a draft for observable defects, repair only what is demonstrably wrong, verify what can honestly be verified, and abstain when intervention would cause harm.

Measured, not promised

Initial preregistered evaluation — 8 paired full-context vs optimized-context tasks, graders frozen before any model run (evals/context-optimizer/, results committed):

Median context reduction:          80.2%
Median runtime net input savings:  76.9%
Optimizable tasks maintained:      7/7
Deterministic regressions:         0
Unsafe compression cases:          1 (by design)
Correct safe fallbacks:            1/1

Scope of that claim, stated plainly: one Claude-family model (claude-haiku-4-5-20251001) · eight preregistered tasks · single samples · deterministic task requirements (output contract + exact-content oracle) · broader behavioral equivalence remains unmeasured. A smaller prompt is not automatically a better one — that is why verification and fallback exist.

Install

# Fastest first run (no install)
uvx piensalo doctor

# Persistent install
pipx install piensalo

# Straight from GitHub
uvx --from git+https://github.com/ralfyishere/piensalo piensalo doctor

doctor verifies your environment and confirms the core runs fully offline — no telemetry, no network, nothing leaves your machine. Python ≥ 3.10; tested in CI on Linux and macOS, Python 3.10–3.13 (Windows unsupported for now).

Development clone and portable Agent Skills

# From a clone (development)
git clone https://github.com/ralfyishere/piensalo.git && cd piensalo
uv sync && uv run piensalo doctor

# Portable Agent Skills only (no runtime needed)
npx skills add ralfyishere/piensalo

The 60-second Context Optimizer demo

git clone https://github.com/ralfyishere/piensalo.git && cd piensalo
./examples/context-optimizer/launch-demo.sh

Offline, no API key: it optimizes a real chatter-heavy engineering context live (deterministic, reproduced on your machine), shows exactly what was kept and omitted and why, then replays the committed recorded model comparison — full context vs optimized context, same task, same grader — ending in a MAINTAINED verdict at a fraction of the tokens, plus the designed unsafe case being refused instead of truncated. Every line is labeled as live-deterministic or recorded; the full captured output is committed at examples/context-optimizer/LAUNCH-TRANSCRIPT.md and an anti-drift test fails CI if the script and transcript ever diverge.

How optimization works

TASK
  → FULL AVAILABLE CONTEXT      (text, JSONL, chat JSON, tool logs, files)
  → CHUNK + CLASSIFY            (explicit structure honored exactly once)
  → PRESERVE MANDATORY CONTEXT  (constraints, exact ids, stop conditions …)
  → RANK OPTIONAL CONTEXT       (inspectable per-chunk score, never opaque)
  → BUILD BUDGETED PACKET       (over-budget mandatory ⇒ REFUSED, not cut)
  → RUN THE TARGET MODEL        (explicit adapter only; provenance pinned)
  → VERIFY THE RESPONSE         (contract + exact-content oracle)
  → ACCEPT, EXPAND, OR FALL BACK

Every chunk gets a disposition with a reason in selection-manifest.json — INCLUDED_MANDATORY, INCLUDED_RELEVANT, OMITTED_DUPLICATE, OMITTED_SUPERSEDED, OMITTED_LOW_RELEVANCE, OMITTED_REGENERABLE, REFERENCED_NOT_INLINE, REQUIRES_EXPANSION — so you can audit exactly why anything was kept or left out. Context needed to fix CI is not the context needed to write launch copy: packets are compiled per task, not per project.

Safe expansion and fallback

Verification failure is never silently returned as success:

1. optimized attempt → deterministic verification
2. failed? add the highest-value omitted chunks (bounded, default 2 rounds, every added chunk recorded)
3. still failing? SAFE FALLBACK — run or recommend the full context, ledgered as a fallback, never counted as an optimized win
4. mandatory context alone over budget? OPTIMIZATION REFUSED — FULL CONTEXT REQUIRED. Critical information is never truncated.

The token ledger separates source, optimized, expansion, fallback, and benchmark-only baseline costs — compression that costs more than it saves is reported as exactly that.

THINK — structure difficult work

piensalo think compiles a task (file or inline text) into a bounded cognitive program before any model runs; piensalo loop keeps long-running work resumable with model provenance; piensalo skill manages 27 portable skill packages (skills/ + micro-skills/) that install into any agent speaking Agent Skills.

CHECK — inspect, repair, verify, abstain

TASK → DRAFT → INSPECT → ABSTAIN or TARGETED REPAIR → VERIFY → FINAL ARTIFACT

• inspect detects observable defects with evidence lines — never vibes.
• repair has two honest modes: offline (emit the packet) or adapter-backed (--adapter claude-cli|openai|ollama|manual, --model, --output) — original draft preserved, provenance recorded, result re-inspected.
• verify reports in five strict buckets — DETERMINISTICALLY VERIFIED, CONTRACT VERIFIED, MODEL-ASSISTED CHECK, UNMEASURED, FAILED — and UNMEASURED never counts as a pass.
• Silent model fallback is prohibited by design: adapters record requested and resolved model and stop on mismatch.

60 seconds of CHECK, for real

Every line below is real output from the shipped CLI — the transcript is committed at examples/flagship/TRANSCRIPT.md and a CI test re-runs the demo and fails if this ever drifts.

A quote task applies two sequential discounts (20%, then 15%). The AI draft added them (35% off → $221.00) instead of compounding (→ $231.20):

$ piensalo inspect --task examples/flagship/task.md \
    --draft examples/flagship/draft-broken.md \
    --contract examples/flagship/contract.json
selected repair(s): rederive-the-numbers
  evidence: asserts a figure with no visible derivation on a multi-rate task

$ piensalo verify --task examples/flagship/task.md \
    --draft examples/flagship/draft-broken.md \
    --contract examples/flagship/contract.json
FAILED
  QUOTE_USD: 221.00 != expected 231.20
[exit: 1]

piensalo repair then emits a repair packet — the complete, ready-to-run prompt for your model, honestly labeled: "instructions for a model; nothing has been applied." (With --adapter, it runs the packet through a model you explicitly choose, writes the repaired draft to a new file with a provenance sidecar, and re-inspects the result — it never claims success just because a model returned text.)

And on a draft that is already right:

$ piensalo inspect --task examples/flagship/task.md \
    --draft examples/flagship/draft-correct.md \
    --contract examples/flagship/contract.json
NO REPAIR NEEDED — no observable defect cleared the activation threshold.

$ piensalo verify --task examples/flagship/task.md \
    --draft examples/flagship/draft-correct.md \
    --contract examples/flagship/contract.json
DETERMINISTICALLY VERIFIED
  QUOTE_USD: 231.20 == expected
CONTRACT VERIFIED
UNMEASURED
  cognition: UNMEASURED (no verifier configured — this is not a pass)

Run the whole thing yourself: bash examples/flagship/demo.sh

CONTEXT — the full command surface

# offline + deterministic: capsule / packet construction
piensalo context compile transcript.txt --goal "continue" --budget 3000 --output out/
piensalo context optimize --task task.md --context session.jsonl --budget 4000 --output opt/

# inspect / verify / diff what was compiled
piensalo context inspect out/
piensalo context verify out/
piensalo context diff out-v1/ out-v2/

# explicit-adapter execution with verification, bounded expansion, safe fallback
piensalo context run --task task.md --context session.jsonl --budget 4000 \
  --adapter claude-cli --model <model> --contract contract.json --output run/

# paired full-vs-optimized evidence run (benchmark cost ledgered separately)
piensalo context evaluate --task task.md --context session.jsonl \
  --adapter claude-cli --model <model> --budgets 2000,4000 --output eval/

compile turns long transcripts into deterministic Continuation Capsules: typed consequence records, active vs superseded decisions, exactness classes, content-addressed source references, byte-stable serialization, honest budget refusal — and behavioral equivalence reported UNMEASURED, because structural verification does not prove a resumed model behaves identically. Deterministic capsule demo: examples/context/.

Cortex Gateway — observe mode (new in 0.1.0-alpha.5)

PIÉNSALO can sit between the AI tools you already use and the model you choose. The first delivery mode is observe: it forwards your traffic unchanged, runs the Cortex Router in shadow to record what THINK, CHECK, or CONTEXT would do, and writes a local, redact-by-default event ledger. It does not modify responses and makes no performance claim — it is a pass-through + measurement surface.

# in front of any OpenAI-compatible upstream (local model, LM Studio, Ollama, OpenRouter, …)
piensalo serve --mode observe \
  --upstream-base-url http://127.0.0.1:11434/v1 --upstream-model <id>

# what would the cortex have done? (shadow only — nothing was intervened on)
piensalo gateway report
piensalo gateway inspect --last 20

Loopback-only by default, SSRF-guarded upstream, bearer-auth optional, no body retention. Try it with zero credentials via the offline demo: examples/gateway/ · design: docs/gateway/ARCHITECTURE.md. Intervention modes (optimize-safe, verified) are DESIGNED, not yet implemented.

Evidence and limitations

Every capability ships with receipts. Two pre-registered 120-cell controlled runs sit behind the CHECK defaults — including the finding that forced repair on already-correct drafts damages delivery ~29% of the time while never corrupting cognition. That is why abstention is the default posture. The Context Optimizer numbers above come from one pre-registered paired run with committed artifacts.

• EVIDENCE.md — mechanism records with maturity levels (DESIGNED → … → PROMOTED, with NARROW and REJECTED as honest terminal states; nothing is PROMOTED yet)
• BENCHMARKS.md — run designs and numbers, confounds attached
• NEGATIVE-RESULTS.md — the failures we keep public on purpose
• Reproduce: make benchmark (no API key needed) · full harness in evals/
• Current limits, honestly: one model family live-tested (Claude); n = 8 tasks per run; single samples; OpenAI-compatible/Ollama adapters are unit-tested with live validation pending; no independent reproduction yet. Help change that: docs/alpha/SUBMIT-RESULTS.md.

Security

Offline by default; no telemetry; no shell execution from untrusted skill text; skill packages scannable with piensalo skill scan. Threat model: docs/THREAT-MODEL.md. Sensitive reports: GitHub Private Vulnerability Reporting (SECURITY.md).

Contributing

Real-task results are the most valuable contribution — all outcomes, including "it correctly did nothing", "it fell back correctly", and "it invented a problem". File one in two minutes with the real task result form; installation trouble goes in the installation form. Details: docs/alpha/SUBMIT-RESULTS.md. Code, skills, verifiers, adapters: CONTRIBUTING.md — every contribution meets the same evidence and security bar. Principles: MANIFESTO.md.

Creator

PIÉNSALO was created by Rafael “Ralph” Peña.

It began as an attempt to preserve and transfer powerful AI problem-solving behavior. The experiments showed that larger prompts alone were not enough: some interventions helped, while others overloaded weaker models, damaged correct delivery, routed incorrectly, or created false confidence. Watching agents re-spend enormous context on history they no longer needed led to the Context Optimizer: not another summarizer, but a system that removes context, tests the resulting answer, restores information when needed, and refuses optimization when it could cause harm.

PIÉNSALO was built from the mechanisms that survived the evidence — the full story is in docs/origin-story.md.

Think through hard work. Verify what matters. Know when to stop.

Piénsalo is an independent open-source project. It is not affiliated with or endorsed by Anthropic.