255 lines
7.2 KiB
Markdown
255 lines
7.2 KiB
Markdown
# Dynavera: Distributed Agentic Onboarding System
|
|
|
|
Dynavera is a multi-agent onboarding platform that combines role-specific training flows, retrieval from organization documents, and LLM-powered guidance. The system is intentionally distributed so that app orchestration and heavy inference can run independently.
|
|
|
|
Repository: https://git.cs.bham.ac.uk/projects-2025-26/vxn217
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
- [At a Glance](#at-a-glance)
|
|
- [Inspector & Supervisor Notes](#inspector--supervisor-notes)
|
|
- [Screenshots](#screenshots)
|
|
- [System Architecture (High-Level)](#system-architecture-high-level)
|
|
- [Project Goals](#project-goals)
|
|
- [Tech Stack](#tech-stack)
|
|
- [Repository Guide](#repository-guide)
|
|
- [Notable Branches](#notable-branches)
|
|
- [Evaluation Credentials](#evaluation-credentials)
|
|
- [Recommended Evaluation Walkthrough](#recommended-evaluation-walkthrough)
|
|
- [Local Setup (Cross-Platform)](#local-setup-cross-platform)
|
|
- [Common Commands](#common-commands)
|
|
- [Additional Documentation](#additional-documentation)
|
|
|
|
---
|
|
|
|
## At a Glance
|
|
|
|
Dynavera focuses on one question: **how do we deliver onboarding that is role-aware, context-aware, and operationally practical?**
|
|
|
|
The platform does this by combining:
|
|
|
|
- A Django management layer for accounts, roles, sessions, and APIs
|
|
- An agentic orchestration loop over WebSockets for responsive interactions
|
|
- A retrieval layer using pgvector and organization-provided documents
|
|
- A GPU inference service for chat completions, embeddings, and chunking support
|
|
|
|
---
|
|
|
|
## Inspector & Supervisor Notes
|
|
|
|
Primary locations relevant to technical quality, architecture reasoning, and evaluation:
|
|
|
|
- Setup, context, and high-level flow: this `README.md`
|
|
- Architecture notes: `docs/`
|
|
- Orchestration runtime: `apps/onboarding/consumers.py`
|
|
- Retrieval bridge and tool routing: `apps/onboarding/mcp.py`
|
|
- Ingestion and vectorization pipeline: `apps/knowledge/tasks.py`
|
|
- Inference service entrypoint: `gpu_server.py`
|
|
|
|
Evaluation-relevant themes represented in the codebase:
|
|
|
|
- Role-scoped onboarding generation and progression
|
|
- Retrieval grounding through uploaded training files
|
|
- Separation of management services and inference services
|
|
- End-to-end flow from upload to onboarding completion
|
|
|
|
---
|
|
|
|
## Screenshots
|
|
|
|
### Home Page
|
|
|
|
|
|
|
|
### Organization Page
|
|
|
|
|
|
|
|
### Onboarding Loading / Generation State
|
|
|
|
|
|
|
|
### Onboarding Content Flow
|
|
|
|
|
|
|
|
---
|
|
|
|
## System Architecture (High-Level)
|
|
|
|
At a high level, Dynavera is split into a management side and an inference side. The orchestrator coordinates user interaction, tool calls, and model responses between the two.
|
|
|
|
|
|
|
|
For the fuller architecture narrative (runtime flow and component placement), see:
|
|
|
|
- [Distributed Runtime Flow](docs/distributed-runtime-flow.md)
|
|
|
|
---
|
|
|
|
## Project Goals
|
|
|
|
- [x] Distributed orchestration across VPS and GPU nodes
|
|
- [x] Context-aware onboarding with RAG (semantic chunking + vector search)
|
|
- [x] Stateful agent workflow over WebSockets
|
|
- [x] Automated ingestion from role training documents (PDF/TXT)
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Django, Django REST Framework, Django Channels
|
|
- **Frontend**: Vue 3, Vite, Pinia
|
|
- **Database**: PostgreSQL with pgvector
|
|
- **AI/ML**: FastAPI, Sentence Transformers, llama.cpp-compatible serving
|
|
- **Infra**: Docker, Redis, Celery
|
|
|
|
---
|
|
|
|
## Repository Guide
|
|
|
|
Key areas in the repo:
|
|
|
|
- `apps/accounts`: user model, organization/role ownership, membership flows
|
|
- `apps/knowledge`: file ingestion, chunking pipeline, vector document persistence
|
|
- `apps/onboarding`: role flows, sessions, websocket orchestration, MCP-style tool routing
|
|
- `config/`: settings, API/ASGI routing, environment wiring
|
|
- `compose/`: development and production deployment manifests
|
|
- `gpu_server.py`: inference and embedding service
|
|
|
|
For a more detailed breakdown:
|
|
|
|
- [Application Structure (Detailed)](docs/application-structure.md)
|
|
|
|
---
|
|
|
|
## Notable Branches
|
|
|
|
These remote branches are useful for understanding how the project evolved:
|
|
|
|
- `origin/main`: stable integration branch used for the current baseline.
|
|
- `origin/feature/node-setup`: early full-stack setup work introducing the initial frontend/backend server shape.
|
|
- `origin/feature/agents`: branch focused on agent-related backend changes, including pgvector-oriented database work.
|
|
- `origin/feature/mcp-workflow`: workflow iteration branch around MCP/testing flow changes.
|
|
- `origin/feature/model-rag`: branch associated with the model/RAG stream and related frontend scaffolding during that phase.
|
|
|
|
Run `git branch -r` to view all remote branches.
|
|
|
|
However, the main branch will be the primary focus as a lot of the code contained in the feature branches was used for testing different approaches and iterations, which then got consolidated or removed as the project evolved. The code in these branches may not be in a fully working state, and some of the approaches explored there were ultimately not used in the final implementation.
|
|
|
|
---
|
|
|
|
## Evaluation Credentials
|
|
|
|
| Role | Email | Password |
|
|
| :--- | :--- | :--- |
|
|
| **Admin** | admin@example.com | admin |
|
|
| **Manager** | haleisaac@example.com | password |
|
|
| **User** | j.thompson@example.com | password |
|
|
|
|
Manager registration code: `MANAGER2026`
|
|
|
|
---
|
|
|
|
## Recommended Evaluation Walkthrough
|
|
|
|
1. Open https://fyp.viswamedha.com
|
|
2. Log in as **Manager** and open the target organization
|
|
3. Upload a role-relevant document (PDF recommended)
|
|
4. Wait for ingestion and embedding completion
|
|
5. Start role onboarding and trigger generation
|
|
6. Check if responses are grounded in uploaded material
|
|
7. Optionally review progress details and logs
|
|
|
|
If the hosted deployment is unavailable, local setup is documented below.
|
|
|
|
---
|
|
|
|
## Local Setup (Cross-Platform)
|
|
|
|
### Prerequisites
|
|
|
|
- Docker Engine / Docker Desktop
|
|
- NVIDIA drivers + NVIDIA Container Toolkit (for GPU inference)
|
|
|
|
### 1) Clone
|
|
|
|
```bash
|
|
git clone https://git.cs.bham.ac.uk/projects-2025-26/vxn217
|
|
cd vxn217
|
|
```
|
|
|
|
### 2) Create `.env`
|
|
|
|
**PowerShell**
|
|
|
|
```powershell
|
|
Copy-Item .env.template .env
|
|
```
|
|
|
|
**CMD**
|
|
|
|
```cmd
|
|
copy .env.template .env
|
|
```
|
|
|
|
**macOS/Linux**
|
|
|
|
```bash
|
|
cp .env.template .env
|
|
```
|
|
|
|
Then update `.env` values for your environment.
|
|
|
|
### 3) Start services (development)
|
|
|
|
```bash
|
|
docker compose -f compose/dev/docker-compose.yml --env-file .env up -d --build
|
|
```
|
|
|
|
### 4) Access endpoints
|
|
|
|
- App: http://localhost:8000
|
|
|
|
### 5) Optional: reset seeded passwords
|
|
|
|
```bash
|
|
docker exec -it fyp-django-dev python manage.py reset_passwords
|
|
```
|
|
|
|
Reset defaults:
|
|
|
|
- Admin users: `admin`
|
|
- Manager and user accounts: `password`
|
|
|
|
---
|
|
|
|
## Common Commands
|
|
|
|
Stop services:
|
|
|
|
```bash
|
|
docker compose -f compose/dev/docker-compose.yml --env-file .env down
|
|
```
|
|
|
|
Tail logs:
|
|
|
|
```bash
|
|
docker compose -f compose/dev/docker-compose.yml --env-file .env logs -f
|
|
```
|
|
|
|
Run migrations:
|
|
|
|
```bash
|
|
docker exec -it fyp-django-dev python manage.py migrate
|
|
```
|
|
|
|
---
|
|
|
|
## Additional Documentation
|
|
|
|
- [Distributed Runtime Flow](docs/distributed-runtime-flow.md)
|
|
- [Application Structure (Detailed)](docs/application-structure.md)
|
|
- [Deployment Topologies](docs/deployment-topologies.md)
|