Skip to main content
This guide walks you through setting up the Justina AI System on your local machine or server.

​
Prerequisites

Before beginning, ensure you have:

Python 3.9+

Required for running the AI service

pip or venv

Package manager for installing dependencies

Backend Running

The Spring Boot backend must be accessible

Network Access

Connection to backend API (default: localhost:8080)
Python 3.9 or higher is required due to type hints and dictionary merge operators used in the code.

​
Installation Steps

1

Clone the Repository

First, clone the Justina repository and navigate to the AI directory:
git clone https://github.com/No-Country-simulation/S02-26-Equipo-24-Web-App-Development.git
cd S02-26-Equipo-24-Web-App-Development/ia
2

Create Virtual Environment

Create and activate a Python virtual environment:
python3 -m venv venv
source venv/bin/activate
Using a virtual environment isolates dependencies and prevents conflicts with system packages.
3

Install Dependencies

Install all required Python packages:
pip install -r requirements.txt
This installs:
  • requests: HTTP client for API calls
  • pandas: Data manipulation
  • numpy: Numerical computations
  • python-dotenv: Environment variable management
  • websocket-client: Real-time backend communication
  • flask: Optional REST API server
4

Configure Environment

Create a .env file in the ia/ directory:
config.py
BASE_URL=http://localhost:8080
IA_USERNAME=ia_justina
IA_PASSWORD=ia_secret_2024
REQUEST_TIMEOUT=10
RETRY_ATTEMPTS=3
Or modify config.py directly:
config.py
import os
from dotenv import load_dotenv

load_dotenv()

BASE_URL = os.getenv("BASE_URL", "http://localhost:8080")
IA_USERNAME = os.getenv("IA_USERNAME", "ia_justina")
IA_PASSWORD = os.getenv("IA_PASSWORD", "ia_secret_2024")
REQUEST_TIMEOUT = int(os.getenv("REQUEST_TIMEOUT", "10"))
RETRY_ATTEMPTS = int(os.getenv("RETRY_ATTEMPTS", "3"))
5

Verify Backend Connection

Test that the backend is accessible:
curl http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"ia_justina","password":"ia_secret_2024"}'
Expected response:
{
  "username": "ia_justina",
  "role": "ROLE_IA"
}

​
Running the AI Service

The AI system can operate in two modes:

​
1. Manual Mode (main.py)

Interactive CLI for processing individual surgeries: 
python main.py
Features:
  • Interactive menu system
  • Process single surgery by UUID
  • Batch processing capability
  • Manual authentication
When to use: Testing, debugging, or one-off analysis

​
2. WebSocket Mode (websocket_client.py)

Automated service that listens for backend notifications: 
python websocket_client.py
Features:
  • Automatic authentication
  • Real-time surgery notifications
  • Automatic analysis and submission
  • Reconnection on failure
When to use: Production deployment, continuous operation
WebSocket mode is recommended for production as it automatically processes surgeries as they complete.

​
Configuration Options

​
Backend URL

If your backend runs on a different host or port: 
BASE_URL = "http://192.168.1.100:8080"  # Remote server
BASE_URL = "https://api.justina.com"    # Production with HTTPS

​
Authentication

The default AI credentials are:
  • Username: ia_justina
  • Password: ia_secret_2024
  • Role: ROLE_IA
Change these credentials in production! Update both the backend user and the AI config.

​
Timeouts and Retries

REQUEST_TIMEOUT = 10      # Seconds to wait for API response
RETRY_ATTEMPTS = 3        # Number of retries on failure
Increase timeout for slow networks or large trajectory datasets.

​
Testing the Setup

​
Quick Test

Run a test with sample data: 
python test_pipeline_local.py
This tests the analysis pipeline without requiring backend connectivity.

​
End-to-End Test

  1. Start the backend
  2. Run the AI service: 
    python main.py
  3. Choose option 2 (batch processing)
  4. Verify analysis completes successfully

​
Troubleshooting

Ensure you’ve activated the virtual environment and run pip install -r requirements.txt.
source venv/bin/activate  # Activate venv
pip install -r requirements.txt
The backend isn’t running. Start it first:
cd ../backend
./mvnw spring-boot:run
Invalid credentials. Verify IA_USERNAME and IA_PASSWORD match the backend’s default AI user.
Check that:
  1. Backend WebSocket endpoint is enabled
  2. JWT token is valid
  3. Firewall allows WebSocket connections
  4. URL uses ws:// not http://

​
Production Deployment

For production environments:
1

Use a Process Manager

Run the AI service with systemd or supervisor:
/etc/systemd/system/justina-ai.service
[Unit]
Description=Justina AI Analysis Service
After=network.target

[Service]
Type=simple
User=justina
WorkingDirectory=/opt/justina/ia
Environment="PATH=/opt/justina/ia/venv/bin"
ExecStart=/opt/justina/ia/venv/bin/python websocket_client.py
Restart=always

[Install]
WantedBy=multi-user.target
Enable and start:
sudo systemctl enable justina-ai
sudo systemctl start justina-ai
2

Configure Logging

Add logging to track analysis results:
import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('justina-ai.log'),
        logging.StreamHandler()
    ]
)
3

Set Up Monitoring

Monitor the AI service health:
# Check status
systemctl status justina-ai

# View logs
journalctl -u justina-ai -f

​
Next Steps

Client Usage

Learn how to use the JustinaAIClient class

API Integration

Understand the WebSocket notification system

Build docs developers (and LLMs) love

Get started for freeTalk to us