multi_llm_chatbot_backend/app/models/README.md

app/models – Data Models & Persona Configuration

This module defines the core data structures for users, chat sessions, and AI advisor personas in the Multi-LLM Chatbot Backend.

It plays a foundational role in ensuring that:

• User data and session state are structured, validated, and serializable
• Persona behavior is configurable, injectable, and extensible

---

Persona Model (persona.py)

class Persona

Represents a single AI advisor with its own personality, tone, and domain of expertise.

Attribute	Description
id	Unique identifier for the persona
name	Human-readable display name
system_prompt	The persona’s default LLM instruction
llm	Instance of the LLM client (Gemini/Ollama)
temperature	Controls creativity level (0–10 scale, converted to 0.0–1.0 internally)

respond() method

This asynchronous method generates a persona-specific reply using the provided context and desired response_length (short, medium, long). It uses a system prompt + user messages + length-based instructions.

await persona.respond(context=messages, response_length="medium")

---

Persona Registry (default_personas.py)

Defines and registers all built-in personas using detailed system_prompt templates and metadata.

These prompts define the tone, response style, formatting rules, document behavior, and epistemological approach of each advisor.

Available Personas

• methodologist: Research methods and design expert
• theorist: Theoretical frameworks and philosophy of science
• pragmatist: Action-oriented coach with a focus on task execution
• socratic: Socratic questioning mentor
• motivator: Psychology-focused coach to build momentum
• critic: Constructive reviewer with sharp academic critique
• storyteller: Communication and storytelling specialist
• minimalist: Minimal guidance, maximum clarity
• visionary: Long-term strategy and innovation
• empathetic: Emotionally aware advisor for mental health & motivation

Registry Functions

Function	Description
get_default_personas(llm)	Returns a list of Persona instances with LLM injected
get_default_persona_prompt(pid)	Returns only the system_prompt of a persona
is_valid_persona_id(pid)	Checks if ID exists in registry
list_available_personas()	Lists all persona IDs

---

User & Session Models (user.py)

UserCreate / UserLogin

Pydantic models for request payloads during signup/login.

User

Persistent user object, mapped to MongoDB using _id aliasing.

Field	Description
id (_id)	MongoDB ObjectId
email, hashed_password	Auth fields
academicStage, researchArea	Optional metadata
created_at, last_login	Timestamps
is_active	Soft-deletion or block flag

UserResponse

Serialized user profile returned to frontend after login/token validation.

---

ChatSession

Stores a single multi-turn conversation. Used for RAG context, memory, and export.

Field	Description
id	MongoDB _id
user_id	Owner user’s ID
title	Human-readable title
messages	List of exchanged messages
created_at, updated_at	Session lifecycle tracking
is_active	Whether it is a deleted/inactive session

ChatSessionResponse

Returned when listing past sessions (lightweight response).

---

Token

Used as the unified login response structure:

{
  "access_token": "...",
  "token_type": "bearer",
  "user": { ... }
}

---

Design Principles

• All models are fully compatible with FastAPI + Pydantic
• MongoDB integration uses bson.ObjectId support and aliases
• Persona logic is decoupled from orchestration — easy to extend
• System prompts are rich, structured, and frontend-format aware (markdown rules enforced)

---

Next Steps

This module is used by:

• core/improved_orchestrator.py – Persona routing
• routes/chat.py – Sequential chat + replies
• auth.py – Token generation and validation
• documents.py – Document-enhanced message generation

Add a new persona? Just extend DEFAULT_PERSONAS and restart the backend.