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: Infrastructure, System Architecture, and the proprietary AVAP Technology stack.
• MrHouston: 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.

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

├── README.md                     # System documentation & Dev guide
├── changelog                     # Version tracking and release history
├── pyproject.toml                # Python project configuration
├── Docker/
│   ├── Dockerfile                # Container definition for the Engine
│   ├── docker-compose.yaml       # Local orchestration for dev environment
│   ├── requirements.txt           # Python dependencies for Docker
│   ├── protos/
│   │   └── brunix.proto          # Protocol Buffers: The source of truth for the API
│   └── src/
│       ├── graph.py              # Workflow graph orchestration
│       ├── prompts.py            # Centralized prompt definitions
│       ├── server.py             # gRPC Server & RAG Orchestration
│       ├── state.py              # Shared state management
│       └── utils/                # Utility modules
├── ingestion/
│   └── docs/                     # AVAP documentation chunks
├── kubernetes/
│   └── kubeconfig.yaml           # Kubernetes cluster configuration
├── scripts/
│   └── pipelines/
│       └── flows/                # Data processing flows
└── src/
    ├── __init__.py
    └── utils/
        ├── emb_factory.py        # Embedding model factory
        ├── llm_factory.py        # LLM model factory
        └── __init__.py

---

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.

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 using the reference table below.

3. Environment Variables Reference

Policy: Every environment variable used by the engine must be documented in this table. Any PR that introduces a new variable without a corresponding entry here will be rejected. See CONTRIBUTING.md for full details.

Create a .env file in the project root with the following variables:

ELASTICSEARCH_URL=http://host.docker.internal:9200
ELASTICSEARCH_LOCAL_URL=http://localhost:9200
ELASTICSEARCH_INDEX=avap-docs-test
POSTGRES_URL=postgresql://postgres:postgres@localhost:5432/langfuse
LANGFUSE_HOST=http://45.77.119.180
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
OLLAMA_URL=http://host.docker.internal:11434
OLLAMA_LOCAL_URL=http://localhost:11434
OLLAMA_MODEL_NAME=qwen2.5:1.5b
OLLAMA_EMB_MODEL_NAME=qwen3-0.6B-emb:latest

Variable	Required	Description	Example
ELASTICSEARCH_URL	Yes	Elasticsearch endpoint used for vector/context retrieval in Docker	http://host.docker.internal:9200
ELASTICSEARCH_LOCAL_URL	Yes	Elasticsearch endpoint used for vector/context retrieval in local	http://localhost:9200
ELASTICSEARCH_INDEX	Yes	Elasticsearch index name used by the engine	avap-docs-test
POSTGRES_URL	Yes	PostgreSQL connection string used by the service	postgresql://postgres:postgres@localhost:5432/langfuse
LANGFUSE_HOST	Yes	Langfuse server endpoint (Devaron Cluster)	http://45.77.119.180
LANGFUSE_PUBLIC_KEY	Yes	Langfuse project public key for tracing and observability	pk-lf-...
LANGFUSE_SECRET_KEY	Yes	Langfuse project secret key	sk-lf-...
OLLAMA_URL	Yes	Ollama endpoint used for text generation/embeddings in Docker	http://host.docker.internal:11434
OLLAMA_LOCAL_URL	Yes	Ollama endpoint used for text generation/embeddings in local	http://localhost:11434
OLLAMA_MODEL_NAME	Yes	Ollama model name for generation	qwen2.5:1.5b
OLLAMA_EMB_MODEL_NAME	Yes	Ollama embeddings model name	qwen3-0.6B-emb:latest

Never commit real secret values. Use placeholder values when sharing configuration examples.

4. Infrastructure Tunnels

Open a terminal and establish the connection to the Devaron Cluster:

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

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

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

5. Launch the Engine

docker-compose up -d --build

---

Testing & Debugging

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

Streaming Query Example

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:

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

---

Repository Standards & Architecture

Docker & Build Context

To maintain production-grade security and image efficiency, this project enforces a strict separation between development files and the production runtime:

• Production Root: All executable code must reside in the /app directory within the container.
• Exclusions: The root /workspace directory is deprecated. No development artifacts, local logs, or non-essential source files (e.g., .git, tests/, docs/) should be bundled into the final image.
• Compliance: All Pull Requests must verify that the Dockerfile context is optimized using the provided .dockerignore.

Failure to comply with these architectural standards will result in PR rejection.

For the full set of contribution standards, see CONTRIBUTING.md.

---

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.

---