Dynavera/README.md

# Dynavera: An Agentic Approach to Role-Specific Trainers

[![Vue 3](https://img.shields.io/badge/Vue-35495E?style=for-the-badge&logo=vue.js&logoColor=4FC08D)](https://vuejs.org/)
[![Vite](https://img.shields.io/badge/Vite-646CFF?style=for-the-badge&logo=vite&logoColor=white)](https://vite.dev/)
[![Django](https://img.shields.io/badge/Django-092E20?style=for-the-badge&logo=django&logoColor=white)](https://www.djangoproject.com/)
[![DRF](https://img.shields.io/badge/DRF-092E20?style=for-the-badge&logo=django&logoColor=white)](https://www.django-rest-framework.org/)
[![Channels](https://img.shields.io/badge/Django_Channels-092E20?style=for-the-badge&logo=django&logoColor=white)](https://channels.readthedocs.io/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge&logo=postgresql&logoColor=white)](https://www.postgresql.org/)
[![pgvector](https://img.shields.io/badge/pgvector-00599C?style=for-the-badge&logo=postgresql&logoColor=white)](https://github.com/pgvector/pgvector)
[![Redis](https://img.shields.io/badge/Redis-DC382D?style=for-the-badge&logo=redis&logoColor=white)](https://redis.io/)
[![Celery](https://img.shields.io/badge/Celery-37814A?style=for-the-badge&logo=celery&logoColor=white)](https://docs.celeryq.dev/en/stable/)
[![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)

Dynavera is a distributed agentic onboarding platform designed to solve the productivity gap in organizational training. The motivation was to create a system that delivers tailored, retrieval-grounded guidance for new roles, leveraging modern AI and orchestration techniques. This project was built to address the challenge of scalable, role-specific onboarding—where generic training fails to meet the needs of specialized positions. By combining curriculum generation, document-grounded retrieval, and live progress tracking, Dynavera enables organizations to onboard users efficiently and transparently. Through this project, I learned how to architect distributed systems, integrate retrieval-augmented generation, and design agent workflows for real-world impact.

## Table of Contents

- [Overview](#overview)
- [Core Features](#core-features)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Usage & Smoke Test](#usage--smoke-test)
- [Project Structure](#project-structure)
- [Demo Access](#demo-access)
- [Operational Commands](#operational-commands)
- [Screenshots](#screenshots)
- [Documentation](#documentation)



## Overview & Core Features

Dynavera addresses the onboarding productivity gap by combining:

- Role-aware curriculum generation
- Retrieval-augmented responses grounded in uploaded organizational documents
- Tool-aware orchestration over WebSockets
- Local-first inference support for privacy-sensitive deployments

The runtime is intentionally distributed: Django manages state and governance, while a dedicated inference service handles model-intensive workloads.

Key features:

- Distributed architecture separating application control plane and inference plane
- Multi-agent style orchestration for curriculum, knowledge, assessment, and monitoring behaviors
- RAG pipeline with semantic chunking, embeddings, and pgvector retrieval
- Live onboarding session updates via Django Channels WebSockets
- Persistent session/progress storage for auditability and recovery

## Architecture

High-level architecture diagram:

![High Level System Architecture](docs/high-level-system-architecture.png)

Key backend runtime entry points:

- `apps/onboarding/consumers.py` for orchestration loop and WebSocket flow
- `apps/onboarding/mcp.py` for tool routing and backend tool execution
- `apps/knowledge/tasks.py` for ingestion/chunking/embedding workflow
- `gpu_server.py` for inference and embedding endpoints

## Quick Start

Prerequisites:

- Docker Engine or Docker Desktop
- NVIDIA drivers and NVIDIA Container Toolkit (for GPU inference)

1. Clone repository

```bash
git clone https://git.cs.bham.ac.uk/projects-2025-26/vxn217
cd vxn217
```

2. Create environment file

PowerShell:

```powershell
Copy-Item .env.template .env
```

CMD:

```cmd
copy .env.template .env
```

macOS/Linux:

```bash
cp .env.template .env
```

3. Start development stack

```bash
docker compose -f compose/dev/docker-compose.yml --env-file .env up -d --build
```

4. Open application

- http://localhost:8000

## Usage/Smoke Test

Follow this end-to-end workflow to use the project and to run the smoke test:

1. Create or select an organization and role
2. Upload role-specific training files
3. Wait for ingestion and embedding to complete (monitor the ingestion UI or logs)
4. Invite a user to the configured role
5. Log in as that user and start onboarding
6. Complete at least one guided interaction and one assessment action

Expected behaviour:

- Workflow completes without manual page refresh
- UI state transitions update live
- No dropped WebSocket session during onboarding

## Project Structure

- `apps/accounts` user, organization, and role membership logic
- `apps/knowledge` training file ingestion and vector document persistence
- `apps/onboarding` sessions, orchestration runtime, and tool integration
- `config` Django settings, routing, ASGI/WSGI wiring
- `compose` development and production container configuration
- `site` frontend application
- `docs` architecture and deployment documentation

## Demo Access

Hosted URL:

- https://fyp.viswamedha.com

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`

## Operational 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
```

Reset seeded passwords:

```bash
docker exec -it fyp-django-dev python manage.py reset_passwords
```

## Screenshots

Home:

![Home Page](docs/images/home-page.png)

Organization:

![Organization Page](docs/images/organization-page.png)

Onboarding generation state:

![Onboarding Loading](docs/images/onboarding-loading-page.png)

Onboarding content flow:

![Onboarding Flow](docs/images/onboarding-content-page.png)

## Documentation

- [Distributed Runtime Flow](docs/distributed-runtime-flow.md)
- [Application Structure](docs/application-structure.md)
- [Deployment Topologies](docs/deployment-topologies.md)