assistance-engine/README.md

# Brunix Assistance Engine

The **Brunix Assistance Engine** is a high-performance, gRPC-powered AI orchestration service. It serves as the core intelligence layer for the Brunix ecosystem, integrating advanced RAG (Retrieval-Augmented Generation) capabilities with real-time observability.

This project is a strategic joint development:
* **[101OBEX Corp](https://101obex.com):** Infrastructure, System Architecture, and the proprietary **AVAP Technology** stack.
* **[MrHouston](https://mrhouston.net):** Advanced LLM Fine-tuning, Model Training, and Prompt Engineering.

---

## System Architecture (Hybrid Dev Mode)

The engine runs locally for development but connects to the production-grade infrastructure in the **Vultr Cloud (Devaron Cluster)** via secure `kubectl` tunnels.

```mermaid
graph TD
    subgraph Local_Workstation [Developer]
        BE[Brunix Assistance Engine - Docker]
        KT[Kubectl Port-Forward Tunnels]
    end
    
    subgraph Vultr_K8s_Cluster [Production - Devaron Cluster]
        OL[Ollama Light Service - LLM]
        EDB[(Elasticsearch Vector DB)]
        PG[(Postgres - Langfuse Data)]
        LF[Langfuse UI - Web]
    end

    BE -- localhost:11434 --> KT
    BE -- localhost:9200 --> KT
    BE -- localhost:5432 --> KT
    
    KT -- Secure Link --> OL
    KT -- Secure Link --> EDB
    KT -- Secure Link --> PG
    
    Developer -- Browser --> LF
```

---

## Project Structure

```text
.
├── Dockerfile              # Container definition for the Engine
├── README.md               # System documentation & Dev guide
├── changelog               # Version tracking and release history
├── docker-compose.yaml     # Local orchestration for dev environment
├── protos/
│   └── brunix.proto        # Protocol Buffers: The source of truth for the API
└── src/
    └── server.py           # Core Logic: gRPC Server & RAG Orchestration
```

---

## Data Flow & RAG Orchestration

The following diagram illustrates the sequence of a single `AskAgent` request, detailing the retrieval and generation phases through the secure tunnel.

```mermaid
sequenceDiagram
    participant U as External Client (gRPCurl/App)
    participant E as Brunix Engine (Local Docker)
    participant T as Kubectl Tunnel
    participant V as Vector DB (Vultr)
    participant O as Ollama Light (Vultr)

    U->>E: AskAgent(query, session_id)
    Note over E: Start Langfuse Trace
    
    E->>T: Search Context (Embeddings)
    T->>V: Query Index [avap_manuals]
    V-->>T: Return Relevant Chunks
    T-->>E: Contextual Data
    
    E->>T: Generate Completion (Prompt + Context)
    T->>O: Stream Tokens (qwen2.5:1.5b)
    
    loop Token Streaming
        O-->>T: Token
        T-->>E: Token
        E-->>U: gRPC Stream Response {text, avap_code}
    end

    Note over E: Close Langfuse Trace
```



---

## Development Setup

### 1. Prerequisites
* **Docker & Docker Compose**
* **gRPCurl** (`brew install grpcurl`)
* **Access Credentials:** Ensure the file `./ivar.yaml` (Kubeconfig) is present in the root directory.

### 2. Observability Setup (Langfuse)
The engine utilizes Langfuse for end-to-end tracing and performance monitoring.
1.  Access the Dashboard: **http://45.77.119.180**
2.  Create a project and generate API Keys in **Settings**.
3.  Configure your local `.env` file:

```env
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=http://45.77.119.180
```

### 3. Infrastructure Tunnels
Open a terminal and establish the connection to the Devaron Cluster:

```bash
# 1. AI Model Tunnel (Ollama)
kubectl port-forward svc/ollama-light-service 11434:11434 -n brunix --kubeconfig ./ivar.yaml &

# 2. Knowledge Base Tunnel (Elasticsearch)
kubectl port-forward svc/brunix-vector-db 9200:9200 -n brunix --kubeconfig ./ivar.yaml &

# 3. Observability DB Tunnel (PostgreSQL)
kubectl port-forward svc/brunix-postgres 5432:5432 -n brunix --kubeconfig ./ivar.yaml &

2nd option

kubectl port-forward --address 0.0.0.0 svc/brunix-vector-db 9200:9200 -n brunix --kubeconfig ./kubernetes/ivar.yaml &

kubectl port-forward --address 0.0.0.0 svc/brunix-postgres 5432:5432 -n brunix --kubeconfig ./kubernetes/ivar.yaml &

kubectl port-forward --address 0.0.0.0 svc/ollama-light-service 11434:11434 -n brunix --kubeconfig ./kubernetes/ivar.yaml &


```



### 4. Launch the Engine
```bash
docker-compose up -d --build
```

---

## Testing & Debugging

The service is exposed on port `50052` with **gRPC Reflection** enabled.

### Streaming Query Example
```bash
grpcurl -plaintext \
  -d '{"query": "Hola Brunix, ¿qué es AVAP?", "session_id": "dev-test-123"}' \
  localhost:50052 \
  brunix.AssistanceEngine/AskAgent
```

---

## API Contract (Protobuf)
To update the communication interface, modify `protos/brunix.proto` and re-generate the stubs:

```bash
python -m grpc_tools.protoc -I./protos --python_out=./src --grpc_python_out=./src ./protos/brunix.proto
```

---

## Security & Intellectual Property
* **Data Privacy:** All LLM processing and vector searches are conducted within a private Kubernetes environment.
* **Proprietary Technology:** This repository contains the **AVAP Technology** stack (101OBEX) and specialized training logic (MrHouston). Unauthorized distribution is prohibited.

---