240 lines
6.2 KiB
Markdown
240 lines
6.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)
|
|
- [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
|
|
|
|
Placeholder slots for final 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)
|
|
|
|
---
|
|
|
|
## 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)
|