Developer docs + quickstart

README.md

@@ -0,0 +1,96 @@
+# CORTX — Self-Editing Reasoning Engine (open source)
+
+**CORTX** turns any instruct-tuned base model into a *self-editing reasoning
+engine*: it verifies its own math with executed code, revises its answers
+against an objective checker, rewrites its own operating rules when it finds
+better ones — and every one of those rewrites passes through a **hard security
+boundary** enforced in code, not prompts.
+
+Built by **ChatPBC Labs**. Apache-2.0.
+
+> Base model: `Qwen/Qwen2.5-7B-Instruct` + QLoRA adapter (trainable on a
+> single T4). The scaffold is model-agnostic — swap the base to any Qwen
+> (32B / 72B / 235B-A22B) or other instruct model by changing one config line.
+
+## What's in this repo
+
+| File | Purpose |
+|---|---|
+| `cortx_secure.py` | **The security engine**: whitelist + locked sections + size caps + rate limit + hash-chained audit + rollback. Drop-in module. |
+| `gen_synthetic.py` | Synthetic data generator (reasoning + self-edit + security-refusal + correction rows) |
+| `train_qwen.py` | QLoRA training kernel (single T4, 4-bit) |
+| `test_security.py` | Security self-test (6/6 passing) |
+| `SECURITY.md` | Threat model + defense layers + audit verification guide |
+| `serve/` | Reference serving kernel (OpenAI-compatible API + admin console, admin token-gated) |
+
+## Quickstart — use the security engine in your own project
+
+```python
+from cortx_secure import SecureEditor, AuditLog
+
+config = {"version": 1, "self_edit_enabled": True,
+          "constitution": "...", "tool_rules": "...",
+          "metacognitive_rules": "...", "refusal_rules": "...",
+          "playbook": "..."}
+editor = SecureEditor(config)                     # audit log auto-created
+
+# model emits [cortex_edit]{...}[/cortex_edit] blocks in its reply:
+clean_text, applied, rejected = editor.apply_edits(model_reply)
+
+print(applied)    # [{'section': 'playbook', 'chars': 120}]
+print(rejected)   # [{'section': 'identity', 'reason': 'locked section...'}]
+
+# tamper-evident audit — verify anytime:
+ok, n = editor.audit.verify()
+```
+
+The model **cannot** edit: identity, security_rules, weights, code, or the
+admin token. Attempts are rejected and logged. That boundary is code.
+
+## The self-improvement loop
+
+```
+user question
+   │
+   ▼
+gate: fast path vs deliberate (System-2)
+   │
+   ▼
+generate ──► parse [calc:]/[verify:] markers ──► sandboxed AST evaluator
+   │                    │ fails?                      │
+   │                    └──► REVISION request ◄───────┘
+   │                              │
+   ▼                              ▼
+[cortex_edit] blocks? ──► SecureEditor: validate → whitelist → caps → rate limit
+   │                              │
+   ▼                              ▼
+answer to user            config versioned + hash-chained audit log
+                          (admin can verify the chain or rollback)
+```
+
+## Training your own
+
+```bash
+python gen_synthetic.py 600        # -> synthetic_train.jsonl / synthetic_val.jsonl
+# upload to Kaggle, run train_qwen.py on a T4 (QLoRA, 4-bit)
+# adapter pushed to chatpbc1/CORTX/adapter-qwen
+```
+
+## Serving
+
+The reference server is an OpenAI-compatible FastAPI kernel (see `serve/`):
+`POST /v1/chat/completions` with a `cortex` option dict
+(`{"system2": true, "self_improve": true}`), plus `/cortex/config`,
+`/cortex/reset`, `/admin/audit` (token-gated), `/admin/rollback` (token-gated).
+
+## Honest limits
+
+- 7B base: strong at tool-fired math and instruction following; still a small
+  model on open-ended reasoning. The scaffold buys *verifiability and auditability*,
+  not raw IQ.
+- Self-edit *quality* is unvalidated by outcomes — review the audit log in
+  production. Security is enforced; edit wisdom is not.
+
+## License
+
+Apache-2.0 · ChatPBC Labs