Python API Reference

Relevant source files

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

• backend/routes/ai_routes.py
• backend/modules/chat/routes.py
• backend/modules/ml/routes.py
• backend/app.py
• backend/modules/ml/gemini_model.py
• README.md

The Python AI Service serves as the computational core of the AI Assistant platform, providing specialized Machine Learning (ML) capabilities via a Flask-based REST API. It is responsible for high-level tasks including local inference with Phi-3, integration with the Google Gemini API, intent detection, sentiment analysis, and vector embedding generation.

Operating on port 5000, this service functions as a stateless execution layer. It receives requests primarily from the Node.js Auth & Orchestration service, processes natural language data using various ML models, and returns structured JSON responses containing generated text and analytical metadata.

Sources: README.md:16-25, backend/app.py:105-106

Core API Infrastructure

The application is built using the Flask framework and utilizes a modular Blueprint-based routing system. This allows for separation of concerns between core AI generation, chat-specific utilities, and general machine learning analysis.

The diagram above illustrates the routing architecture where requests are dispatched to specialized Blueprints and then handled by dedicated service classes.
Sources: backend/app.py:16-26, backend/routes/ai_routes.py:6-8, backend/modules/ml/routes.py:5-6

Service Endpoints Summary

Endpoint	Method	Description	Source File
/health	GET	Basic service health check and status.	backend/app.py:40
/generate	POST	Generates AI response with context and memories.	backend/app.py:44
/extract-memory	POST	Extracts factual statements from text input.	backend/app.py:84
/embed	POST	Generates 384-dimensional vector embeddings.	backend/app.py:100
/similarity	POST	Calculates cosine similarity between two vectors.	backend/app.py:116

AI Generation and Model Integration

The AI generation logic supports dual-model capabilities, allowing the system to switch between a local Phi-3 model and the cloud-based Google Gemini API.

Generation Logic Flow

When a /generate request is received, the service prepares the message history and incorporates retrieved memories to provide context-aware responses.

Gemini Integration

The GeminiModel class manages the lifecycle of the Google Generative AI client, including initialization with API keys and prompt formatting.

• Initialization: Configures genai with model_name, temperature, top_p, and max_tokens.
• Prompt Construction: Merges system instructions, conversation history (last 5 messages), and the current user message into a single formatted string.
• Safety: Provides fallback responses if the API is uninitialized or an error occurs during generation.

Sources: backend/modules/ml/gemini_model.py:19-43, backend/modules/ml/gemini_model.py:82-113

Machine Learning Modules

The /ml routes provide specialized analysis tools that can be used independently of the conversational generation flow.

Intent and Sentiment Analysis

The system identifies the "intent" behind user messages (e.g., question, command, note) and the "sentiment" (positive, negative, neutral).

Parameter	Type	Required	Description
text	String	Yes	Input text for analysis.
messages	Array	Yes (for /analyze)	List of strings representing a conversation.

Sources: backend/modules/ml/routes.py:10-58, backend/app.py:73-77

Text Summarization

The /summarize endpoint utilizes the MLService to condense long text into a specified number of sentences.
Sources: backend/modules/ml/routes.py:65-94

Vector Embedding and Similarity

The EmbeddingService enables the "memory" feature of the platform by converting text into numerical vectors and performing mathematical comparisons.

• Embedding Generation: Converts input text into a 384-dimensional vector using sentence-transformers.
• Similarity Computation: Computes the similarity between two embeddings, typically used to retrieve the most relevant memories for a given user query.

# Implementation Reference from backend/app.py
@app.route('/embed', methods=['POST'])
def generate_embedding():
    data = request.json
    text = data.get('text')
    embedding = embedding_service.generate_embedding(text)
    return send_success({'embedding': embedding, 'dimension': 384})

Sources: backend/app.py:100-114, backend/app.py:116-128

Chat Management (Legacy/Internal)

The chat_bp (defined in backend/modules/chat/routes.py) provides routes for message validation, cleaning, and history management. While the primary orchestration is handled by the Node.js service, these endpoints support local debugging and direct AI interaction.

• POST /send: Validates and cleans input, processes the message via chat_service, and returns the AI response.
• GET /history: Retrieves stored messages with optional user filtering and limits (max 200).
• POST /model: Switches the active model between phi3 and gemini.

Sources: backend/modules/chat/routes.py:11-54, backend/modules/chat/routes.py:63-87, backend/modules/chat/routes.py:145-171

The Python API serves as a robust backend for intelligent operations, abstracting complex ML model interactions into simple, versioned RESTful endpoints used by the rest of the stack.