ravana-cognitive 0.3.2__tar.gz

ravana_cognitive-0.3.2/LICENSE

@@ -0,0 +1,109 @@
+Oxiverse Community License (OCL) v1.0. Source-Available • Non-Commercial • Privacy-by-Design.
+
+Oxiverse Community License (OCL) v1.0
+Copyright © 2026 Likhith Sai Seemala
+1. Grant of License
+Subject to the terms of this License, Likhith Sai Seemala ("Licensor") grants you a worldwide, non-exclusive, non-transferable, non-sublicensable license to:
+
+(a) use, copy, modify, and run the Software;
+(b) create derivative works of the Software;
+(c) share the Software and derivative works, for Non-Commercial Purposes only.
+Derivative works must be distributed under a license approved by the Open Source Initiative (OSI). However, such derivative works may not relicense, sublicense, or obscure the original Oxiverse Software's copyright notices, and any modification to the core Oxiverse Software must remain under OCL v1.0. "Core Oxiverse Software" means the Oxiverse cognitive architecture (including RAVANA, RLMv2, ConceptGraph, and successor components), IntentForge search engine, and any other Oxiverse services released under this License unless explicitly designated otherwise by Licensor.
+
+Commercial use is prohibited except as expressly permitted under Section 3.
+
+2. Non-Commercial Use Definition
+"Non-Commercial Purpose" means use that is:
+
+Personal, non-monetized experimentation
+Educational or academic instruction
+Academic or non-profit research
+Internal evaluation within a non-revenue-generating organization
+Open research or community learning projects
+Non-Commercial Purpose expressly excludes:
+
+Selling, licensing, or monetizing the Software or derivatives
+Offering the Software as a hosted service (SaaS, API-as-a-Service, etc.)
+Integrating the Software into a paid product, platform, or commercial offering
+Using the Software for commercial consulting, client work, or agency deliverables
+Any activity that generates revenue, directly or indirectly, using the Software
+Knowledge Exception: This License restricts the commercial distribution, hosting, or monetization of the Software itself. It does not restrict a developer's ability to use general knowledge, algorithms, ideas, or publicly documented concepts learned from reading or using the Software in wholly separate, unrelated commercial projects.
+
+3. Commercial Use & Licensing
+Commercial use of the Software is permitted under one of two paths:
+
+(a) Open-Source Commercial License (Free)
+You may use, modify, and monetize the Software for commercial purposes without paying a licensing fee, provided that:
+
+Your project and all derivative works are distributed under OCL v1.0 only;
+You make complete corresponding source code publicly available;
+You maintain all copyright notices and this License;
+You comply fully with Section 5 (Privacy-by-Design Requirement).
+This path is designed to reward builders who contribute back to the ecosystem.
+
+(b) Proprietary Commercial License (Paid)
+If you wish to develop, deploy, or monetize the Software without open-sourcing your derivative works, you must obtain a separate, written Commercial License from Licensor.
+
+To inquire about Proprietary Commercial Licensing, contact: likhith@oxiverse.com
+
+Proprietary Commercial Licenses may include terms for:
+
+Closed-source deployment in revenue-generating environments
+White-labeling or proprietary redistribution rights
+Support, updates, and SLA options
+Custom feature development or integration
+Multi-year licensing agreements with volume discounts
+3.1 Verification & Compliance
+If you claim eligibility for the Open-Source Commercial License under (a):
+
+You are responsible for maintaining public source code availability;
+Licensor reserves the right to verify compliance and request evidence of open-source distribution;
+Misrepresenting your project as open-source to avoid Commercial Licensing constitutes license violation and triggers Section 9 (Termination).
+3.2 No Selective Open-Washing
+Publishing only a frontend, UI layer, or non-functional wrapper under an open-source license while keeping the core engine, search index, ranking algorithms, cognitive architecture, or any revenue-generating component proprietary does not qualify as open-source distribution under this License. The complete corresponding source code for all functional components must be publicly available. Any attempt to circumvent this by architectural separation of "open" and "closed" modules triggers Section 9 (Termination).
+
+4. Redistribution & Source Availability
+If you distribute the Software or derivative works (even for Non-Commercial Purposes):
+
+(a) You must include this License in full, unmodified, with all copyright notices intact;
+(b) You must make the complete corresponding source code available under the same OCL v1.0 terms;
+(c) You may not sublicense, relicense, or distribute under different terms.
+5. Privacy-by-Design Requirement
+All derivative works, modifications, or redistributions of the Software must uphold privacy-by-design as a non-negotiable baseline:
+
+(a) No Unauthorized Data Collection: You may not add tracking, telemetry, analytics, or user data collection mechanisms without explicit, informed, opt-in user consent.
+(b) Data Minimization: No telemetry, analytics, or user data may be collected except for crash logs and diagnostic data. Such logs must be stored locally by default. If the user chooses to transmit logs to a third-party service (including Oxiverse-operated services, or a self-hosted alternative), they must obtain explicit, informed, opt-in consent from the end-user. The Software must provide a clear mechanism to disable all log transmission entirely.
+(c) User Control: Users must retain the ability to view, export, and delete any data generated or stored by the Software.
+(d) Enhancements Encouraged: You are free—and encouraged—to enhance privacy protections beyond this baseline (e.g., end-to-end encryption, local-first architecture, zero-knowledge proofs).
+(e) Transparency & Mandatory Privacy Policy: Any entity distributing the Software or derivative works (commercial or non-commercial) must publish a human-readable privacy policy that: (i) discloses use of Oxiverse services; (ii) states that no user data is stored except crash logs, which may be transmitted (if the user opts in) to Oxiverse-operated services or a user-selected third-party alternative, and that transmission can be entirely disabled; (iii) is prominently linked in the Software and all distribution channels.
+Violation of this Privacy Requirement constitutes a material breach of this License and triggers automatic termination under Section 9.
+
+6. Contributions
+Any contribution submitted to Licensor for inclusion in the Software shall be governed by the terms of this License. By submitting a contribution, you represent that you have the right to do so, and you grant Licensor a perpetual, worldwide, non-exclusive, royalty-free license to distribute your contribution solely under the terms of OCL v1.0 (and any future versions of OCL that Licensor publishes).
+
+Commercial Licensing Exception: If Licensor wishes to include your contribution in a Proprietary Commercial License (Section 3(b)), Licensor must obtain your separate, explicit written consent and negotiate fair compensation with you at that time.
+
+Contributor Commercial Licensing Benefit: If you are a contributor to the Software and wish to obtain a Proprietary Commercial License (Section 3(b)) to commercialize derivative works based on your contribution, you are eligible for preferential licensing terms (discounted or waived fees) at Licensor's discretion, contingent on: (a) Your contribution being already merged into the core Software; (b) You operating a distinct, separate commercial service or product (not a direct fork of the Software); (c) Your application for commercial licensing explicitly referencing your contributor status and the specific contribution(s) involved.
+
+The core Oxiverse Software and its cognitive architecture (RAVANA, RLMv2, ConceptGraph, and successor components) remain under OCL v1.0 and may not be relicensed, sublicensed, or closed-sourced by any party, including contributors. Only derivative works and original extensions created on top of the core may be commercialized under proprietary terms, subject to a valid Proprietary Commercial License.
+
+7. Patent Grant
+Subject to the terms of this License, Licensor grants Licensee a non-exclusive, worldwide, royalty-free license under any patent claims licensable by Licensor that are necessarily infringed by the Software alone, solely for Non-Commercial Purposes. This patent grant terminates automatically upon any commercial use without a valid Commercial License.
+
+8. No Warranty
+THE SOFTWARE 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, TITLE, AND NON-INFRINGEMENT. IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+9. Termination
+This License automatically terminates if you violate any of its terms and fail to cure the violation after written notice. Upon discovery of a violation, Licensor shall provide written notice to Licensee and a reasonable opportunity (minimum 30 days) to cure the violation. If not cured within this period, the License terminates automatically. Upon termination:
+
+(a) All rights granted to you cease immediately;
+(b) You must cease all use, distribution, and development of the Software;
+(c) Licensor reserves the right to pursue legal remedies for unauthorized commercial use or privacy violations.
+10. License Versions
+Licensor may publish updated versions of this License. Existing projects may continue under the version they adopted at the time of first use. New projects should use the latest published version. Commercial License terms are negotiated separately and are not affected by public License updates.
+
+11. Governing Law & Jurisdiction
+This License shall be governed by and construed in accordance with the laws of the Republic of India, without regard to its conflict of law principles. Any disputes arising under or in connection with this License shall be subject to the exclusive jurisdiction of the courts located in Visakhapatnam, Andhra Pradesh, India.
+
+Last Updated: April 2026
+For licensing inquiries: likhith@oxiverse.com

ravana_cognitive-0.3.2/PKG-INFO

@@ -0,0 +1,530 @@
+Metadata-Version: 2.4
+Name: ravana-cognitive
+Version: 0.3.2
+Summary: RAVANA -- Pressure-driven cognitive ML framework (unified package)
+License: OCL-1.0
+Project-URL: Homepage, https://codeberg.org/oxiverse/ravana
+Project-URL: Repository, https://codeberg.org/oxiverse/ravana
+Project-URL: Documentation, https://codeberg.org/oxiverse/ravana/src/branch/main/docs
+Project-URL: Issues, https://codeberg.org/oxiverse/ravana/issues
+Classifier: License :: Other/Proprietary License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: web
+Requires-Dist: requests; extra == "web"
+Requires-Dist: sentence-transformers; extra == "web"
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == "viz"
+Requires-Dist: networkx; extra == "viz"
+Provides-Extra: full
+Requires-Dist: requests; extra == "full"
+Requires-Dist: sentence-transformers; extra == "full"
+Requires-Dist: matplotlib; extra == "full"
+Requires-Dist: networkx; extra == "full"
+Requires-Dist: tiktoken; extra == "full"
+Dynamic: license-file
+
+# RAVANA — Recursive Learning Model
+
+> **A pressure-driven cognitive ML framework where learning emerges from self-organization, not gradient descent.**
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
+[![NumPy](https://img.shields.io/badge/NumPy-1.20%2B-orange)](https://numpy.org)
+[![License](https://img.shields.io/badge/License-OCL%201.0-purple)](LICENSE)
+[![Status](https://img.shields.io/badge/Status-Research%20Prototype-yellow)]()
+
+---
+
+## What Is RAVANA?
+
+RAVANA is a **cognitive architecture research project** proposing *pressure-driven self-organization* as an alternative to gradient descent for machine learning. Instead of minimizing loss functions via backpropagation, RAVANA learns through **cognitive dissonance minimization**: prediction errors create internal pressure (free energy), and the system self-organizes to reduce that pressure.
+
+```
+Traditional ML:     Loss(θ) = f(prediction, target) → ∇Loss → θ ← θ - η∇Loss
+RAVANA:             Prediction Error → Free Energy (Pressure) → Hebbian Plasticity + Sleep → Equilibrium
+```
+
+### Core Philosophy
+
+| Traditional ML | RAVANA |
+|----------------|--------|
+| **Loss functions** → gradients | **Free energy** (pressure) → self-organization |
+| **Backpropagation** | **Hebbian/anti-Hebbian plasticity** + structural plasticity |
+| **Weight decay, regularization** | **Identity** + homeostatic sleep consolidation |
+| **Batch/layer normalization** | **SWS + REM sleep cycles** with dream sabotage |
+| **Dense weight matrices** | **ConceptGraph** (typed edges, inhibition, hierarchy) |
+| **Global attention** | **Spreading activation** (local, bounded, typed) |
+| **Static weights / RAG** | **Episodic → Semantic → Graph bridge** |
+| **External reward functions** | **Intrinsic motivation** (Meaning = f(-Dissonance, Identity, Prediction)) |
+| **No emotion/identity** | **VAD emotion engine** + momentum-based identity |
+
+---
+
+## Two Architectures, One Codebase
+
+RAVANA now contains **two complementary cognitive architectures**:
+
+### 1. **RAVANA v2** — GRACE Cognitive Core (`ravana-v2/`)
+The original GRACE (General Recursive Adaptive Cognitive Engine) with 27 phases (A–P) implementing:
+- **Governor regulation** (Phases A–C) — Hard constraints, predictive dampening, center-seeking homeostasis
+- **Strategy & Intent** (Phases D–J) — 4 strategy modes, planning, hypotheses, Occam layer
+- **World Model & Epistemology** (Phases F–G.5) — Belief reasoning, active probes, VoI-driven action
+- **Emotion & Sleep** (Phases K–L.5) — VAD emotion, empathy, 4-stage sleep, dual-process
+- **Meaning & Consciousness** (Phases M–N) — Intrinsic motivation, global workspace
+- **Human Memory & Dialogue** (Phases O–P) — Episodic/semantic persistence, conversational repair
+
+### 2. **RAVANA Modular** — Decoder-First Chat (`ravana/`) **NEW**
+A streamlined, package-oriented architecture focused on **continuous web learning** and **decoder-first generation**:
+- **CognitiveCore** (`ravana/core/`) — VAD emotion, Identity, Meaning, Dual-process, Global Workspace, Meta-cognition, Sleep, **Multi-user BeliefStore**
+- **GraphEngine** (`ravana/graph/`) — Concept graph, spreading activation, hippocampal indexing, curiosity scoring
+- **DecoderEngine** (`ravana/decoder/`) — Neural decoder, vocab building, seed corpus + web article training
+- **WebLearner** (`ravana/web/`) — Multi-API search (circuit breaker), background learning, curiosity-driven exploration (Phase 18)
+- **BootstrapManager** (`ravana/bootstrap/`) — Consolidated concept seeding (3 methods unified)
+- **RLMv2 Decomposed** (`ravana/nn/rlm/`) — RelationPredictor, PropagationEngine, Plasticity
+- **ChatInterface** (`ravana/chat/`) — CLI, response pipeline, reasoning loop
+
+---
+
+## Key Innovations (Shared)
+
+### 🧠 Pressure-Driven Learning
+No loss functions, no gradients, no backpropagation. Learning driven by **5-channel free energy accumulator** tracking semantic, linguistic, episodic, contradiction, and abstraction prediction errors.
+
+### 🕸️ ConceptGraph with Typed Edges
+Heterogeneous graph of concept nodes with **active/core/genesis vectors** connected by typed relation edges (semantic, causal, temporal, analogical, contextual, inferred, inhibitory). Each edge carries weight, confidence, relation vector, predicate token, EWC importance, and Bayesian posterior.
+
+### 💤 Sleep Consolidation (SWS + REM)
+Two-phase sleep modeled on mammalian sleep:
+- **SWS**: Structural stabilization, adaptive homeostatic downscale, hierarchical abstraction compression, inhibitory edge formation, hippocampal replay
+- **REM**: Creative recombination via 20% counterfactual reversals, 10% emotional valence flipping, 1.5× failure oversampling
+
+### 🔄 Sleep-Time Interleaved Replay
+Domain-tagged experiences buffered during training, replayed during SWS+REM. **Eliminates catastrophic forgetting entirely** (12% → 0% retention drop) in lifelong streaming benchmarks.
+
+### 🏛️ GRACE Governor (v2 only)
+Closed-loop regulation with four layers: hard constraints (non-negotiable), predictive dampening (look-ahead), boundary pressure (air resistance), center-seeking homeostasis. **Fully observable** with clamp diagnostics.
+
+### 🎭 VAD Emotion Engine
+3D affective state (Valence, Arousal, Dominance) via differential equations. Modulates inference: high arousal → exploration, positive valence → trust predictions, high dominance → stronger concepts.
+
+### 🧩 RLMv2 — Triple Decomposition Architecture
+Brain-inspired: decomposes input into **(subject, relation_type, object)** triples. Enables vector arithmetic analogy: `subject_embed + offset(verb) ≈ target_embed`. **Spreading activation is the sole inference mechanism**.
+
+### 📖 GloVe Semantic Embeddings
+Token embeddings initialized from pre-trained GloVe (100D) projected via QR-based orthogonal projection. Replaces character n-gram embeddings for genuine semantic relationships.
+
+### 🎯 Verb-Stem Offset Predictor + Test-Time Adapter
+New inference path: `offset(verb) = avg(target - subject)` over training pairs. Each verb gets its own offset. For held-out subjects, an **entity-specific adapter (U, V matrices)** is initialized from the nearest training neighbor and adapted via 10-step MSE minimization: `min ||(subject_embed @ U.T @ V) + offset(verb) - target_embed||²`. This recovers held-out generalization from **5-12% to 93-100% Top-1**.
+
+### 🌐 Continuous Web Learning (Modular only)
+`WebLearner` fetches → extracts → trains decoder online. Knowledge grows **without retraining from scratch**. Curiosity-driven (free energy + contradiction + novelty + serendipity).
+
+### 👥 Multi-User Belief Merging (Modular only)
+`BeliefStore` tracks *who believes what*, detects contradictions, merges across users — `cross_reference_users()`, `find_agreement()`, `find_disagreement()`.
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+# Primary (Codeberg)
+git clone https://codeberg.org/oxiverse/ravana.git
+# Mirror (GitHub)
+git clone https://github.com/oxiverse-ecosystem/ravana.git
+cd ravana
+pip install -e ravana/          # NumPy only (modular package)
+pip install tiktoken            # Optional: BPE tokenizer
+```
+
+### Modular Package — Decoder-First Chat (NEW)
+
+```bash
+# Interactive chat with web learning
+python -m ravana.chat
+
+# Batch mode for testing
+python -m ravana.chat --chat "hello|what is trust|explain oxiverse|bye" --strategy
+
+# With ablation flags
+python -m ravana.chat --chat "what causes rain" --no-vad --no-rlm --no-beliefs --no-curiosity
+```
+
+**Key flags:**
+- `--no-vad` — Disable VAD emotion modulation
+- `--no-rlm` — Disable RLMv2 triple verification
+- `--no-beliefs` — Disable belief store
+- `--no-curiosity` — Disable autonomous curiosity-driven learning
+- `--mode` — `stochastic` | `deterministic` | `exploratory`
+- `--trace` — Print chain traces
+- `--data-dir` — Custom data directory
+- `--user` — Multi-user isolation
+
+### GRACE Cognitive Core (v2)
+
+```python
+from ravana_v2.cognitive import CognitiveFramework
+
+fw = CognitiveFramework()
+state = fw.initialize()
+
+for episode, (inp_vec, tgt_vec) in enumerate(training_data):
+    concepts = fw.perceive(state, inp_vec)
+    predictions = fw.predict(state, concepts)
+    state = fw.learn(state, predictions, tgt_vec, episode)
+    if episode % 100 == 0:
+        state = fw.sleep(state)
+
+result = fw.infer(state, test_vec)  # Inference without state change
+```
+
+### RLMv2 — Language Model (Shared)
+
+```python
+from ravana.nn import RLM
+from ravana_ml.tokenizer import WordTokenizer
+import numpy as np
+
+tok = WordTokenizer()
+tok.encode("heat causes expansion")
+
+model = RLM(
+    vocab_size=tok.vocab_size, 
+    embed_dim=64, 
+    concept_dim=64, 
+    n_concepts=100,
+    latent_dim=64,  # Set equal to embed_dim for entity adapter compatibility
+)
+inp = np.array(tok.encode("heat causes"), dtype=np.int64)
+tgt = np.array(tok.encode("expansion"), dtype=np.int64)
+model.learn(inp, tgt)
+model.sleep_cycle()
+logits = model.forward(inp)
+```
+
+**Note:** The `latent_dim` parameter controls the world model latent dimension. For the entity-specific adapter (enables test-time adaptation for held-out subjects) to work without additional projection overhead, set `latent_dim=embed_dim`. If they differ, the model automatically projects embeddings to latent space before applying the adapter.
+
+---
+
+## Benchmarks (External)
+
+All benchmarks are run via external benchmarking infrastructure. See [`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md) for reproduction instructions and expected results.
+
+### External Benchmark Harness (NEW)
+
+```bash
+# Quick run (PCX + Graph, ~2 min)
+python external_benchmark.py --quick
+
+# Full suite (PCX + Lifelong + Graph, ~10 min)
+python external_benchmark.py
+
+# Individual surfaces
+python external_benchmark.py --quick --skip-lifelong    # PCX + Graph
+python external_benchmark.py --quick --skip-pcx        # Lifelong + Graph
+```
+
+**Key external validation results:**
+
+| Metric | Result |
+|--------|--------|
+| Cross-domain transfer Top-1 | **75.0%** |
+| Cross-domain transfer Top-10 | **100%** |
+| Held-out Science Top-1 (adapted) | **93.8%** (n=16) |
+| Held-out Social Top-1 (adapted) | **95.0%** (n=20) |
+| Held-out Science Top-1 (baseline) | 12.5% (n=16) |
+| Held-out Social Top-1 (baseline) | 5.0% (n=20) |
+| Graph Inference P95 / P99 | 2.7 ms / 2.9 ms |
+| Graph Peak Memory / Throughput | 0.3 MB / 556 QPS |
+| W_rel Causal / Semantic Alignment | 0.68 / 0.55 |
+| Lifelong forgetting (permuted MNIST) | **0%** (with sleep) |
+| Within-domain triple top-10 | 80.9% |
+
+**Note:** Held-out numbers are reported with test-time entity adapter adaptation (10-step MSE on verb offset). Baseline (without adaptation) is shown for comparison. The adaptation recovers held-out generalization from 5-12% to 93-100%. Cross-domain structural transfer probes measure Science verbs + Social subjects and show 75% Top-1 with full bridge+alignment pipeline.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Complete architecture reference — GRACE, RLMv2, Phases A–P, GloVe, verb-stem offset |
+| [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) | Quickstart tutorial — install to first model in 5 minutes |
+| [`docs/ML_FRAMEWORK.md`](docs/ML_FRAMEWORK.md) | ravana_ml deep dive — tensors, modules, ConceptGraph, RLM v1/v2 |
+| [`docs/COGNITIVE_CORE.md`](docs/COGNITIVE_CORE.md) | ravana-v2 reference — all 27 GRACE modules, configurations |
+| [`docs/UNIFIED_PACKAGE.md`](docs/UNIFIED_PACKAGE.md) | ravana/ package — PyTorch API, CognitiveFramework, serialization |
+| [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) | Complete function/class reference for all three layers |
+| [`docs/CONCEPTS.md`](docs/CONCEPTS.md) | Theoretical foundations — pressure, free energy, Hebbian, sleep, VAD, triples |
+| [`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md) | Running experiments — cross-domain, Phase 4, RLMv2 benchmarks, cognitive phases, **modular ablations, per-triple eval** |
+| [`docs/ADVANCED_TOPICS.md`](docs/ADVANCED_TOPICS.md) | Customization — tokenizers, plasticity, sleep, governor, multi-agent, lifelong |
+| [`docs/TUTORIALS.md`](docs/TUTORIALS.md) | 8 step-by-step tutorials — Hello World to visualization |
+| [`docs/DEVELOPER_GUIDE.md`](docs/DEVELOPER_GUIDE.md) | Contributing — code standards, testing, architecture principles, release process |
+
+---
+
+## Running Tests
+
+```bash
+# Modular package tests (NEW)
+python -m pytest tests/test_cognitive_rlm.py -v
+python -m pytest tests/test_dialogue_system.py -v
+python -m pytest tests/test_dialogue_engine_integration.py -v
+python -m pytest tests/ -k "not slow" -v
+
+# RLMv2 unit tests (shared)
+python -m pytest tests/test_rlm_v2.py -v
+python -m pytest tests/test_rp_only.py -v
+python -m pytest tests/test_rp_contrastive.py -v
+python -m pytest tests/test_structural_transfer.py -v
+
+# GRACE cognitive core tests (v2)
+python -m pytest ravana-v2/tests/ -v
+
+# All tests
+python -m pytest tests/ ravana-v2/tests/ -v
+```
+
+**Current status: 1256+ tests passing**
+
+---
+
+## Running Experiments
+
+### Modular Package Experiments (NEW)
+
+```bash
+# Ablation study — all config combinations
+python scripts/run_ablation.py --queries "hello|what is trust|explain oxiverse|bye" --runs 3
+python scripts/run_ablation.py --quick --modes  # Baseline + single flag removals + mode variants
+
+# Per-triple evaluation harness
+python scripts/triple_eval.py --data-dir ./data --output triple_eval_report.json
+python scripts/triple_eval.py --triples-file my_triples.json --output report.json
+```
+
+### GRACE / ML Framework Experiments
+
+```bash
+# Cross-domain transfer
+python experiments/experiment_cross_domain.py
+
+# Phase 4 integrated (triplet margin + wake-sleep)
+python experiments/experiment_phase4_integrated.py
+
+# RLMv2 triple benchmark
+python experiments/experiment_triple_benchmark_v6.py
+
+# Diagnostic tests
+python tests/test_rp_only.py
+python tests/test_rp_contrastive.py
+python tests/test_structural_transfer.py
+
+# Cognitive architecture experiments
+cd ravana-v2 && python experiments/runner.py
+```
+
+### Custom Experiments
+
+See [`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md#custom-experiments) for templates and configuration reference.
+
+---
+
+## Project Structure
+
+```
+ravana/
+├── README.md                           # This file
+├── ravana/                             # Unified pip-installable package (NEW)
+│   ├── __init__.py                     # import ravana
+│   ├── core/                           # CognitiveCore
+│   │   ├── emotion.py                  # VADEmotionEngine (VAD dynamics)
+│   │   ├── identity.py                 # IdentityEngine (self-coherence)
+│   │   ├── meaning.py                  # MeaningEngine (dissonance reduction)
+│   │   ├── dual_process.py             # DualProcessController (System 1/2)
+│   │   ├── global_workspace.py         # GlobalWorkspace (broadcast)
+│   │   ├── meta_cognition.py           # MetaCognition (bias detection)
+│   │   ├── sleep.py                    # SleepConsolidation (hippocampal replay)
+│   │   ├── belief_store.py             # BeliefStore (multi-user merging)
+│   │   └── __init__.py
+│   ├── graph/                          # GraphEngine
+│   │   ├── engine.py                   # Concept graph, spreading activation, hippocampal indexing
+│   │   └── __init__.py                 # + backward compat: ConceptGraph, ConceptNode, etc.
+│   ├── decoder/                        # DecoderEngine
+│   │   ├── engine.py                   # Neural decoder, vocab, training, generation
+│   │   └── __init__.py
+│   ├── web/                            # WebLearner
+│   │   ├── learner.py                  # Multi-API search, background learning, curiosity
+│   │   └── __init__.py
+│   ├── bootstrap/                      # BootstrapManager
+│   │   ├── manager.py                  # Consolidated: auto_expand, seed_from_curiosity, bootstrap_domain
+│   │   └── __init__.py
+│   ├── nn/rlm/                         # RLMv2 Decomposed
+│   │   ├── relation_predictor.py       # RelationPredictor (W_rel, verb-stem offset)
+│   │   ├── propagation.py              # PropagationEngine (multi-phase spread)
+│   │   ├── plasticity.py               # Plasticity (Hebbian/Anti-Hebbian/Structural)
+│   │   └── __init__.py
+│   ├── chat/                           # ChatInterface
+│   │   ├── interface.py                # CLI, response pipeline, reasoning loop
+│   │   └── __init__.py
+│   └── pyproject.toml                  # numpy>=1.20
+├── ravana_ml/                          # ML Framework (~5,200 lines)
+│   ├── nn/rlm_v2.py                    # RLMv2 (triple decomposition, GloVe)
+│   ├── graph.py                        # ConceptGraph (3,678 lines)
+│   ├── tensor.py                       # StateTensor / RawTensor / Parameter
+│   ├── plasticity.py                   # Hebbian, Anti-Hebbian, Structural
+│   └── ... (tokenizer, embedder, free_energy, currencies, propagation)
+├── ravana-v2/                          # GRACE Cognitive Core (~19,500 lines)
+│   ├── core/                           # 27 Phases A–P modules
+│   │   ├── governor.py                 # Central regulation
+│   │   ├── identity.py                 # Momentum-based self-concept
+│   │   ├── sleep.py                    # 4-stage SWS+REM
+│   │   ├── emotion.py                  # VAD differential equations
+│   │   ├── human_memory.py             # Episodic/Semantic (2,321 lines)
+│   │   ├── global_workspace.py         # Consciousness bottleneck
+│   │   ├── meaning.py                  # Intrinsic motivation
+│   │   ├── dual_process.py             # System 1 / System 2
+│   │   └── ... (20 more modules)
+│   ├── experiments/phases/             # Phase runners
+│   └── tests/                          # Unit tests
+├── experiments/                        # Cross-domain & Phase 4 experiments (18 files)
+├── scripts/                            # Analysis & evaluation tools
+│   ├── run_ablation.py                 # Ablation study runner (NEW)
+│   ├── triple_eval.py                  # Per-triple evaluation harness (NEW)
+│   └── ...
+├── tests/                              # ML framework tests (17 files)
+├── docs/                               # Full documentation (13 files)
+├── data/glove/                         # GloVe embeddings (download required)
+├── results/                            # Benchmark outputs & diagnostics
+├── ablation_results.json               # Ablation study outputs
+├── triple_eval_report.json             # Per-triple diagnostic reports
+└── RAVANA_DEV_PLAN.md                 # Development roadmap
+```
+
+---
+
+## Ablation Study Framework (NEW)
+
+The modular package includes a systematic ablation runner (`scripts/run_ablation.py`):
+
+```bash
+# Full factorial (4 flags × 3 modes = 48 configs)
+python scripts/run_ablation.py --queries "hello|what is trust|explain oxiverse|bye" --runs 3
+
+# Quick mode (baseline + 4 single removals + 2 mode variants = 7 configs)
+python scripts/run_ablation.py --quick --modes
+
+# Output: ablation_results.json + markdown comparison table
+```
+
+**What it tests:**
+| Flag | Component |
+|------|-----------|
+| `--no-vad` | VAD emotion modulation |
+| `--no-rlm` | RLMv2 triple verification |
+| `--no-beliefs` | Multi-user belief store |
+| `--no-curiosity` | Autonomous curiosity-driven learning |
+
+**Metrics tracked:** Success rate, avg latency, total time, error modes per config.
+
+---
+
+## Per-Triple Evaluation Harness (NEW)
+
+Detailed diagnostics instead of averaged metrics (`scripts/triple_eval.py`):
+
+```bash
+# Default 10 triples (semantic, causal, contrastive)
+python scripts/triple_eval.py --data-dir ./data --output triple_eval_report.json
+
+# Custom triples
+python scripts/triple_eval.py --triples-file my_triples.json --output report.json
+```
+
+**Per-triple metrics:**
+- **Relation type**: semantic / causal / contrastive / possessive / temporal / analogical
+- **Prediction error (PE)**: how well the model predicts the object
+- **Confidence**: model's confidence in the prediction
+- **Top-1 / Top-5 accuracy**: exact match / in top 5
+- **Rank**: position of correct object in predictions
+- **Graph edge**: weight, confidence, type, `prediction_free_energy`
+- **Source**: where learned — `seed` | `web` | `user` | `sleep` | `inference` | `unknown`
+
+**Aggregated diagnostics:**
+- Overall metrics + by relation type + by source
+- Edge health summary (avg weight, confidence, PE, type distribution)
+
+---
+
+## How to Use This Project
+
+RAVANA is released under the **Oxiverse Community License (OCL) v1.0** — source-available, non-commercial, privacy-by-design.
+
+### Permitted (Non-Commercial Use)
+- **Use**: Run RAVANA for personal, academic, or research purposes.
+- **Modify**: Fork, change, and adapt the code.
+- **Distribute**: Share copies of the original or modified code, as long as this license is included.
+- **Commercial (Open-Source Path)**: Monetize your project if you keep all derivatives under OCL v1.0, publish complete source code, and comply with the Privacy-by-Design requirement (Section 5).
+
+### Not Permitted Without a Commercial License
+- **Closed-source commercial use** (SaaS, paid APIs, proprietary products, consulting built directly on RAVANA).
+- **Removing or obscuring** the copyright and license notice.
+- **Privacy violations**: Adding tracking, telemetry, or data collection without explicit opt-in consent.
+
+### Commercial Licensing
+- **Open-Source Commercial License (Free)**: Distribute under OCL v1.0 with full source code — no fee required.
+- **Proprietary Commercial License (Paid)**: Closed-source deployment, white-labeling, or SLA — contact likhith@oxiverse.com.
+
+### Why OCL?
+OCL protects the open research nature of RAVANA while allowing sustainable commercial adoption. The Privacy-by-Design requirement ensures user data remains under user control.
+
+---
+
+## License
+
+OCL v1.0 (Oxiverse Community License) — Source-Available, Non-Commercial, Privacy-by-Design. See [LICENSE](LICENSE) for the full text.
+
+---
+
+## About
+
+RAVANA explores an alternative paradigm for machine learning — where cognition emerges from **internal pressure**, not gradient optimization; where knowledge **self-organizes** through Hebbian plasticity and sleep consolidation; and where **identity, emotion, and meaning** are first-class citizens of the learning dynamics.
+
+**The core thesis**: *"Cognition as pressure-driven self-organization."*
+
+This is the center of gravity. Everything else is implementation detail.
+
+---
+
+## Citation
+
+If you use RAVANA in research, please cite:
+
+```bibtex
+@misc{ravana2026,
+  title={RAVANA: Pressure-Driven Self-Organization for Cognitive Machine Learning},
+  author={RAVANA Research Team},
+  year={2026},
+  url={https://codeberg.org/oxiverse/ravana}
+}
+```
+
+---
+
+## Links
+
+- **Documentation**: [`docs/`](docs/)