docs: Update for decomposed repo structure

- AGENT-ONBOARDING: New repo map with daviestechlabs Gitea repos
- TECH-STACK: Reference handler-base instead of llm-workflows
- CODING-CONVENTIONS: Update project structure for new repos
- ADR 0006: Update GitRepository examples for Gitea repos

llm-workflows has been split into:
- handler-base, chat-handler, voice-assistant
- kuberay-images, argo, kubeflow, mlflow, gradio-ui
This commit is contained in:
2026-02-02 05:58:35 -05:00
parent 832cda34bd
commit b6f7605fab
4 changed files with 95 additions and 37 deletions

View File

@@ -15,9 +15,21 @@ You are working on a **homelab Kubernetes cluster** running:
| Repo | What It Contains | When to Edit |
|------|------------------|--------------|
| `homelab-k8s2` | Kubernetes manifests, Talos config, Flux | Infrastructure changes |
| `llm-workflows` | NATS handlers, Argo/KFP workflows | Workflow/handler changes |
| `companions-frontend` | Go server, HTMX UI, VRM avatars | Frontend changes |
| `homelab-design` (this) | Architecture docs, ADRs | Design decisions |
| `companions-frontend` | Go server, HTMX UI, VRM avatars | Frontend changes |
### AI/ML Repos (git.daviestechlabs.io/daviestechlabs)
| Repo | Purpose |
|------|---------|
| `handler-base` | Shared Python library for NATS handlers |
| `chat-handler` | Text chat with RAG pipeline |
| `voice-assistant` | Voice pipeline (STT → RAG → LLM → TTS) |
| `kuberay-images` | GPU-specific Ray worker Docker images |
| `argo` | Argo Workflows (training, batch inference) |
| `kubeflow` | Kubeflow Pipeline definitions |
| `mlflow` | MLflow integration utilities |
| `gradio-ui` | Gradio demo apps (embeddings, STT, TTS) |
## 🏗️ System Architecture (30-Second Version)
@@ -74,22 +86,39 @@ talos/
│ └── nvidia/nvidia-runtime.yaml
```
### Workflows (`llm-workflows`)
### AI/ML Services (Gitea daviestechlabs org)
```
workflows/ # NATS handler deployments
├── chat-handler.yaml
├── voice-assistant.yaml
└── pipeline-bridge.yaml
handler-base/ # Shared handler library
├── handler_base/ # Core classes
│ ├── handler.py # Base Handler class
│ ├── nats_client.py # NATS wrapper
│ └── clients/ # Service clients (STT, TTS, LLM, etc.)
chat-handler/ # RAG chat service
├── chat_handler_v2.py # Handler-base version
└── Dockerfile.v2
voice-assistant/ # Voice pipeline service
├── voice_assistant_v2.py # Handler-base version
└── pipelines/voice_pipeline.py
argo/ # Argo WorkflowTemplates
├── document-ingestion.yaml
├── batch-inference.yaml
── qlora-training.yaml
── qlora-training.yaml
└── document-ingestion.yaml
pipelines/ # Kubeflow Pipeline Python
kubeflow/ # Kubeflow Pipeline definitions
├── voice_pipeline.py
── document_ingestion_pipeline.py
── document_ingestion_pipeline.py
└── evaluation_pipeline.py
kuberay-images/ # GPU worker images
├── dockerfiles/
│ ├── Dockerfile.ray-worker-nvidia
│ ├── Dockerfile.ray-worker-strixhalo
│ └── Dockerfile.ray-worker-rdna2
└── ray-serve/ # Serve modules
```
## 🔌 Service Endpoints (Internal)
@@ -138,14 +167,24 @@ f"ai.pipeline.status.{request_id}" # Status updates
### Deploy a New AI Service
1. Create InferenceService in `homelab-k8s2/kubernetes/apps/ai-ml/kserve/`
2. Add endpoint to `llm-workflows/config/ai-services-config.yaml`
2. Push to main → Flux deploys automatically
### Add a New NATS Handler
1. Create handler repo or add to existing (use `handler-base` library)
2. Add K8s Deployment in `homelab-k8s2/kubernetes/apps/ai-ml/`
3. Push to main → Flux deploys automatically
### Add a New Workflow
### Add a New Argo Workflow
1. Create handler in `llm-workflows/chat-handler/` or `llm-workflows/voice-assistant/`
2. Add Kubernetes Deployment in `llm-workflows/workflows/`
3. Push to main → Flux deploys automatically
1. Add WorkflowTemplate to `argo/` repo
2. Push to main → Gitea syncs to cluster
### Add a New Kubeflow Pipeline
1. Add pipeline .py to `kubeflow/` repo
2. Compile with `python pipeline.py`
3. Upload YAML to Kubeflow UI
### Create Architecture Decision