Python Service Overview

Relevant source files

The following files were used as context for generating this wiki page:

• backend/app.py
• backend/services/ai_service.py
• backend/routes/ai_routes.py
• backend/modules/ml/routes.py
• backend/modules/ml/gemini_model.py
• backend/services/chat_service.py
• README.md

The Python Service serves as the core intelligence engine for the AI Assistant platform. Operating as a Flask-based REST API on port 5000, it encapsulates all Machine Learning (ML) functionalities, including local LLM inference via Phi-3, integration with the Google Gemini API, intent detection, sentiment analysis, and vector embedding generation. Sources: README.md, backend/app.py:12-25

This service is decoupled from the primary database (MongoDB), which is managed by the Node.js Auth & Orchestration Service. Instead, it functions as a stateless processing layer that receives conversation history and retrieved memories as input to generate context-aware responses and extract structured facts. Sources: README.md, backend/routes/ai_routes.py:11-40

Service Architecture and Components

The service is structured around specialized modules and services that handle different aspects of the AI pipeline. The AIService acts as the primary orchestrator, delegating tasks to specific model wrappers or ML utilities. Sources: backend/app.py:19-21, backend/services/chat_service.py:14-25

Core Components

Component	Responsibility	File Path
Flask Application	Entry point, route definitions, and CORS handling.	backend/app.py
AIService	Orchestrates text generation across local and API models.	backend/services/ai_service.py
GeminiModel	Wrapper for Google's Generative AI API integration.	backend/modules/ml/gemini_model.py
Phi3Model	Manages local inference using the Phi-3 Mini GGUF model.	backend/modules/ml/phi3_model.py
EmbeddingService	Generates 384-dimensional vector embeddings for RAG.	backend/services/embedding_service.py
MLService	Provides utilities for intent, sentiment, and summarization.	backend/modules/ml/routes.py

The following diagram illustrates the internal request flow within the Python Service:

AI Generation Pipeline

The generation process involves taking user prompts, conversation context (typically the last 10 messages), and retrieved memories to produce a coherent response. The service supports two primary backends:

1. Phi-3: A local, privacy-focused model using llama-cpp-python.
2. Gemini: An advanced API-based model for complex reasoning.

Sources: backend/app.py:48-60, backend/modules/ml/gemini_model.py:15-35, README.md

API Endpoints

POST /generate

The primary endpoint for text generation. It processes the prompt and returns the AI response along with detected intent and sentiment.

Parameter	Type	Description
prompt	String	The current user message.
model	String	Choice of 'phi3' or 'gemini' (default: 'phi3').
context	Array	List of previous message objects (role/text).
memories	Array	List of relevant facts retrieved from the vector store.

Sources: backend/app.py:44-78, backend/routes/ai_routes.py:11-30

Machine Learning Utilities

Beyond text generation, the service provides discrete endpoints for analyzing text properties and preparing data for Retrieval-Augmented Generation (RAG).

Intent and Sentiment Analysis

The MLService and ChatService utilize specialized modules to classify user input. Intent detection identifies commands, questions, or notes, while sentiment analysis determines if a message is positive, negative, or neutral. Sources: backend/modules/ml/routes.py:10-50, backend/services/chat_service.py:38-50

Vector Embeddings

The EmbeddingService generates numerical representations of text. These 384-dimensional vectors are used by the Node.js service to perform cosine similarity searches against the memory database. Sources: backend/app.py:102-118, README.md

Memory Extraction

The MemoryExtractionService is responsible for identifying significant facts within a conversation. When a user sends a message, the service analyzes the text to extract "memory candidates"—facts that have an importance score and associated tags. Sources: backend/app.py:80-95, backend/routes/ai_routes.py:65-95

Memory Candidate Structure

{
  "fact": "User prefers dark mode for the interface",
  "importanceScore": 0.8,
  "tags": ["preference", "ui"]
}

Sources: backend/routes/ai_routes.py:75-80

Technical Summary

The Python Service is a specialized ML worker that abstracts the complexities of local LLM management and external AI APIs. By providing a standardized REST interface for generation, embedding, and analysis, it allows the rest of the system to remain agnostic of the specific ML implementation details. Sources: README.md, backend/app.py:134-140