diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..77c52c5 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/README.md b/README.md index 7c60965..5cfbafe 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/LANGUAGE-BOUNDARIES.md b/docs/LANGUAGE-BOUNDARIES.md index 8ab6c42..ab8cbc4 100644 --- a/docs/LANGUAGE-BOUNDARIES.md +++ b/docs/LANGUAGE-BOUNDARIES.md @@ -6,9 +6,9 @@ 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 @@ -16,12 +16,11 @@ every repository into one implementation language. - `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 diff --git a/docs/LOCAL-DEPENDENCY-INVENTORY.md b/docs/LOCAL-DEPENDENCY-INVENTORY.md index bf95b0d..ab8fcd2 100644 --- a/docs/LOCAL-DEPENDENCY-INVENTORY.md +++ b/docs/LOCAL-DEPENDENCY-INVENTORY.md @@ -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`. @@ -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 | @@ -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.