diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c36d9bf --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,150 @@ +# CLAUDE.md — PCNA Codebase Guide + +## Project Overview + +PCNA (Prime Circular Neural Architecture) is a deterministic, prime-indexed circular graph system for modular compute and real-time diagnostics. It has two distinct layers: + +- **core/** — the inference engine: six rings of prime-indexed tensor nodes running heptagram propagation, coherence scoring, and EDCM diagnostics +- **backend/** — a FastAPI server that hosts seeds, integrates an LLM orchestrator, and exposes REST/WebSocket APIs + +The canonical upstream is `The-Interdependency/a0`. Features are ported from there and adapted. Development happens on `claude/update-from-interdependency-a0-*` branches; PRs go to `main`. + +--- + +## Repository Layout + +``` +core/ Engine modules (no FastAPI, no DB) +backend/ Server, LLM, optimization, SMS, Moltbook, outreach +frontend/src/ React dashboard (5 components) +tests/ pytest — no pytest-asyncio; use asyncio.run() for async tests +schemas/ JSON schemas +main.py Seed runner entry point +conftest.py sys.path insert — keeps pytest imports working +requirements.txt +``` + +--- + +## Core Modules — What Each Does + +### `core/ptca_core.py` — `PTCACore` +Base class for all prime-ring tensors. Tensor shape: `[N, DIMS=4, PHASES=7, HEPT_SITES=7]`. Heptagram propagation via Euler steps (DT=0.01). Coherence = `1 - |ring - hub|_mean`. Used by Φ, Ψ, Ω, and Σ. + +Key: `_adj_distances(n)` uses `math.ceil(n/4)` to get gap=14 for n=53 (spec-correct). Keep `import math` — it's used here. + +### `core/theta.py` — `ThetaTensor` +N=29 microkernel gate. Ragged circle counts per node (1–12), SHA-256 blueprint sharding, gate control via `GATE_THRESHOLD=0.45`. Not a PTCACore subclass — standalone. Neighbors hardcoded to `±1, ±7 mod 29`. Imported as `from .theta import ThetaTensor`. + +### `core/sigma.py` — `SigmaRing` / `get_sigma()` +N=41 filesystem observer wrapping PTCACore. Tracks watched file mtimes, drains change events on `content_interval` cadence. Singleton via `get_sigma()`. In `core/pcna.py`, sigma import and use are wrapped in a broad `except Exception: pass` (silent). In `core/zeta.py`, the import is caught with `except ImportError` (silent return) and runtime errors with `except Exception` (logged). Treat sigma as optional — callers degrade gracefully if it raises. + +### `core/memory_core.py` — `MemoryCore` +Parameterized long-term (N=19, seed=19) and short-term (N=17, seed=17) memory rings. Round-robin write, content-addressed query, `flush_to()` transfers short→long on positive reward. + +### `core/pcna.py` — `PCNAEngine` +Six-ring inference engine. Key attributes: `self.phi`, `self.psi`, `self.omega`, `self.theta`, `self.memory_l`, `self.memory_s`. `RING_WEIGHTS` defines the **scored** ring set: `{phi, psi, omega, theta, memory_l, memory_s}`. `state()["rings"]` also includes `sigma` (optional observer, not scored). These two dicts are not required to be identical — only the scored rings need entries in `RING_WEIGHTS`. Checkpoints go in `.checkpoints/pcna_checkpoint.npz`. + +### `core/edcm.py` +Six-family metrics (cm, da, drift, dvg, int_val, tbf) with `ALERT_HIGH=0.80`, `ALERT_LOW=0.20`. `DIRECTIVES` dict uses canonical names: `CONSTRAINT_REFOCUS`, `DISSONANCE_HALT`, `DRIFT_ANCHOR`, `DIVERGENCE_COMMIT`, `INTENSITY_CALM`, `BALANCE_CONCISE`. `check_directives()` returns a list of fired directive names. + +### `core/zeta.py` — `ZetaEngine` +ZFAE: evaluates every assistant response via EDCM, nudges PCNAEngine.phi. Coherence formula: `cm*0.35 + da*0.25 + int_val*0.25 + (1-drift)*0.15`. Per-directory resolution (1–5) via prefix matching. Module-level singleton `_zeta_engine`. `_sigma_nudge_factors()` silently swallows `ImportError`; logs other exceptions. + +### `core/merge.py` — `InstanceMerge` +Static methods: `absorb`, `fork`, `converge`. All output dicts use `theta_*` keys (not `guardian_*`). Federated averaging via `_fed_avg(a, b, alpha)`. + +### `backend/edcm_engine.py` — `EDCMAnalyzer` +Derives EDCM metrics from `seed_states` dicts (require `health_score`, `mass`, `role` keys). Fires directives, generates insights/recommendations, assigns `monetization_value`. Async `analyze()` — call with `asyncio.run()` in tests. + +--- + +## Key Invariants + +**`RING_WEIGHTS` defines the scored ring set.** `RING_WEIGHTS` in `pcna.py` must match the keys used in `_coherence_score()` — currently `{phi, psi, omega, theta, memory_l, memory_s}`. `state()["rings"]` may include additional non-scored rings (currently `sigma`). If you add a scored ring, update `RING_WEIGHTS` and `_coherence_score`. If you add a non-scored/observer ring, add it only to `state()["rings"]`, not to `RING_WEIGHTS`. + +**No `guardian` key anywhere.** The ring was renamed from `guardian` to `theta`. If you see `guardian` as a dict key or attribute (outside docstring prose), it's a bug. + +**EDCM directive names are canonical.** Always `CONSTRAINT_REFOCUS`, `DISSONANCE_HALT`, `DRIFT_ANCHOR`, `DIVERGENCE_COMMIT`, `INTENSITY_CALM`, `BALANCE_CONCISE`. No internal abbreviations. + +**`ALERT_HIGH` and `ALERT_LOW` before `DIRECTIVES`.** In `core/edcm.py`, constants must be defined before the `DIRECTIVES` dict that references them. + +**No `pytest-asyncio`.** Tests use `asyncio.run()` directly. Do not add `@pytest.mark.asyncio`. + +**No `sys.path.insert` in source files.** `conftest.py` handles the path. Don't add it to individual modules. + +--- + +## Import Paths + +Tests and backend modules import from the package root: +```python +from core.edcm import compute_metrics, check_alerts, check_directives +from backend.edcm_engine import EDCMAnalyzer +from core.pcna import PCNAEngine +``` + +The root `main.py` uses `from core.topology import ...` — correct. +`core/main.py` uses `from src.core.*` — broken, do not use. + +--- + +## CI + +GitHub Actions runs a single `build` job on every push with two steps: + +1. **flake8** — `--select=E9,F63,F7,F82` (syntax errors, undefined names). Must pass clean. +2. **pytest** — all `test_*.py` and `tests_*.py` in `tests/`. Must pass. + +Common CI failures seen: +- Backslash-escaped triple quotes in f-strings → E999 SyntaxError +- Unused `global` declarations → F824 +- Wrong import paths (e.g. `from src.core.*`) → ModuleNotFoundError +- Missing `asyncio.run()` / leftover `@pytest.mark.asyncio` decorator + +--- + +## Known Stubs (not yet implemented) + +| File | What's missing | +|------|---------------| +| `core/routing_loop.py` | Only a print stub — `GlobalRouterZero` not implemented | +| `backend/moltbook_integration.py` | 100% mock data; all methods are TODOs | +| `backend/sms_service.py` | Twilio integration commented out; mock mode only | +| `backend/researcher_outreach.py` | `send_outreach()` is a stub; message generation works | + +--- + +## Known Issues + +- `core/memory_core.py`: `query()` is defined but never called anywhere +- `core/helix_vis.py`: saves to hardcoded `pcna_helix.gif`; no config +- `core/sigma.py`: `structural_interval` is stored but never acted on +- `core/merge.py`: `fork()` time-seeds its RNG — rapid calls may collide +- `backend/server.py`: MongoDB connection failure is not handled gracefully; seed roles are hardcoded in initialization (not topology-driven) +- `requirements.txt`: missing `motor`, `python-dotenv`, `emergentintegrations`, `scipy`, `matplotlib` + +--- + +## Adding a New Ring + +1. Create `core/.py` — implement the ring class with `tensor`, `ring_coherence`, `node_coherence`, `nudge()`, `state()` interface +2. Add it to `PCNAEngine.__init__()` as `self.` +3. Add it to `state()["rings"]` under the same key +4. **If scored:** add the weight to `RING_WEIGHTS` and add the key to `_coherence_score()`'s `ring_scores` dict +5. **If observer/optional:** skip `RING_WEIGHTS`; wrap access in `try/except` in `_inject()` and `reward()` +6. Add checkpoint save/load in `save_checkpoint()` / `load_checkpoint()` (scored rings only) + +--- + +## Working with EDCM + +`core/edcm.py` computes metrics from response text (content length, variance, context overlap). `backend/edcm_engine.py` computes metrics from seed state dicts (health scores, masses, roles). These are two separate derivation paths feeding the same six-family schema. + +To add a new directive: add it to `DIRECTIVES` in `core/edcm.py`, add the corresponding firing condition to `EDCMAnalyzer._fire_directives()` in `backend/edcm_engine.py`, and add a test in `tests/test_edcm_engine.py`. + +--- + +## Frontend + +React app in `frontend/`. Components: `TopologyVisualization`, `SystemHealthDashboard`, `EDCMArtifacts`, `LLMInterface`, `SMSConsole`. Not tested in CI. Backend served separately. diff --git a/README.md b/README.md index a16ba80..11cfbf3 100644 --- a/README.md +++ b/README.md @@ -1,448 +1,205 @@ -# PCNA Repo -Initialized Sat Jan 31 19:00:28 PST 2026 -Below is a single-file, copypastable README.md for your PCNA repository, written clean, technical, and grounded — aligned with your preference for structure first, then content and ready for GitHub. +# PCNA — Prime Circular Neural Architecture +Deterministic, prime-indexed circular graph architecture for modular compute and real-time diagnostics. --- -Prime Circular Neural Architecture (PCNA) +## Architecture -Deterministic, prime-indexed, circular graph architecture for modular compute + diagnostics. +PCNA organizes compute and diagnostics into **61 seeds** arranged on a unit-circle address space with heptagram (7-site) routing. The core ring tensors use N=53 (a prime) as their node count, which avoids harmonic aliasing in heptagram propagation. -GPT generated; context, prompt Erin Spencer +### Seed Topology +| Layer | Count | Role | +|-------|-------|------| +| Global router | 1 | Coordination root (ID 0) | +| Sentinels | 4 | Diagnostics — observe, do not compute | +| Meta routers | 7 | Cluster aggregation | +| Compute seeds | 49 (7×7) | Primary compute units | +| **Total** | **61** | | ---- - -I. Purpose - -PCNA is an experimental neural / distributed-compute topology that: - -organizes compute nodes on a unit-circle address space - -routes traffic through prime-indexed clusters - -separates computation from diagnostics - -embeds observability directly into the architecture - - -Design goal: - -> predictable routing, sparse communication, measurable stability - - - -PCNA avoids opaque dense attention or monolithic networks in favor of: - -explicit structure - -bounded neighborhoods - -inspectable flows - -failure visibility - - - ---- - -II. Core Ideas (Plain English) - -Instead of: - -> one giant black-box neural net - - - -PCNA uses: - -many small nodes - -clustered routing - -meta routers - -independent sentinels watching the system - - -So: - -compute happens here -analysis happens there -feedback closes the loop - -This enables: - -modular growth - -easier debugging - -resilience to failure - -compatibility with EDCM diagnostics - - - ---- - -III. Topology - -Node counts - -Layer Count Role - -child routers 49 primary compute -meta routers 7 cluster aggregation -sentinels 4 diagnostics / metadata -global router 1 coordination root -total seeds 53 prime-indexed set - - -53 is chosen because: - -prime → avoids harmonic aliasing - -clean cluster separation - -symmetric layout for circular addressing - - - ---- - -Layout - -(sentinels) - ○ ○ - ○ ○ - - [ 7 clusters × 7 nodes each ] - - → meta routers (7) - ↓ - global zero - - ---- - -IV. Functional Layers - -1. Child Routers (49) - -Primary compute units. - -Responsibilities: - -token transforms - -state updates - -local tensor math - -Markov recursion - -learning steps - - -Properties: - -small - -independent - -replaceable - - - ---- - -2. Meta Routers (7) - -Cluster coordinators. - -Responsibilities: - -aggregate child outputs - -route inter-cluster traffic - -reduce bandwidth - -maintain locality - - - ---- - -3. Global Router (0) - -System spine. - -Responsibilities: - -high-level coordination - -broadcast - -synchronization - -scheduling - - - ---- - -4. Sentinels (4) - -Diagnostics only — not compute. - -Responsibilities: - -anomaly detection - -stability metrics - -constraint strain (EDCM) - -outlier detection - -metadata analysis - - -Key rule: - -> Sentinels observe but do not influence compute directly. +Each compute seed connects to heptagram neighbors (`±3 mod 7` within its meta cluster). Routing traverses the meta-router tree; sentinels scan with a 7:2 stride pattern and publish diagnostics only. +### Six-Ring Inference Engine (`core/pcna.py`) +The `PCNAEngine` runs a six-ring pipeline per inference call: -They produce: +| Ring | Symbol | N | Seed | Role | +|------|--------|---|------|------| +| Phi | Φ | 53 | 53 | Cognitive substrate | +| Psi | Ψ | 53 | 43 | Self-model | +| Omega | Ω | 53 | 47 | Autonomy | +| Theta | Θ | 29 | 29 | Microkernel gate | +| Memory-L | — | 19 | 19 | Long-term memory | +| Memory-S | — | 17 | 17 | Short-term memory | -signals +**Ring weights** (coherence scoring): Φ 0.30 · Θ 0.20 · Ψ 0.15 · Ω 0.15 · Memory-L 0.12 · Memory-S 0.08 -flags +Sigma (Σ) is an optional observer ring outside the scored pipeline: -feedback +| Ring | Symbol | N | Seed | Role | +|------|--------|---|------|------| +| Sigma | Σ | 41 | 41 | Filesystem observer — injects coherence into Ψ | +Sigma appears in `state()["rings"]` but is not in `RING_WEIGHTS`; it is accessed via `try/except` and degrades gracefully if unavailable. -Never hidden mutation. +**Inference steps:** +1. **Project** — SHA-512(text) → 53-dim normalized signal +2. **Inject** — push signal into Φ; cross-inject Θ coherence → Φ, Φ coherence → Ψ, Σ coherence → Ψ, Memory-L hub → Ω +3. **Propagate** — heptagram propagation (Φ:10, Ψ:8, Ω:6, Θ:5 steps) +4. **PTCA-seed audit** — per-node hub-ring coherence for Φ/Ψ/Ω +5. **PCTA-circle audit** — gate status and circle counts on Θ +6. **Coherence score** — weighted ring coherence → winner ring + confidence +### EDCM — Six-Family Diagnostics ---- - -V. Data Flow - -Forward pass - -input - → children - → meta routers - → global router - → output - -Diagnostic loop - -all states - → sentinels - → metrics - → health signals - → optional corrective policies +The EDCM subsystem (`core/edcm.py`, `backend/edcm_engine.py`) measures system health continuously: -Separation of concerns: +| Metric | Key | Alert | +|--------|-----|-------| +| Constraint Mismatch | `cm` | HIGH ≥ 0.80 | +| Dissonance Accumulation | `da` | HIGH ≥ 0.80 | +| Drift | `drift` | HIGH ≥ 0.80 | +| Divergence | `dvg` | HIGH ≥ 0.80 | +| Intensity | `int_val` | LOW ≤ 0.20 | +| Turn-Balance Fairness | `tbf` | LOW ≤ 0.20 | -Path Purpose - -compute results -sentinel measurement +**Behavioral directives** fire automatically on threshold crossings: +`CONSTRAINT_REFOCUS` · `DISSONANCE_HALT` · `DRIFT_ANCHOR` · `DIVERGENCE_COMMIT` · `INTENSITY_CALM` · `BALANCE_CONCISE` +### ZetaEngine (`core/zeta.py`) +Non-LLM real-time learning: after every assistant response, ZFAE (Zeta Function Alpha Echo) computes EDCM coherence and drives PCNA Φ-ring reward backprop. Supports per-directory resolution levels (1–5). --- -VI. Why This Exists - -Problems with typical deep nets - -opaque - -fragile - -hard to debug - -expensive global attention - -poor observability - - -PCNA aims to provide - -deterministic routing - -sparse communication - -explicit locality - -inspectability - -modular scaling - -native diagnostics - - +## Repository Structure ---- - -VII. Relationship to EDCM - -PCNA and EDCM are complementary: - -System Role - -PCNA compute substrate -EDCM dissonance / stability metrics - - -Conceptually: - -PCNA thinks -EDCM measures strain of thinking - -This allows: - -early instability detection - -alignment checks - -human-readable diagnostics - - - ---- - -VIII. Minimal Folder Structure - -pcna/ +``` +├── core/ +│ ├── pcna.py # PCNAEngine — six-ring inference pipeline +│ ├── ptca_core.py # PTCACore — parameterized prime-ring tensor +│ ├── theta.py # ThetaTensor — N=29 microkernel gate +│ ├── sigma.py # SigmaRing — N=41 filesystem observer +│ ├── memory_core.py # MemoryCore — long/short-term memory rings +│ ├── merge.py # InstanceMerge — absorb/fork/converge +│ ├── zeta.py # ZetaEngine — EDCM-driven backprop +│ ├── edcm.py # EDCM metrics, alerts, directives +│ ├── topology.py # PCNATopology — seed layout and routing +│ ├── tensor_engine.py # TensorState, MarkovRecursion +│ ├── routing_loop.py # GlobalRouterZero (stub — not implemented) +│ └── helix_vis.py # Spectral helix visualizer │ -├─ core/ -│ ├─ node.py -│ ├─ router.py -│ ├─ cluster.py -│ ├─ sentinel.py -│ └─ topology.py +├── backend/ +│ ├── server.py # FastAPI — endpoints, WebSocket, MongoDB +│ ├── edcm_engine.py # EDCMAnalyzer — artifacts and directives +│ ├── llm_abstraction.py # LLMOrchestrator — multi-provider fallback +│ ├── optimization_engine.py # SelfOptimizer — health and anomaly monitor +│ ├── sms_service.py # SMSService (Twilio stub) +│ ├── moltbook_integration.py # MoltbookClient (stub) +│ └── researcher_outreach.py # OutreachManager — researcher campaign │ -├─ metrics/ -│ ├─ edcm_adapter.py -│ └─ health_metrics.py +├── frontend/src/ +│ ├── TopologyVisualization.js +│ ├── SystemHealthDashboard.js +│ ├── EDCMArtifacts.js +│ ├── LLMInterface.js +│ └── SMSConsole.js │ -├─ sims/ -│ ├─ toy_markov.py -│ └─ stress_tests.py +├── tests/ +│ ├── test_edcm_engine.py # EDCM + EDCMAnalyzer unit tests +│ ├── test_tensor_engine.py # MarkovRecursion mass-conservation tests +│ └── tests_topology.py # PCNATopology routing tests │ -├─ viz/ -│ ├─ circular_layout.py -│ └─ cylinder_unwrap.py -│ -├─ docs/ -│ └─ architecture.md -│ -└─ README.md - +├── schemas/ # JSON schema definitions +├── main.py # Seed runner entry point (FastAPI) +├── conftest.py # sys.path setup for pytest +└── requirements.txt +``` --- -IX. Minimal Prototype (concept sketch) - -class ChildNode: - def step(self, x): - return transform(x) - +## Installation -class MetaRouter: - def __init__(self, children): - self.children = children +```bash +pip install -r requirements.txt +``` - def route(self, x): - return sum(c.step(x) for c in self.children) - - -class Sentinel: - def inspect(self, states): - return anomaly_score(states) +Additional dependencies required for full production use: +| Package | Required by | +|---------|-------------| +| `motor` | `backend/server.py` — async MongoDB | +| `python-dotenv` | environment variable loading | +| `emergentintegrations` | `backend/llm_abstraction.py` — multi-provider LLM | +| `scipy` | `proof_check.py` — spectral analysis | +| `matplotlib` | `core/helix_vis.py` — visualization | --- -X. Design Principles +## Running -small pieces > giant monoliths +### Seed runner (single node) -explicit > implicit +```bash +SEED_ID=1 ROLE=compute PORT=8001 python main.py +``` -inspectable > mystical +Multi-seed: set `SEED_URL_=http://host:port` for each neighbor. -deterministic > emergent chaos +### Backend server -diagnostics first-class +```bash +uvicorn backend.server:app --reload +``` +### Tests +```bash +pytest +``` --- -XI. Status - -Early research / experimental. +## Multi-Instance Mesh -Not production hardened. - -Iteration expected. - -Refinement will continue. +`core/merge.py` provides three merge modes for running multiple `PCNAEngine` instances: +| Mode | Behaviour | +|------|-----------| +| `absorb(dominant, donor)` | Dominant absorbs donor state (α=0.15); donor retired | +| `fork(parent)` | Parent spawns child with copied state + Gaussian noise; both continue | +| `converge(a, b, alpha)` | Federated averaging in both directions (default α=0.50); both continue | --- -XII. Attribution - -GPT generated; context, prompt Erin Spencer - - ---- - -XIII. License - -MIT recommended -(simple, permissive, encourages adoption and collaboration) +## Checkpointing +```python +engine = PCNAEngine() +engine.load_checkpoint() # restore from .checkpoints/pcna_checkpoint.npz +# ... inference ... +engine.save_checkpoint() # persist all ring tensors +``` --- -XIV. hmm - -Open constraints / active questions: - -is 4 sentinel coverage optimal vs 5 or 7? - -best routing strategy: deterministic vs adaptive? - -ideal cluster size beyond 7? - -sentinel → compute feedback latency tradeoffs - - -(hmm retained intentionally as unresolved design space) +## Design Principles +- **Deterministic routing** over opaque attention +- **Sparse communication** — bounded neighborhoods, heptagram adjacency +- **Explicit structure** — every ring self-declares identity in `state()` +- **Diagnostics first-class** — EDCM runs continuously, not as an afterthought +- **Inspectable** — checkpoint/restore, per-node coherence, per-ring state dicts +- **Modular growth** — rings are independently parameterized by `(n, seed, role)` --- -If you'd like next, I can: - -generate architecture.md - -write topology.py - -build a runnable Python demo - -or produce SVG visualizers for the circle/cylinder unwrap +## Status +Experimental / research. Core inference engine and EDCM diagnostics are fully implemented. Several backend integrations are stubs awaiting external API credentials: -Structure or code next? +- **Twilio SMS** (`backend/sms_service.py`) — mock mode only +- **Moltbook** (`backend/moltbook_integration.py`) — all stubs +- **Researcher email sending** (`backend/researcher_outreach.py`) — generation implemented, sending is a stub +- **routing_loop.py** — not yet implemented