gini-core 0.1.0__tar.gz

gini_core-0.1.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: gini-core
+Version: 0.1.0
+Summary: GINI core domain model — topology, devices, and the proof-of-activity format
+Author: GINI Toolkit
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/citelab/gini
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+
+# GINI — gBuilder 6.0
+
+**A visual lab for computer networks, cloud computing, *and* operating systems — draw a system, press Run, and it comes to life as real containers (and a real xv6 kernel) you can inspect, drive, and observe.**
+
+💬 **Join the community:** [GINI Discord](https://discord.gg/s5zTAgdKQd) — questions, help, and discussion.
+
+GINI lets students and instructors build a topology on a canvas, then launches it as
+honest, running infrastructure on Docker: a real C router that actually forwards packets,
+a real OpenFlow controller programming a real switch, and real cloud services (databases,
+object stores, message queues, dashboards) discoverable by name — plus a real **xv6** operating-system
+kernel you can watch and extend in a visual **Machine Lab**. A built-in AI tutor —
+**GINI** — explains what's on the canvas, animates how packets flow, and can scaffold
+whole working systems from a one-line description.
+
+It's designed to anchor three courses:
+
+- **Computer Networks** — switches, routers, subnets, firewalls, and real OpenFlow SDN.
+- **Cloud Computing** — VPC-style networking, managed services, autoscaling, observability.
+- **Operating Systems** — a real **xv6** (RISC-V) kernel in a visual **Machine Lab**: watch the
+  scheduler, system calls, traps, virtual memory, and the file system live, then extend the kernel
+  yourself with **shadows** — a novel way to drop your own code into a *running* xv6 machine to
+  experiment (fix the scheduler, add a syscall) without forking the kernel.
+
+> gBuilder 6.0 is the modern rewrite of the classic GINI Toolkit. The original
+> Python 2.7 / PyQt4 / SCons app lives under `legacy/` for reference.
+
+---
+
+## Highlights
+
+- **Visual builder** — a fast PySide6/Qt 6 canvas with a searchable palette of ~40
+  networking and cloud elements, theming, save/load, and an inspector.
+- **It actually runs** — Run compiles the canvas to a Docker Compose project and brings it
+  up. Machines, routers, switches, controllers, and cloud services all start as containers.
+- **The real C gRouter** — the genuine GINI router (built with `zig cc`), forwarding
+  packets over a portable user-space fabric. No kernel modules, no privileges.
+- **Real SDN** — drop an *OpenFlow Controller* + *OpenVSwitch*; GINI runs **POX** (Python 3)
+  programming the gRouter in OpenFlow-1.0 switch mode. Watch flows install on the first
+  packet, then forward at wire speed.
+- **Cloud services as containers** — MinIO, PostgreSQL, Redis, MongoDB, RabbitMQ, Kafka
+  (Redpanda), NATS, nginx, Traefik, Prometheus, Grafana, Jaeger, Fortio, and more — each a
+  real, off-the-shelf image reachable by service name.
+- **Live observability** — drop *Metrics* + *Dashboards* and GINI auto-wires
+  cAdvisor → Prometheus → Grafana with a prebuilt dashboard. Generate load and watch the
+  graphs move.
+- **A real OS to hack** — a genuine **xv6** kernel in a visual **Machine Lab** (scheduler, system
+  calls, traps, virtual memory, file system — all live over the serial, no gdb), plus **shadows**:
+  drop your own code into a running xv6 machine for experiments and graded assignments, no kernel
+  fork required.
+- **GINI AI** — an in-app tutor with **Explain**, **Tutor**, and **Wizard** modes. Ask it
+  to explain a device, trace a path, or describe a system you want and it lays out a
+  working blueprint. Runs against a local LLM (Ollama) or fully offline.
+
+---
+
+## Requirements
+
+- **Python 3.10+** (3.12 recommended). The Qt 6 GUI — **PySide6** plus **QtWebEngine** (for the
+  embedded Desktop / OS-Zoo screens) — installs **automatically** as a dependency; you never install
+  Qt separately, whichever install route you pick.
+- A **container runtime** — Docker, or **Colima**/**Podman** (`gini-setup` detects it and can help
+  install it) — needed to *Run* topologies. You can explore fully in **Demo mode** without one.
+- Works on **macOS, Linux, and Windows**. *Optional:* a local **[Ollama](https://ollama.com)** model
+  for richer GINI AI answers.
+
+---
+
+## Install
+
+There are **two ways to install, both fully supported** — pick one (don't mix the two; see
+Troubleshooting). Either way the Qt GUI (PySide6 + QtWebEngine) is pulled in automatically.
+
+### 1. From source — the latest code
+
+Recommended if you want the newest features, plan to build the xv6 kernel image yourself, or want to
+contribute. You track `main`, so you always have the freshest bits.
+
+```bash
+# in your clone of the repo:
+cd frontend-ng
+pip install -e .              # editable install; PySide6 + QtWebEngine come with it
+gini-setup                    # brings in the container runtime + images (one time)
+gbuilder                      # launch
+```
+
+### 2. Pre-compiled package — the simplest, most stable
+
+The hands-off route. It may be a version or two behind `main`, but it's the more stable, "just
+install and go" option — good for students and classroom setups.
+
+```bash
+pipx install gini-toolkit     # the app, isolated. `pip install gini-toolkit` also works.
+gini-setup                    # brings in the container runtime + images (one time)
+gbuilder                      # launch
+```
+
+Either way, `gbuilder` opens immediately — build, save, and explore topologies, with the AI tutor and
+everything in **Demo mode** working right away. Live **Run** (real containers) lights up once
+`gini-setup` finishes. After upgrading (`git pull` for source, or `pipx upgrade gini-toolkit` for the
+package), re-run `gini-setup --update` to refresh images.
+
+> No `pipx`? Install it once (`brew install pipx` on macOS, or `pip install pipx`), or use
+> `pip install gini-toolkit` inside a virtual environment.
+
+<details>
+<summary><b>macOS details</b></summary>
+
+`gini-setup` uses **Colima** — a free, lightweight Docker runtime, no Docker Desktop license needed.
+On a clean Mac with [Homebrew](https://brew.sh) it offers to run:
+
+```bash
+brew install colima docker
+colima start --cpu 2 --memory 4 --disk 30
+```
+
+If Docker Desktop (or Colima) is already running, `gini-setup` detects it and just pulls the images.
+</details>
+
+<details>
+<summary><b>Linux details</b></summary>
+
+Install **Docker Engine** first — it needs `sudo`, so `gini-setup` guides rather than auto-installs:
+
+```bash
+# https://docs.docker.com/engine/install/ for your distro, then:
+sudo usermod -aG docker $USER      # log out / back in afterwards
+```
+
+Podman works too. Then run `gini-setup` to pull the images.
+</details>
+
+<details>
+<summary><b>Windows details</b></summary>
+
+Colima isn't available on Windows — use **Docker Desktop** or **Podman Desktop**:
+
+```powershell
+winget install -e --id Docker.DockerDesktop
+```
+
+Start it, then run `gini-setup`. (Live-Run networking on Windows is still being validated;
+Demo mode works fully.)
+</details>
+
+<details>
+<summary><b>Dev tools & building images locally</b></summary>
+
+```bash
+# extra dev tooling (tests, linters) on top of the source install:
+cd frontend-ng && pip install -e ".[dev]"
+
+# build the container images yourself instead of pulling them
+# (needed to hack the xv6 kernel via shadows):
+docker build -t gini-xv6:latest backend/xv6      # + oszoo / grouter / pox
+```
+
+Point the app at a different image registry with `GINI_REGISTRY=ghcr.io/<owner>`.
+</details>
+
+<details>
+<summary><b>Troubleshooting</b></summary>
+
+- **"runtime not set up yet"** — run `gini-setup`. Demo mode still works without it.
+- **`gini-setup` pull says `denied` / `not found`** — images unreachable: check your network, or that
+  the registry (`ghcr.io/gini-toolkit`) is correct and its packages are public.
+- **Two `gbuilder`s on your PATH** — you installed with both pip *and* pipx; keep one
+  (`pip uninstall gini-toolkit` or `pipx uninstall gini-toolkit`).
+</details>
+
+---
+
+### Your first topology
+
+- **Place** a device by dragging it from the palette onto the canvas.
+- **Connect** two devices: click the **Connect** tool in the toolbar (the link icon), then
+  click the first device and then the second — a link appears. Click the tool again (or
+  press Esc) to leave Connect mode. You can also ask GINI: "connect R1 and S1".
+- **Run** the topology with the ▶ button.
+
+Once it's running:
+
+- **Double-click** a machine to open a shell; a service with a web UI (Grafana, MinIO …)
+  to open its dashboard; a router to open the **Router Lab**.
+- **Right-click** any node for **Open console**, **Log in**, **View logs**, or **Delete**.
+- The console log prints each running service's web URL.
+
+---
+
+## GINI AI
+
+The right-hand **Ask GINI** panel is a teaching assistant that always sees the live canvas.
+Modes are toggle buttons; the toolbar shows the current **mode** and whether GINI is
+**thinking**.
+
+- **Explain** — click any device and GINI explains it on the canvas (spotlight, callouts,
+  animated packet flows). It also explains palette elements ("when do I use a switch vs a
+  hub?").
+- **Tutor** — overlays highlights and animations as it teaches.
+- **Wizard** — describe what you want ("something I can watch under load", "a web app with
+  a database") and GINI matches a curated, guaranteed-to-work **recipe** and lays it out
+  with one click. The model only *selects and explains*; the building is deterministic, so
+  even a small local model can't produce a broken topology.
+
+Connect a model by pointing GINI at Ollama:
+
+```bash
+export GINI_LLM_URL=http://localhost:11434
+export GINI_LLM_MODEL=llama3.1        # or gemma, qwen, …
+python -m gini
+```
+
+Without a model, GINI still builds, inspects, traces paths, and ranks recipes
+deterministically.
+
+---
+
+## Software-Defined Networking
+
+The SDN stack is the original GINI design, made real:
+
+- **OpenVSwitch** element → the gRouter launched in `--openflow` mode (a real OpenFlow 1.0
+  switch).
+- **OpenFlow Controller** element → a **POX** (`gar`, Python 3) container running an app
+  you choose from the inspector (`l2_learning`, `hub`, or the classic `of_tutorial`).
+
+Draw `Controller → OVS → hosts`, Run, and ping between hosts: the first packet misses the
+flow table → goes up to POX → a flow is installed → the rest forward in the datapath. You
+can watch flows appear with `openflow entry all` in the OVS console, and the controller's
+decisions in its logs.
+
+---
+
+## Cloud service catalog
+
+Each of these palette elements runs as a real container, reachable by name on the lab's
+network (cloud-style service discovery):
+
+| Element | Backed by | Console |
+|---|---|---|
+| Object Storage | MinIO | ✓ |
+| Managed Database | PostgreSQL | — |
+| NoSQL Database | MongoDB | — |
+| Cache | Redis | — |
+| Message Queue | RabbitMQ | ✓ |
+| Event Stream | Redpanda (Kafka API) | — |
+| Pub/Sub | NATS | ✓ |
+| Reverse Proxy | Traefik | ✓ |
+| Load Balancer | nginx | — |
+| Web App | nginxdemos/hello | ✓ |
+| Container Registry | registry:2 | — |
+| Metrics | Prometheus | ✓ |
+| Dashboards | Grafana | ✓ |
+| Tracing | Jaeger | ✓ |
+| Load Generator | Fortio | ✓ |
+
+Compute elements (**Instance**, **Container**) run as plain containers on the same network,
+so a program inside them reaches services by name (`psql -h database1`,
+`http://objectstore1:9000`).
+
+---
+
+## Repository layout
+
+```
+frontend-ng/        gBuilder 6.0 — PySide6 app (domain · ui · agent · runtime · services)
+backend/
+  src/grouter/      the real C gRouter (~20k lines) incl. OpenFlow/SDN mode
+  grouter-build/      C build + Dockerfile (gini-grouter) + e2e forwarding tests
+  sdn/              POX (gar) controller + Dockerfile (gini-pox)
+legacy/             the original Python 2.7 / PyQt4 GINI, kept for reference
+ARCHITECTURE.md     what's active vs legacy, and how it fits together
+```
+
+See **[ARCHITECTURE.md](ARCHITECTURE.md)** for the full map.
+
+---
+
+## Testing
+
+```bash
+cd frontend-ng
+pytest                                   # ~95 tests
+# headless / CI:
+QT_QPA_PLATFORM=offscreen pytest
+```
+
+The gRouter has end-to-end forwarding proofs under `backend/grouter-build/tests/`
+(`forward_test.py`, `multihop_test.py`, …), runnable against a built `grouter` binary.
+
+---
+
+## Status
+
+gBuilder 6.0 is under active development. Working today: the visual builder, real packet
+forwarding through the C gRouter (single- and multi-router), OpenFlow SDN (POX + gRouter),
+the cloud service catalog, observability auto-wiring, and the GINI AI tutor with Explain /
+Tutor / Wizard modes. On the roadmap: configuring services from the inspector, VPC-level
+isolation, a managed Kubernetes element, and more Wizard recipes.
+
+---
+
+## License & contact
+
+GINI is free software — see `COPYING` for copyright information. Questions, bugs, or ideas:
+open an issue on this repository, or email `maheswar@cs.mcgill.ca`.

gini_core-0.1.0/README.md

@@ -0,0 +1,305 @@
+# GINI — gBuilder 6.0
+
+**A visual lab for computer networks, cloud computing, *and* operating systems — draw a system, press Run, and it comes to life as real containers (and a real xv6 kernel) you can inspect, drive, and observe.**
+
+💬 **Join the community:** [GINI Discord](https://discord.gg/s5zTAgdKQd) — questions, help, and discussion.
+
+GINI lets students and instructors build a topology on a canvas, then launches it as
+honest, running infrastructure on Docker: a real C router that actually forwards packets,
+a real OpenFlow controller programming a real switch, and real cloud services (databases,
+object stores, message queues, dashboards) discoverable by name — plus a real **xv6** operating-system
+kernel you can watch and extend in a visual **Machine Lab**. A built-in AI tutor —
+**GINI** — explains what's on the canvas, animates how packets flow, and can scaffold
+whole working systems from a one-line description.
+
+It's designed to anchor three courses:
+
+- **Computer Networks** — switches, routers, subnets, firewalls, and real OpenFlow SDN.
+- **Cloud Computing** — VPC-style networking, managed services, autoscaling, observability.
+- **Operating Systems** — a real **xv6** (RISC-V) kernel in a visual **Machine Lab**: watch the
+  scheduler, system calls, traps, virtual memory, and the file system live, then extend the kernel
+  yourself with **shadows** — a novel way to drop your own code into a *running* xv6 machine to
+  experiment (fix the scheduler, add a syscall) without forking the kernel.
+
+> gBuilder 6.0 is the modern rewrite of the classic GINI Toolkit. The original
+> Python 2.7 / PyQt4 / SCons app lives under `legacy/` for reference.
+
+---
+
+## Highlights
+
+- **Visual builder** — a fast PySide6/Qt 6 canvas with a searchable palette of ~40
+  networking and cloud elements, theming, save/load, and an inspector.
+- **It actually runs** — Run compiles the canvas to a Docker Compose project and brings it
+  up. Machines, routers, switches, controllers, and cloud services all start as containers.
+- **The real C gRouter** — the genuine GINI router (built with `zig cc`), forwarding
+  packets over a portable user-space fabric. No kernel modules, no privileges.
+- **Real SDN** — drop an *OpenFlow Controller* + *OpenVSwitch*; GINI runs **POX** (Python 3)
+  programming the gRouter in OpenFlow-1.0 switch mode. Watch flows install on the first
+  packet, then forward at wire speed.
+- **Cloud services as containers** — MinIO, PostgreSQL, Redis, MongoDB, RabbitMQ, Kafka
+  (Redpanda), NATS, nginx, Traefik, Prometheus, Grafana, Jaeger, Fortio, and more — each a
+  real, off-the-shelf image reachable by service name.
+- **Live observability** — drop *Metrics* + *Dashboards* and GINI auto-wires
+  cAdvisor → Prometheus → Grafana with a prebuilt dashboard. Generate load and watch the
+  graphs move.
+- **A real OS to hack** — a genuine **xv6** kernel in a visual **Machine Lab** (scheduler, system
+  calls, traps, virtual memory, file system — all live over the serial, no gdb), plus **shadows**:
+  drop your own code into a running xv6 machine for experiments and graded assignments, no kernel
+  fork required.
+- **GINI AI** — an in-app tutor with **Explain**, **Tutor**, and **Wizard** modes. Ask it
+  to explain a device, trace a path, or describe a system you want and it lays out a
+  working blueprint. Runs against a local LLM (Ollama) or fully offline.
+
+---
+
+## Requirements
+
+- **Python 3.10+** (3.12 recommended). The Qt 6 GUI — **PySide6** plus **QtWebEngine** (for the
+  embedded Desktop / OS-Zoo screens) — installs **automatically** as a dependency; you never install
+  Qt separately, whichever install route you pick.
+- A **container runtime** — Docker, or **Colima**/**Podman** (`gini-setup` detects it and can help
+  install it) — needed to *Run* topologies. You can explore fully in **Demo mode** without one.
+- Works on **macOS, Linux, and Windows**. *Optional:* a local **[Ollama](https://ollama.com)** model
+  for richer GINI AI answers.
+
+---
+
+## Install
+
+There are **two ways to install, both fully supported** — pick one (don't mix the two; see
+Troubleshooting). Either way the Qt GUI (PySide6 + QtWebEngine) is pulled in automatically.
+
+### 1. From source — the latest code
+
+Recommended if you want the newest features, plan to build the xv6 kernel image yourself, or want to
+contribute. You track `main`, so you always have the freshest bits.
+
+```bash
+# in your clone of the repo:
+cd frontend-ng
+pip install -e .              # editable install; PySide6 + QtWebEngine come with it
+gini-setup                    # brings in the container runtime + images (one time)
+gbuilder                      # launch
+```
+
+### 2. Pre-compiled package — the simplest, most stable
+
+The hands-off route. It may be a version or two behind `main`, but it's the more stable, "just
+install and go" option — good for students and classroom setups.
+
+```bash
+pipx install gini-toolkit     # the app, isolated. `pip install gini-toolkit` also works.
+gini-setup                    # brings in the container runtime + images (one time)
+gbuilder                      # launch
+```
+
+Either way, `gbuilder` opens immediately — build, save, and explore topologies, with the AI tutor and
+everything in **Demo mode** working right away. Live **Run** (real containers) lights up once
+`gini-setup` finishes. After upgrading (`git pull` for source, or `pipx upgrade gini-toolkit` for the
+package), re-run `gini-setup --update` to refresh images.
+
+> No `pipx`? Install it once (`brew install pipx` on macOS, or `pip install pipx`), or use
+> `pip install gini-toolkit` inside a virtual environment.
+
+<details>
+<summary><b>macOS details</b></summary>
+
+`gini-setup` uses **Colima** — a free, lightweight Docker runtime, no Docker Desktop license needed.
+On a clean Mac with [Homebrew](https://brew.sh) it offers to run:
+
+```bash
+brew install colima docker
+colima start --cpu 2 --memory 4 --disk 30
+```
+
+If Docker Desktop (or Colima) is already running, `gini-setup` detects it and just pulls the images.
+</details>
+
+<details>
+<summary><b>Linux details</b></summary>
+
+Install **Docker Engine** first — it needs `sudo`, so `gini-setup` guides rather than auto-installs:
+
+```bash
+# https://docs.docker.com/engine/install/ for your distro, then:
+sudo usermod -aG docker $USER      # log out / back in afterwards
+```
+
+Podman works too. Then run `gini-setup` to pull the images.
+</details>
+
+<details>
+<summary><b>Windows details</b></summary>
+
+Colima isn't available on Windows — use **Docker Desktop** or **Podman Desktop**:
+
+```powershell
+winget install -e --id Docker.DockerDesktop
+```
+
+Start it, then run `gini-setup`. (Live-Run networking on Windows is still being validated;
+Demo mode works fully.)
+</details>
+
+<details>
+<summary><b>Dev tools & building images locally</b></summary>
+
+```bash
+# extra dev tooling (tests, linters) on top of the source install:
+cd frontend-ng && pip install -e ".[dev]"
+
+# build the container images yourself instead of pulling them
+# (needed to hack the xv6 kernel via shadows):
+docker build -t gini-xv6:latest backend/xv6      # + oszoo / grouter / pox
+```
+
+Point the app at a different image registry with `GINI_REGISTRY=ghcr.io/<owner>`.
+</details>
+
+<details>
+<summary><b>Troubleshooting</b></summary>
+
+- **"runtime not set up yet"** — run `gini-setup`. Demo mode still works without it.
+- **`gini-setup` pull says `denied` / `not found`** — images unreachable: check your network, or that
+  the registry (`ghcr.io/gini-toolkit`) is correct and its packages are public.
+- **Two `gbuilder`s on your PATH** — you installed with both pip *and* pipx; keep one
+  (`pip uninstall gini-toolkit` or `pipx uninstall gini-toolkit`).
+</details>
+
+---
+
+### Your first topology
+
+- **Place** a device by dragging it from the palette onto the canvas.
+- **Connect** two devices: click the **Connect** tool in the toolbar (the link icon), then
+  click the first device and then the second — a link appears. Click the tool again (or
+  press Esc) to leave Connect mode. You can also ask GINI: "connect R1 and S1".
+- **Run** the topology with the ▶ button.
+
+Once it's running:
+
+- **Double-click** a machine to open a shell; a service with a web UI (Grafana, MinIO …)
+  to open its dashboard; a router to open the **Router Lab**.
+- **Right-click** any node for **Open console**, **Log in**, **View logs**, or **Delete**.
+- The console log prints each running service's web URL.
+
+---
+
+## GINI AI
+
+The right-hand **Ask GINI** panel is a teaching assistant that always sees the live canvas.
+Modes are toggle buttons; the toolbar shows the current **mode** and whether GINI is
+**thinking**.
+
+- **Explain** — click any device and GINI explains it on the canvas (spotlight, callouts,
+  animated packet flows). It also explains palette elements ("when do I use a switch vs a
+  hub?").
+- **Tutor** — overlays highlights and animations as it teaches.
+- **Wizard** — describe what you want ("something I can watch under load", "a web app with
+  a database") and GINI matches a curated, guaranteed-to-work **recipe** and lays it out
+  with one click. The model only *selects and explains*; the building is deterministic, so
+  even a small local model can't produce a broken topology.
+
+Connect a model by pointing GINI at Ollama:
+
+```bash
+export GINI_LLM_URL=http://localhost:11434
+export GINI_LLM_MODEL=llama3.1        # or gemma, qwen, …
+python -m gini
+```
+
+Without a model, GINI still builds, inspects, traces paths, and ranks recipes
+deterministically.
+
+---
+
+## Software-Defined Networking
+
+The SDN stack is the original GINI design, made real:
+
+- **OpenVSwitch** element → the gRouter launched in `--openflow` mode (a real OpenFlow 1.0
+  switch).
+- **OpenFlow Controller** element → a **POX** (`gar`, Python 3) container running an app
+  you choose from the inspector (`l2_learning`, `hub`, or the classic `of_tutorial`).
+
+Draw `Controller → OVS → hosts`, Run, and ping between hosts: the first packet misses the
+flow table → goes up to POX → a flow is installed → the rest forward in the datapath. You
+can watch flows appear with `openflow entry all` in the OVS console, and the controller's
+decisions in its logs.
+
+---
+
+## Cloud service catalog
+
+Each of these palette elements runs as a real container, reachable by name on the lab's
+network (cloud-style service discovery):
+
+| Element | Backed by | Console |
+|---|---|---|
+| Object Storage | MinIO | ✓ |
+| Managed Database | PostgreSQL | — |
+| NoSQL Database | MongoDB | — |
+| Cache | Redis | — |
+| Message Queue | RabbitMQ | ✓ |
+| Event Stream | Redpanda (Kafka API) | — |
+| Pub/Sub | NATS | ✓ |
+| Reverse Proxy | Traefik | ✓ |
+| Load Balancer | nginx | — |
+| Web App | nginxdemos/hello | ✓ |
+| Container Registry | registry:2 | — |
+| Metrics | Prometheus | ✓ |
+| Dashboards | Grafana | ✓ |
+| Tracing | Jaeger | ✓ |
+| Load Generator | Fortio | ✓ |
+
+Compute elements (**Instance**, **Container**) run as plain containers on the same network,
+so a program inside them reaches services by name (`psql -h database1`,
+`http://objectstore1:9000`).
+
+---
+
+## Repository layout
+
+```
+frontend-ng/        gBuilder 6.0 — PySide6 app (domain · ui · agent · runtime · services)
+backend/
+  src/grouter/      the real C gRouter (~20k lines) incl. OpenFlow/SDN mode
+  grouter-build/      C build + Dockerfile (gini-grouter) + e2e forwarding tests
+  sdn/              POX (gar) controller + Dockerfile (gini-pox)
+legacy/             the original Python 2.7 / PyQt4 GINI, kept for reference
+ARCHITECTURE.md     what's active vs legacy, and how it fits together
+```
+
+See **[ARCHITECTURE.md](ARCHITECTURE.md)** for the full map.
+
+---
+
+## Testing
+
+```bash
+cd frontend-ng
+pytest                                   # ~95 tests
+# headless / CI:
+QT_QPA_PLATFORM=offscreen pytest
+```
+
+The gRouter has end-to-end forwarding proofs under `backend/grouter-build/tests/`
+(`forward_test.py`, `multihop_test.py`, …), runnable against a built `grouter` binary.
+
+---
+
+## Status
+
+gBuilder 6.0 is under active development. Working today: the visual builder, real packet
+forwarding through the C gRouter (single- and multi-router), OpenFlow SDN (POX + gRouter),
+the cloud service catalog, observability auto-wiring, and the GINI AI tutor with Explain /
+Tutor / Wizard modes. On the roadmap: configuring services from the inspector, VPC-level
+isolation, a managed Kubernetes element, and more Wizard recipes.
+
+---
+
+## License & contact
+
+GINI is free software — see `COPYING` for copyright information. Questions, bugs, or ideas:
+open an issue on this repository, or email `maheswar@cs.mcgill.ca`.

gini_core-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gini-core"
+dynamic = ["version"]
+description = "GINI core domain model — topology, devices, and the proof-of-activity format"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "GINI Toolkit" }]
+# Pure Python and deliberately tiny: this is the code the desktop app and the Teaching Center must
+# agree on — the proof chain, the ticket codes, the narration — so it has to install anywhere,
+# including a headless server VM with no Qt and no compiler.
+#
+# PyYAML is here because `gini.domain.fragment_yaml` and `gini.domain.lesson` genuinely need it.
+# Declaring zero dependencies looked cleaner and was a lie: `pip install gini-core` would have
+# given you a package whose own modules raise ImportError. It is a universal wheel and about a
+# thousandth of what Qt would have cost.
+dependencies = ["PyYAML>=6.0"]
+
+[project.urls]
+Homepage = "https://github.com/citelab/gini"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["gini.domain*"]
+
+[tool.setuptools.package-data]
+"gini.domain" = ["missions/**/*.yaml"]
+
+[tool.setuptools_scm]
+root = ".."
+version_file = "src/gini/_version.py"
+local_scheme = "no-local-version"

gini_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gini_core-0.1.0/src/gini/domain/__init__.py

@@ -0,0 +1,9 @@
+"""Pure-Python domain model — no Qt dependency."""
+from . import devices, topology
+from .devices import Category, DeviceType, REGISTRY, all_devices, by_category, get
+from .topology import DeviceInstance, Link, Topology
+
+__all__ = [
+    "devices", "topology", "Category", "DeviceType", "REGISTRY",
+    "all_devices", "by_category", "get", "DeviceInstance", "Link", "Topology",
+]