Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Repository instructions

This repository is the Go control plane for the Edge-Computing-LLM organization.
Keep Layer 1 (`k3s-nvidia-edge`) and Layer 2 (`llm-observability-stack`)
ownership explicit. Do not embed application services, Helm templates, model
weights, credentials, or arbitrary model-generated shell execution here.

Before completing a change run `gofmt`, `go test ./...`, `go vet ./...`, and
`go build -o /tmp/edge ./cmd/edge`. Mutating cluster operations must retain
dry-run behavior and require `--yes`. Never log Secrets or kubeconfig content.
7 changes: 3 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,9 @@ a read-only evidence companion for the deployed Qwen runtime. It consumes the
status produced by these layers; `edge-cli` does not install it as another
cluster layer.

[`Frontend-Edge-LLM-Observability`](https://github.com/Edge-Computing-LLM/Frontend-Edge-LLM-Observability)
is the TypeScript/Vue presentation companion. It is also outside the ordered
cluster lifecycle and consumes controlled metrics endpoints rather than direct
host or Kubernetes credentials.
Dashboard presentation is owned by the Helm-provisioned Grafana dashboards in
`llm-observability-stack`; there is no separate browser repository or
browser-side Kubernetes credential path.

The CLI supports automatic NVIDIA/CPU selection. It does not currently install
AMD, Intel, or Apple Silicon accelerator runtimes.
Expand Down
15 changes: 7 additions & 8 deletions docs/LANGUAGE-BOUNDARIES.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,21 @@ every repository into one implementation language.
| Language or format | Use it for | Do not use it for |
|---|---|---|
| Go | Durable CLIs, install/uninstall workflows, validation gates, typed configuration, command execution, and cross-repository orchestration | Browser UI or one-off data analysis |
| Python 3.11 | Structured evidence, benchmarks, API services, notebooks, Kubernetes reporting, and test tooling | Host package installation or a second deployment control plane |
| Python | Optional Jupyter learning material only | Deployed services, host validation, benchmarks, evidence collection, or a second control plane |
| Bash | Short transparent wrappers around Helm, kubectl, container image import, and workshop command sequences | Growing business logic, complex parsing, persistent state, or duplicated Go workflows |
| TypeScript/Vue | Browser dashboards, typed frontend models, chart interaction, and client-side Prometheus parsing | Direct privileged Kubernetes access or host orchestration |
| Grafana JSON | Reproducible dashboard presentation provisioned by Helm | Direct privileged Kubernetes access or host orchestration |
| Helm/YAML | Declarative Kubernetes resources and deployment profiles | Imperative host installation logic |

## Repository mapping

- `edge-cli`: Go only for product behavior; Make and YAML remain build/CI glue.
- `k3s-nvidia-edge`: Go for infrastructure workflows and Helm/YAML for the GPU
Operator profile.
- `llm-observability-stack`: Helm/YAML for resources, Go for its legacy/helper
CLI, Python 3.11 for application/benchmark/diagnostic code, and Bash only for
thin local operator wrappers.
- `qwen-gguf-observability`: dependency-free Python 3.11 for structured,
read-only evidence collection.
- `Frontend-Edge-LLM-Observability`: Vue 3 and TypeScript for the browser.
- `llm-observability-stack`: Helm/YAML for resources and Go for its helper CLI,
gateway, toolbox, benchmark, Kubernetes inspection, telemetry, and tests.
- `qwen-gguf-observability`: dependency-free Go for structured, read-only
evidence collection.
- Grafana JSON in `llm-observability-stack`: browser presentation.

New deployable repositories require a clear ownership boundary. A new
repository should not be created merely to move an existing script to another
Expand Down
11 changes: 5 additions & 6 deletions docs/LOCAL-DEPENDENCY-INVENTORY.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ lockfiles, generated package metadata, and documentation.
| Infrastructure | `Edge-Computing-LLM/k3s-nvidia-edge` | Install or validate k3s and, conditionally, NVIDIA Container Toolkit, GPU Operator, RuntimeClass, device plugin, and DCGM. |
| Application | `Edge-Computing-LLM/llm-observability-stack` | Deploy CPU- or GPU-profiled Ollama, Open WebUI, OpenTelemetry, Prometheus, and Grafana workloads. |
| Evidence | `Edge-Computing-LLM/qwen-gguf-observability` | Validate the live Qwen runtime contract and capture sanitized evidence without owning cluster resources. |
| Dashboard | `Edge-Computing-LLM/Frontend-Edge-LLM-Observability` | Present LLM, Kubernetes, and accelerator telemetry. |
| Dashboard | Grafana JSON in `Edge-Computing-LLM/llm-observability-stack` | Present LLM, Kubernetes, and accelerator telemetry through Helm provisioning. |

The NVIDIA infrastructure layer is conditional. CPU hosts skip its GPU-specific
components and deploy the application layer with `values.cpu-k3s.yaml`.
Expand Down Expand Up @@ -59,8 +59,7 @@ instead.
| Kubernetes | `kubernetes/kubernetes` | Released k3s/Kubernetes binaries and APIs |
| NVIDIA | `NVIDIA/k8s-dra-driver-gpu` | Reference/documentation; the current platform uses the device plugin and GPU Operator path |
| Metrics | `prometheus/prometheus`, `prometheus/alertmanager`, `prometheus/node_exporter`, `prometheus/blackbox_exporter`, `kubernetes/kube-state-metrics`, `grafana/grafana` | Vendored Helm charts and released images |
| Python service | `fastapi/fastapi`, `encode/uvicorn`, `pydantic/pydantic`, `langchain-ai/langchain`, `encode/httpx`, `prometheus/client_python` | Pinned Python 3.11 packages in `langchain-demo/requirements.txt` |
| Frontend | `ag-grid/ag-grid`, `primefaces/primevue`, `primefaces/primeicons`, `vuejs/core`, `ecomfe/vue-echarts`, `tailwindlabs/tailwindcss`, `vitejs/vite` | Locked npm packages; `apache/echarts` is already local |
| Go telemetry | `prometheus/client_golang`, `open-telemetry/opentelemetry-go` | Versioned Go modules used by the Ollama gateway and edge toolbox |
| Tika | `apache/tika`, `apache/tika-docker` | Released chart/image; `apache/tika-helm` is local |
| Documentation tooling | `norwoodj/helm-docs`, `helm-unittest/helm-unittest` | Optional development tooling |

Expand All @@ -77,12 +76,12 @@ boundary.
clean, current clone is sufficient.
- The NVIDIA DRA repository referenced as `NVIDIA/k8s-dra-driver-gpu` is distinct
from the locally available `kubernetes-sigs/dra-driver-nvidia-gpu`.
- `Frontend-Edge-LLM-Observability` is the actual organization repository name;
use that case in documentation and remotes.
- The former standalone frontend was retired; Grafana dashboard JSON is the
organization-owned presentation source.

## Audit method

The inventory combined Git remote enumeration for every `.git` worktree with
repository URL extraction, Go module files, Helm `Chart.yaml`/`Chart.lock`, Python
requirements, npm lock metadata, CI workflows, and runtime manifests from all five
requirements, npm lock metadata, CI workflows, and runtime manifests from all four
organization projects. Credentials and generated build output were excluded.