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
|
||||
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
|
||||
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.
|
||||
|
||||
---
|
||||
Loading…
Reference in New Issue