From 8d1de81e4745d14c1895bcb8cd70068e38064740 Mon Sep 17 00:00:00 2001 From: rafa-ruiz Date: Wed, 11 Feb 2026 00:41:39 -0800 Subject: [PATCH] update --- README.md | 233 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 130 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index e1d8eb3..d246749 100644 --- a/README.md +++ b/README.md @@ -8,127 +8,154 @@ This project is a strategic joint development: --- -## System Architecture +## System Architecture (Hybrid Dev Mode) -The following diagram illustrates the interaction between the AVAP technology, the trained intelligence, and the infrastructure components: +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_Dev [Laptop Ivar/Rafael] - BE[Brunix Assistance Engine] - KT[Kubectl Tunnel] + subgraph Local_Workstation [Developer] + BE[Brunix Assistance Engine - Docker] + KT[Kubectl Port-Forward Tunnels] end - subgraph Vultr_K8s_Cluster [Production - Vultr Cloud] - EDB[(Elasticsearch Vector DB - HDD)] - PG[(Postgres - System Data)] - LF[Langfuse UI] + 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:9200/5432 --> KT - KT -- Secure Tunnel --> EDB - KT -- Secure Tunnel --> PG - BE -- Public IP --> LF + 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 ``` --- -## Technology Stack +## Project Structure -* **Logic Layer:** [LangChain](https://www.langchain.com/) & [LangGraph](https://langchain-ai.github.io/langgraph/) (Python 3.11). -* **Communication:** [gRPC](https://grpc.io/) (High-performance, low-latency RPC framework). -* **Vector Database:** [Elasticsearch 8.12](https://www.elastic.co/) (For semantic search and AVAP data retrieval). -* **Observability:** [Langfuse](https://langfuse.com/) (End-to-end tracing, latency monitoring, and cost management). -* **Infrastructure:** Dockerized environment with PostgreSQL 15 persistence. +```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 +``` --- -## Getting Started +## Data Flow & RAG Orchestration -### Prerequisites -* Docker & Docker Compose -* OpenAI API Key (or configured local provider) - -### Installation & Deployment - -1. **Clone the repository:** - ```bash - git clone git@github.com:BRUNIX-AI/assistance-engine.git - cd assistance-engine - ``` - -2. **Configure Environment Variables:** - Create a `.env` file in the root directory: - ```env - OPENAI_API_KEY=your_key_here - LANGFUSE_PUBLIC_KEY=pk-lf-... - LANGFUSE_SECRET_KEY=sk-lf-... - LANGFUSE_HOST=http://langfuse:3000 - ``` - -3. **Launch the Stack:** - ```bash - docker-compose up -d --build - ``` - -The engine will be listening for gRPC requests on port `50052`. - ---- - -## Component Overview - -| Service | Container Name | Description | Role | -| :--- | :--- | :--- | :--- | -| **Engine** | `brunix-assistance-engine` | The AVAP-powered brain. | 101OBEX Corp | -| **Vector DB** | `brunix-vector-db` | Elasticsearch instance (Knowledge Base). | Training Support | -| **Observability** | `brunix-observability` | Langfuse UI (Tracing & Costs). | System Quality | -| **System DB** | `brunix-postgres` | Internal storage for Langfuse. | Infrastructure | - ---- - -## Partnership & Contributions - -This repository is private and represents the intellectual property of **101OBEX Corp** and **MrHouston**. - -* **Architecture & AVAP:** Managed by 101OBEX Engineering. -* **Model Training & Intelligence:** Managed by MrHouston Data Science Team. - ---- - -## Open Source & Intellectual Property - -The Brunix Assistance Engine is built on a hybrid architecture that balances the flexibility of open-source tools with the security of proprietary intelligence: - -* **Open Source Frameworks:** Utilizes **LangChain** and **LangGraph** (MIT License) for orchestration, and **gRPC** for high-performance communication. -* **Infrastructure:** Deploys via **Docker** using **PostgreSQL** and **Elasticsearch** (Elastic License 2.0). -* **Proprietary Logic:** The **AVAP Technology** (101OBEX Corp) and the specific **Model Training/Prompts** (MrHouston) are protected intellectual property. -* **LLM Provider:** Currently configured for **OpenAI** (Proprietary SaaS). The modular design allows for future integration with locally-hosted Open Source models (e.g., Llama 3, Mistral) to ensure 100% data sovereignty if required. - -## Security & Privacy - -The system is designed with a "Security-First" approach to protect corporate intelligence: - -1. **Data in Transit:** Communication between the Engine and external clients is handled via **gRPC**, supporting **TLS/SSL encryption** to ensure that data remains private and tamper-proof. -2. **Internal Networking:** All database interactions (Elasticsearch, PostgreSQL) occur within a **private Docker bridge network** (`avap-network`), isolated from the public internet. -3. **Observability Governance:** **Langfuse** provides a full audit trail of every LLM interaction, allowing for real-time monitoring of data leakage or unexpected model behavior. -4. **Enterprise Secret Management:** While local development uses `.env` files, the architecture is **Production-Ready for Kubernetes**. In production environments, sensitive credentials (API Keys, Database passwords) are managed via **Kubernetes Secrets** or **HashiCorp Vault**, ensuring that no sensitive data is stored within the container images or source control. +The following diagram illustrates the sequence of a single `AskAgent` request, detailing the retrieval and generation phases through the secure tunnel. ```mermaid -graph LR - subgraph Public_Internet - Client[External Client] - end - subgraph Encrypted_Tunnel [TLS/SSL] - gRPC[gRPC Protocol] - end - subgraph K8s_Cluster [Production Environment] - Engine[Brunix Engine] - Sec{{"Kubernetes Secrets"}} - DB[(Databases)] +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 - Client --> gRPC - gRPC --> Engine - Sec -.->|Injected as Env| Engine - Engine <--> DB -``` \ No newline at end of file + 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 & +``` + +### 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. + +--- \ No newline at end of file