INIT(app): initial setup
- Initialize project structure - Add base application files
This commit is contained in:
261
README.md
Normal file
261
README.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# MAS (Multi-Agent System)
|
||||
|
||||
MAS is a unified UI and orchestration layer for multiple AI agents (similar to ChatGPT, Claude, Gemini), running on your own Kubernetes cluster.
|
||||
|
||||
## 🎯 Architecture
|
||||
|
||||
### Agents
|
||||
- **Claude Code (Orchestrator)**: overall coordinator & DevOps expert
|
||||
- **Qwen Backend**: backend engineer (FastAPI, Node.js)
|
||||
- **Qwen Frontend**: frontend engineer (Next.js, React)
|
||||
- **Qwen SRE**: monitoring & reliability engineer
|
||||
|
||||
### Tech stack
|
||||
- **Backend**: LangGraph + LangChain + FastAPI
|
||||
- **UI**: Chainlit (chat-style UI)
|
||||
- **Database**: PostgreSQL (CNPG)
|
||||
- **Cache**: Redis
|
||||
- **LLMs**: Claude API + **Groq Llama 3.x** (OpenAI-compatible API)
|
||||
- **Deploy**: Kubernetes + ArgoCD
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Local development
|
||||
|
||||
### 1. Run with Docker Compose
|
||||
|
||||
```bash
|
||||
cd deploy/docker
|
||||
|
||||
# Copy or create .env and fill in your API keys
|
||||
# (ANTHROPIC_API_KEY, GROQ_API_KEY, etc.)
|
||||
|
||||
# Start the full stack
|
||||
docker compose up -d
|
||||
|
||||
# Tail logs
|
||||
docker compose logs -f mas
|
||||
```
|
||||
|
||||
Open: `http://localhost:8000`
|
||||
|
||||
### 2. Run backend directly (Python)
|
||||
|
||||
```bash
|
||||
cd services/backend
|
||||
|
||||
# Create venv
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Environment variables
|
||||
cp .env.example .env
|
||||
# Edit .env and set your API keys
|
||||
|
||||
# Run Chainlit app
|
||||
chainlit run chainlit_app.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ☸️ Kubernetes deployment
|
||||
|
||||
### 1. Create namespace and secrets
|
||||
|
||||
```bash
|
||||
kubectl create namespace mas
|
||||
|
||||
kubectl create secret generic mas-api-keys \
|
||||
--from-literal=anthropic-api-key=YOUR_CLAUDE_KEY \
|
||||
--from-literal=openai-api-key=YOUR_OPENAI_KEY \
|
||||
--from-literal=google-api-key=YOUR_GEMINI_KEY \
|
||||
-n mas
|
||||
```
|
||||
|
||||
### 2. Deploy via ArgoCD
|
||||
|
||||
```bash
|
||||
# Create ArgoCD Application
|
||||
kubectl apply -f deploy/argocd/mas.yaml
|
||||
|
||||
# Sync and check status
|
||||
argocd app sync mas
|
||||
argocd app get mas
|
||||
```
|
||||
|
||||
### 3. Deploy from your server (example)
|
||||
|
||||
```bash
|
||||
# SSH into your k3s master
|
||||
ssh oracle-master
|
||||
|
||||
# Apply ArgoCD Application
|
||||
sudo kubectl apply -f /path/to/deploy/argocd/mas.yaml
|
||||
|
||||
# Check status
|
||||
sudo kubectl get pods -n mas
|
||||
sudo kubectl logs -f deployment/mas -n mas
|
||||
```
|
||||
|
||||
Ingress example (if configured): `https://mas.mayne.vcn`
|
||||
|
||||
---
|
||||
|
||||
## 🎨 UI customization
|
||||
|
||||
### Chainlit theme & behavior
|
||||
|
||||
You can customize the UI via `services/backend/.chainlit`:
|
||||
|
||||
```toml
|
||||
[UI]
|
||||
name = "MAS"
|
||||
show_readme_as_default = true
|
||||
default_collapse_content = true
|
||||
```
|
||||
|
||||
### Agent prompts
|
||||
|
||||
System prompts for each agent live in `services/backend/agents.py`.
|
||||
You can tune:
|
||||
- how the **Orchestrator** routes tasks
|
||||
- coding style of backend/frontend agents
|
||||
- SRE troubleshooting behavior
|
||||
|
||||
---
|
||||
|
||||
## 📊 Observability
|
||||
|
||||
### Prometheus ServiceMonitor (example)
|
||||
|
||||
```yaml
|
||||
apiVersion: monitoring.coreos.com/v1
|
||||
kind: ServiceMonitor
|
||||
metadata:
|
||||
name: mas
|
||||
namespace: mas
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: mas
|
||||
endpoints:
|
||||
- port: http
|
||||
path: /metrics
|
||||
```
|
||||
|
||||
### Grafana dashboards
|
||||
|
||||
Recommended panels:
|
||||
- LangGraph workflow metrics
|
||||
- Per-agent latency & error rate
|
||||
- Token usage and cost estimates
|
||||
- Backend API latency & 5xx rate
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Advanced features
|
||||
|
||||
### 1. MCP (Model Context Protocol) with Claude
|
||||
|
||||
Using Claude Code as Orchestrator, MAS can access:
|
||||
- Filesystem (read/write project files)
|
||||
- Git (status, commit, push, PR)
|
||||
- SSH (run remote commands on your servers)
|
||||
- PostgreSQL (schema inspection, migrations, queries)
|
||||
- Kubernetes (kubectl via MCP tool)
|
||||
|
||||
This allows fully automated workflows like:
|
||||
- “Create a new service, add deployment manifests, and deploy to k3s.”
|
||||
- “Debug failing pods and propose a fix, then open a PR.”
|
||||
|
||||
### 2. Multi-agent collaboration (LangGraph)
|
||||
|
||||
Typical workflow:
|
||||
|
||||
```text
|
||||
User request
|
||||
↓
|
||||
Claude Orchestrator
|
||||
↓ decides which agent(s) to call
|
||||
Backend Dev → Frontend Dev → SRE
|
||||
↓
|
||||
Claude Orchestrator (review & summary)
|
||||
↓
|
||||
Final answer to user
|
||||
```
|
||||
|
||||
Examples:
|
||||
- Full‑stack feature (API + UI + monitoring)
|
||||
- Infra rollout (Harbor, Tekton, CNPG, MetalLB) with validation
|
||||
|
||||
---
|
||||
|
||||
## 📝 Usage examples
|
||||
|
||||
### Backend API request
|
||||
|
||||
```text
|
||||
User: "Create a signup API with FastAPI.
|
||||
Use PostgreSQL and JWT tokens."
|
||||
|
||||
🎼 Orchestrator:
|
||||
→ routes to Qwen Backend
|
||||
|
||||
⚙️ Qwen Backend:
|
||||
→ generates FastAPI router, Pydantic models, DB schema, JWT logic
|
||||
|
||||
🎼 Orchestrator:
|
||||
→ reviews, suggests improvements, and outputs final code snippet & file layout
|
||||
```
|
||||
|
||||
### Frontend component request
|
||||
|
||||
```text
|
||||
User: "Build a responsive dashboard chart component using Recharts."
|
||||
|
||||
🎼 Orchestrator:
|
||||
→ routes to Qwen Frontend
|
||||
|
||||
🎨 Qwen Frontend:
|
||||
→ generates a Next.js/React component with TypeScript and responsive styles
|
||||
|
||||
🎼 Orchestrator:
|
||||
→ explains how to integrate it into your existing app
|
||||
```
|
||||
|
||||
### Infra / SRE request
|
||||
|
||||
```text
|
||||
User: "Prometheus is firing high memory alerts for the PostgreSQL pod.
|
||||
Help me stabilize it."
|
||||
|
||||
🎼 Orchestrator:
|
||||
→ routes to Qwen SRE
|
||||
|
||||
📊 Qwen SRE:
|
||||
→ analyzes metrics & logs (conceptually),
|
||||
proposes tuning (Postgres config, indexes, pooler),
|
||||
and suggests alert threshold adjustments.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome:
|
||||
- New agents (e.g., data engineer, security engineer)
|
||||
- New tools (Harbor, Tekton, CNPG, MetalLB integrations)
|
||||
- Better prompts and workflows
|
||||
- Docs and examples
|
||||
|
||||
Feel free to open issues or PRs in your Git repository.
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user