update
This commit is contained in:
rafa-ruiz
parent
4cf171c8a2
commit
8d1de81e47
231
README.md
231
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
|
```mermaid
|
||||||
graph TD
|
graph TD
|
||||||
subgraph Local_Dev [Laptop Ivar/Rafael]
|
subgraph Local_Workstation [Developer]
|
||||||
BE[Brunix Assistance Engine]
|
BE[Brunix Assistance Engine - Docker]
|
||||||
KT[Kubectl Tunnel]
|
KT[Kubectl Port-Forward Tunnels]
|
||||||
end
|
end
|
||||||
|
|
||||||
subgraph Vultr_K8s_Cluster [Production - Vultr Cloud]
|
subgraph Vultr_K8s_Cluster [Production - Devaron Cluster]
|
||||||
EDB[(Elasticsearch Vector DB - HDD)]
|
OL[Ollama Light Service - LLM]
|
||||||
PG[(Postgres - System Data)]
|
EDB[(Elasticsearch Vector DB)]
|
||||||
LF[Langfuse UI]
|
PG[(Postgres - Langfuse Data)]
|
||||||
|
LF[Langfuse UI - Web]
|
||||||
end
|
end
|
||||||
|
|
||||||
BE -- localhost:9200/5432 --> KT
|
BE -- localhost:11434 --> KT
|
||||||
KT -- Secure Tunnel --> EDB
|
BE -- localhost:9200 --> KT
|
||||||
KT -- Secure Tunnel --> PG
|
BE -- localhost:5432 --> KT
|
||||||
BE -- Public IP --> LF
|
|
||||||
|
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).
|
```text
|
||||||
* **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).
|
├── Dockerfile # Container definition for the Engine
|
||||||
* **Observability:** [Langfuse](https://langfuse.com/) (End-to-end tracing, latency monitoring, and cost management).
|
├── README.md # System documentation & Dev guide
|
||||||
* **Infrastructure:** Dockerized environment with PostgreSQL 15 persistence.
|
├── 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
|
The following diagram illustrates the sequence of a single `AskAgent` request, detailing the retrieval and generation phases through the secure tunnel.
|
||||||
* 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.
|
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
graph LR
|
sequenceDiagram
|
||||||
subgraph Public_Internet
|
participant U as External Client (gRPCurl/App)
|
||||||
Client[External Client]
|
participant E as Brunix Engine (Local Docker)
|
||||||
end
|
participant T as Kubectl Tunnel
|
||||||
subgraph Encrypted_Tunnel [TLS/SSL]
|
participant V as Vector DB (Vultr)
|
||||||
gRPC[gRPC Protocol]
|
participant O as Ollama Light (Vultr)
|
||||||
end
|
|
||||||
subgraph K8s_Cluster [Production Environment]
|
U->>E: AskAgent(query, session_id)
|
||||||
Engine[Brunix Engine]
|
Note over E: Start Langfuse Trace
|
||||||
Sec{{"Kubernetes Secrets"}}
|
|
||||||
DB[(Databases)]
|
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
|
end
|
||||||
|
|
||||||
Client --> gRPC
|
Note over E: Close Langfuse Trace
|
||||||
gRPC --> Engine
|
|
||||||
Sec -.->|Injected as Env| Engine
|
|
||||||
Engine <--> DB
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
---
|
||||||
Loading…
Reference in New Issue