flywire-coding-cortex 0.1.0__tar.gz

flywire_coding_cortex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlyWire Coding Cortex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

flywire_coding_cortex-0.1.0/PKG-INFO

@@ -0,0 +1,447 @@
+Metadata-Version: 2.4
+Name: flywire-coding-cortex
+Version: 0.1.0
+Summary: Run FlyWire-derived LIF neurons and map rates to coding-agent drives
+Author: FlyWire Coding Cortex contributors
+License: MIT
+Project-URL: Homepage, https://github.com/imrizwan/flywire-cortex
+Project-URL: Codex, https://codex.flywire.ai/
+Keywords: flywire,connectome,LIF,agent,openclaw,cursor,mcp
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: full
+Requires-Dist: pandas>=2.0; extra == "full"
+Requires-Dist: pyarrow>=14; extra == "full"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Dynamic: license-file
+
+# FlyWire Coding Cortex
+
+**Pip-installable connector** for AI coding agents: install once, then every
+Cursor / OpenClaw / Claude session can **run FlyWire-derived neurons** (leaky
+integrate-and-fire on real synapse edges) and map population rates into
+**coding drives** (implement, stop, reverse, steer, groom).
+
+| | |
+|---|---|
+| **Code license** | MIT |
+| **Circuit data** | FlyWire-derived, [CC BY-NC 4.0](data/DATA_LICENSE.md) |
+| **Anatomy browser** | [FlyWire Codex](https://codex.flywire.ai/) |
+| **Default seed** | 668 neurons · ~19k signed edges (FAFB v783 escape/steering subgraph) |
+
+> **Honesty bar:** Wiring and contact counts come from public FlyWire data.
+> Membrane dynamics, task→current encoding, and the rate→coding map are
+> **models**. This does not claim biologically calibrated coding skill or that
+> a fruit fly “understands” your codebase.
+
+---
+
+## Why this exists
+
+Most agent “skills” are markdown instructions. This package is a
+**pip-installable tool** plus an ambient skill/MCP connector so agents can
+call a real runtime every session—without cloning a folder into every project.
+
+```text
+coding task
+    │
+    ▼
+sense (risk / tests / urgency → currents)
+    │
+    ▼
+LIF on FlyWire-derived circuit.json
+    │
+    ▼
+population rates (gf, dnp09, mdn, loom, …)
+    │
+    ▼
+CodingSignals (primary drive + clamps)
+    │
+    ▼
+agent acts  ──verify──►  Hebbian coding memory
+```
+
+---
+
+## Quick start
+
+```bash
+# From this repository
+pip install -e .
+# Optional (needed for --profile full):
+# pip install -e ".[full]"
+
+flywire-cortex fetch --profile seed
+flywire-cortex install
+flywire-cortex status
+```
+
+Smoke test:
+
+```bash
+flywire-cortex reset
+flywire-cortex sense --text "urgent failing auth bug"
+flywire-cortex step --ms 50
+flywire-cortex signals
+```
+
+Example: giant-fiber stop drive
+
+```bash
+flywire-cortex reset
+flywire-cortex stimulate gf --strength 0.5 --ms 80
+flywire-cortex step --ms 10
+flywire-cortex signals
+# → primary: "gf", escape: true, stop: true
+```
+
+If `pip install` fails (SSL / corporate proxy), you can still run from source:
+
+```powershell
+$env:PYTHONPATH = "C:\path\to\flywire-coding-cortex\src"
+python -m flywire_coding_cortex.cli status
+```
+
+---
+
+## Install
+
+### 1. Package
+
+```bash
+pip install flywire-coding-cortex          # when published to PyPI
+# or
+pip install -e .                          # from a clone
+# or
+uv tool install .
+```
+
+`pip install` **does not download** connectome dumps. Data is opt-in via `fetch`.
+
+### 2. Circuit profile
+
+```bash
+flywire-cortex fetch --list-profiles
+flywire-cortex fetch --profile seed       # default, offline after copy
+```
+
+### 3. Wire agents
+
+```bash
+flywire-cortex install
+# or subset:
+flywire-cortex install --targets cursor openclaw
+```
+
+Copies `skill/` into:
+
+| Target | Path |
+|---|---|
+| Cursor | `~/.cursor/skills/flywire-coding-cortex/` |
+| OpenClaw | `~/.openclaw/workspace/skills/flywire-coding-cortex/` (and `~/.openclaw/skills/` when present) |
+| Claude | `~/.claude/skills/flywire-coding-cortex/` |
+
+Also writes `~/.flywire-coding-cortex/mcp.snippet.json`.
+
+### 4. Optional MCP connector (Cursor)
+
+Add to your Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "flywire-coding-cortex": {
+      "command": "flywire-cortex",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Then restart the agent session. Tools exposed:
+
+| Tool | Purpose |
+|---|---|
+| `cortex_status` | Active profile + neuron/edge counts |
+| `cortex_sense` | Task text → sensory currents |
+| `cortex_step` | Advance LIF (`ms`, optional `text`) |
+| `cortex_stimulate` | Stim a role group (`gf`, `dnp09`, …) |
+| `cortex_signals` | Clamped coding drives JSON |
+| `cortex_remember` | Query / strengthen / weaken memory |
+
+---
+
+## Download profiles
+
+Choose (and later change) how much FlyWire data to pull. Profiles are cached
+side-by-side under `~/.flywire-coding-cortex/profiles/<name>/`. `status` /
+`step` always use the **active** profile.
+
+| Profile | Approx size | Command | What you get |
+|---|---|---|---|
+| `seed` | ~0.3–5 MB | `flywire-cortex fetch` | Bundled curated subgraph (668 cells by default) |
+| `codex` | ~60–300 MB | `flywire-cortex fetch --profile codex` | Public Codex gzipped CSVs + ETL rebuild |
+| `full` | ~10.6 GB | `flywire-cortex fetch --profile full --yes` | Zenodo Feathers + ETL (explicit confirm) |
+
+```bash
+flywire-cortex fetch --list-profiles
+flywire-cortex fetch --profile seed --force     # re-copy / switch back
+flywire-cortex fetch --profile full --yes
+flywire-cortex fetch --profile full --yes --include-synapses   # also ~9.5 GB synapse table
+flywire-cortex status
+```
+
+**Rules:**
+
+- Agents must **never** auto-run `full`. Ask the human first.
+- `full` requires `--yes` and `pip install 'flywire-coding-cortex[full]'` (pandas + pyarrow).
+- URLs live in [`data/manifest.json`](data/manifest.json) so mirrors can be edited without code changes.
+
+Codex dump base (FAFB v783):
+
+`https://storage.googleapis.com/flywire-data/codex/data/fafb/783`
+
+---
+
+## Every coding turn (agent loop)
+
+The bundled skill instructs agents to run this loop (CLI or MCP):
+
+1. **`status`** — ensure a circuit exists (`fetch --profile seed` if missing)
+2. **`sense --text "…"`** — encode the task into currents (risk, test-red, urgency, ambiguity)
+3. **`step --ms 50`** — run LIF on real edges
+4. **`signals`** — read `primary` drive and clamps
+5. **Act only under that primary drive** (see [Roles](#roles--coding-drives))
+6. Apply [practices](#thinking-practices)
+7. After verify: **`remember strengthen|weaken`**
+
+LIF voltage/rates persist across separate CLI invocations in
+`~/.flywire-coding-cortex/state/lif_state.json`. Use `flywire-cortex reset` to
+clear between unrelated tasks.
+
+---
+
+## CLI reference
+
+```text
+flywire-cortex <command> …
+```
+
+| Command | Description |
+|---|---|
+| `fetch` | Download / activate a profile (`--profile`, `--list-profiles`, `--force`, `--yes`, `--include-synapses`) |
+| `status` | Home path, active profile, neuron/edge/role counts |
+| `sense` | Encode task text (or `--risk` / `--test-red` / `--urgency` / `--ambiguity`) |
+| `step` | Advance simulation (`--ms`, optional `--text`) |
+| `stimulate` | Stim a group: `gf`, `dnp09`, `mdn`, `lc4`, `lplc2`, `dng11`, `escw`, `dna01`, `dna02`, … |
+| `signals` | Emit coding drives JSON (`--ms` to step first) |
+| `reset` | Clear persisted LIF state |
+| `remember` | `query` \| `strengthen` \| `weaken` \| `add-node` \| `add-edge` |
+| `install` | Copy skills + print MCP snippet (`--targets`) |
+| `mcp` | Run MCP stdio server |
+
+### `remember` examples
+
+```bash
+flywire-cortex remember query --text "auth middleware"
+flywire-cortex remember strengthen --pre concept:tests --post role:dnp09 --why "ci green"
+flywire-cortex remember weaken --pre concept:migration --post role:dnp09 --why "broke prod"
+flywire-cortex remember add-node --pre concept:oauth --label "OAuth flow"
+flywire-cortex remember add-edge --pre concept:oauth --post role:lc4 --why "auth is high risk"
+```
+
+---
+
+## Roles → coding drives
+
+FlyWire-style role names are **coding lenses**. Rates come from the live sim;
+the bridge picks a **winner-take-most** primary.
+
+| Role | Drive | Agent should |
+|---|---|---|
+| `lc4` / `lplc2` | Risk / loom | Scan blast radius, security, regressions |
+| `gf` | Escape / stop | Do not ship; halt feature work; unblocker |
+| `dnp09` | Forward | Implement the requested change |
+| `mdn` | Reverse | Revert / undo a bad direction |
+| `dna01` / `dna02` | Steer | Write L vs R tradeoff, then choose |
+| `dng11` | Groom | Cleanup, rename, lint-only |
+| `escw` | Effort under pressure | Polish without scope creep |
+| `ascending` | Proprioception | Read local conventions before inventing |
+| `sensory` | External constraint | Honor ticket / failing test / user text |
+
+Example `signals` payload:
+
+```json
+{
+  "primary": "dnp09",
+  "escape": false,
+  "stop": false,
+  "reverse": false,
+  "walk_drive": 0.42,
+  "nervous": 0.12,
+  "support": ["lc4"],
+  "rationale": "primary=dnp09 walk=0.42 nervous=0.12 mdn=0.0 gf=False"
+}
+```
+
+---
+
+## Thinking practices
+
+Applied **on top of** rates (see `skill/practices.md`):
+
+1. **Winner-take-most** — one primary drive per turn  
+2. **Inhibition delay** — high risk → list blast radius before edits  
+3. **Recurrent working set** — ≤5 active files/APIs  
+4. **Hebbian writeback** — strengthen only after verify; weaken on failure  
+5. **Sparse coding** — smallest change that satisfies the drive  
+6. **Bilateral steer** — design forks get an explicit L/R paragraph  
+7. **Proprioception first** — read neighbors before new patterns  
+8. **Refractory** — after `gf` / `mdn`, no new feature drive that turn  
+9. **Population scores** — prefer CLI sense scores over vibes  
+10. **Consolidate** — end of session: 3 new + 1 weakened memory edges  
+
+---
+
+## Architecture
+
+```text
+flywire-coding-cortex/
+  pyproject.toml
+  README.md                 ← you are here
+  INSTALL.md
+  LICENSE                   ← MIT (code)
+  data/
+    circuit.seed.json       ← curated FlyWire subgraph (CC BY-NC)
+    manifest.json           ← profile URLs / sizes
+    DATA_LICENSE.md
+  memory/
+    seed-graph.json         ← starter coding-memory ontology
+  skill/
+    SKILL.md                ← Cursor / OpenClaw / Claude skill
+    roles.md
+    practices.md
+  src/flywire_coding_cortex/
+    cli.py                  ← entrypoint
+    lif.py                  ← LIF on CSR adjacency
+    sense.py                ← task → currents
+    bridge.py               ← rates → CodingSignals
+    memory.py               ← Hebbian graph
+    paths.py                ← FLYWIRE_CORTEX_HOME helpers
+    mcp_server.py
+    install_skills.py
+    assets/                 ← copies shipped in the wheel
+    etl/
+      download.py           ← fetch profiles
+      build_circuit.py      ← Codex / Feather → circuit.json
+```
+
+### Runtime home (`FLYWIRE_CORTEX_HOME`)
+
+Default: `~/.flywire-coding-cortex/`
+
+| Path | Contents |
+|---|---|
+| `config.json` | Active profile name |
+| `profiles/<name>/circuit.json` | Active wiring |
+| `profiles/<name>/raw/` | Downloaded dumps (gitignored) |
+| `state/lif_state.json` | Persisted voltages / rates / stims |
+| `memory/graph.json` | Coding synapses (not FlyWire edges) |
+| `mcp.snippet.json` | MCP config helper |
+
+Override:
+
+```bash
+# bash
+export FLYWIRE_CORTEX_HOME=/path/to/cortex-home
+
+# PowerShell
+$env:FLYWIRE_CORTEX_HOME = "D:\cortex-home"
+```
+
+### What is real vs modeled
+
+| Real (measured / extracted) | Modeled |
+|---|---|
+| Neuron IDs, sides, types, roles in the subgraph | LIF τ, threshold, noise, weight scale |
+| Signed synapse counts from Codex NT types | Task text → current injection |
+| Graph adjacency used for spike propagation | Rate → coding-drive clamps |
+| | Hebbian coding-memory edges |
+
+---
+
+## Environment & dependencies
+
+- Python **≥ 3.10** (3.10+ recommended; annotations use modern syntax)
+- Required: `numpy`
+- Optional `[full]`: `pandas`, `pyarrow` (Zenodo Feather profile)
+
+```bash
+pip install -e ".[full]"
+```
+
+---
+
+## Limitations (v1)
+
+- Does **not** simulate the full ~139k-neuron brain every turn  
+- Does **not** call live Codex apps (sign-in wall); uses static public files  
+- Does **not** depend on DesktopFly or any overlay app  
+- `full` downloads are large; confirm disk and network before `--yes`  
+- MCP server is a minimal JSON-RPC subset (`initialize`, `tools/list`, `tools/call`)  
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `flywire-cortex` not found | `pip install -e .` or set `PYTHONPATH=…/src` and run `python -m flywire_coding_cortex.cli` |
+| `circuit.seed.json missing` | Run `fetch --profile codex` once to rebuild, or ensure `data/circuit.seed.json` exists in the repo |
+| Rates always zero across commands | Call `sense`/`stimulate` then `step`; state persists—use `reset` between unrelated tasks |
+| `full` refuses to run | Pass `--yes`; install `[full]` extras |
+| Skill not picked up | Re-run `flywire-cortex install`; start a **new** agent session |
+| SSL errors on `pip install` | Fix certs / use a venv; interim: `PYTHONPATH` + `python -m …` |
+
+---
+
+## Citation & attribution
+
+Please cite FlyWire when using or redistributing circuit extracts:
+
+- Dorkenwald, S. et al. *Neuronal wiring diagram of an adult brain.* Nature 634, 124–138 (2024). https://doi.org/10.1038/s41586-024-07558-y  
+- Schlegel, P. et al. *Whole-brain annotation and multi-connectome cell typing of Drosophila.* Nature 634, 139–152 (2024). https://doi.org/10.1038/s41586-024-07686-5  
+
+Project sites: [flywire.ai](https://flywire.ai) · [codex.flywire.ai](https://codex.flywire.ai/)
+
+Code in this repository is MIT. Derived JSON and downloaded dumps remain under
+FlyWire’s **CC BY-NC 4.0** terms — see [data/DATA_LICENSE.md](data/DATA_LICENSE.md).
+
+---
+
+## Contributing / publishing
+
+```bash
+git clone <this-repo>
+cd flywire-coding-cortex
+pip install -e ".[full]"
+flywire-cortex fetch --profile seed
+flywire-cortex install
+```
+
+To rebuild the shipped seed from Codex dumps:
+
+```bash
+flywire-cortex fetch --profile codex --force
+# copies rebuilt circuit into data/circuit.seed.json and package assets
+```
+
+When ready for GitHub/PyPI: tag a release, ensure `circuit.seed.json` is
+committed, and document the CC BY-NC split in the release notes.