Asistente NEAE - Virtual Educational Support Assistant

A modern web interface to interact with the NEAE Virtual Assistant (Special Educational Support Needs) for Andalucía, designed to provide specialized support for educators and families.

Overview

The NEAE Assistant is an AI-powered virtual assistant that provides specialized support for educational professionals working with students who have Special Educational Support Needs (NEAE) in Andalucía, Spain. It offers guidance on curricular adaptations, specialized resources, inclusive strategies, and educational regulations.

Features

Web Interface

• Real-Time Chat - Instant communication with the NEAE assistant
• Responsive Design - Works perfectly on both mobile and desktop devices
• Modern Interface - Clean and professional design suitable for educational environments
• Loading Indicators - Visual feedback for user interactions
• Automatic Links - Automatic URL detection in responses
• Markdown Support - Rich text formatting in messages
• Connection Status - Real-time server connectivity indicators

Assistant Capabilities

• Secure Authentication - Access control based on API keys
• Session Management - Maintains conversational context
• Error Handling - Comprehensive error management
• AI Integration - Powered by Google Gemini AI
• Specialized Knowledge - Expert guidance on NEAE topics

Quick Start

Prerequisites

Make sure you have Python 3.7+ installed and the following dependencies:

pip install fastapi uvicorn[standard] google-generativeai python-dotenv

1. Start the Server

uvicorn main:app --reload

2. Access the Web Interface

Open your browser and go to: http://127.0.0.1:8000

The interface will automatically redirect you to the chat application.

Project Structure

asistente-neae/
├── main.py                # FastAPI server with chat endpoints
├── user_keys.json         # User keys and usage limits
├── user_keys.example.json # Example key configuration
├── prompt.txt             # System instructions for the assistant
├── .env                   # Environment variables
├── credenciales_google.json # Google credentials
├── frontend/              # Web interface files (SPA)
│   └── static/            # Static assets
│       ├── index.html     # SPA application shell
│       ├── css/
│       │   └── app.css    # CSS styles
│       ├── js/
│       │   ├── router.js  # SPA router
│       │   ├── session.js # Session management
│       │   ├── errorHandler.js # Error handling
│       │   └── config.js  # Frontend configuration
│       └── views/         # SPA views
│           ├── chat/      # Chat view
│           └── login/     # Login view
├── test_setup.py          # Configuration verification script
├── README.md              # This documentation
└── LICENSE                # Project license

Configuration

User Key Configuration

The system uses a user_keys.json file to manage user keys and their usage limits:

1. Create the configuration file:

   cp user_keys.example.json user_keys.json

2. Edit the user keys:

   {
     "your_custom_key": {
       "count": 0,
       "max_uses": 100,
       "user_id": "user1",
       "description": "User description"
     },
     "another_key": {
       "count": 0,
       "max_uses": 50,
       "user_id": "user2",
       "description": "Secondary user"
     }
   }

3. Configuration fields:

   • count: Current usage count (increments automatically)
   • max_uses: Maximum allowed uses per key
   • user_id: Unique user identifier
   • description: Optional user description

4. Reload configuration:

   • Keys are loaded automatically when the server starts
   • To reload without restarting: POST /admin/reload-keys
   • View current status: GET /admin/keys-status

Environment Configuration

Ensure your .env file includes the required Google credentials path:

GOOGLE_APPLICATION_CREDENTIALS_PATH=./credenciales.json

Usage Examples

Start a Conversation

1. Start the server with uvicorn main:app --reload
2. Open http://127.0.0.1:8000 in your browser
3. Type your NEAE-related query
4. Press Enter or click "Send"

Example Queries

• "I need adaptations for a student with ADHD in 3rd grade"
• "What resources are available for students with dyslexia?"
• "How to adapt a math activity for autism"
• "Andalusian regulations on NEAE"

API Endpoints

Authentication

All API requests require an API key in the header:

X-API-Key: your_api_key_here

Available Endpoints

POST /chat/start

Starts a new chat session.

Headers:

X-API-Key: [your_api_key]

Response:

{
  "session_id": "uuid-string",
  "message": "Welcome message"
}

POST /chat/send

Sends a message to the assistant.

Headers:

X-API-Key: [your_api_key]

Body:

{
  "session_id": "uuid-string",
  "question": "Your question here"
}

Response:

{
  "session_id": "uuid-string",
  "answer": "Assistant's response",
  "error": null
}

Special Features

Message Formatting

The assistant automatically formats responses with:

• Section headers with clear titles
• Clickable links for external resources
• Bullet lists for structured information
• Bold text using markdown syntax
• Code blocks for technical examples

Input Validation

• Character limit of 1000 per message
• Session validation to maintain conversation context
• Real-time error handling with user-friendly messages
• Connection monitoring with automatic retry logic

Troubleshooting

Server Issues

Server does not start:

pip install fastapi uvicorn[standard] google-generativeai python-dotenv

Port already in use:

# End process using port 8000
netstat -ano | findstr :8000
# Then use the PID with: taskkill /F /PID [PID_NUMBER]

Web Interface Issues

Connection errors:

• Ensure the server is running on port 8000
• Check that the API key is correctly set in static/config.js
• Open browser developer tools (F12) to check for JavaScript errors

CORS Issues: The server is preconfigured to allow all origins in development. If you encounter CORS errors, check the server configuration in main.py.

Static files not loading:

• Ensure all paths in index.html use the /static/ prefix
• Verify FastAPI static file mounting is correctly configured

Google Credentials Issues

Authentication errors:

• Check that your .env file points to the correct credentials file
• Ensure credenciales.json exists and contains valid Google API credentials
• Verify that the Google Generative AI service is enabled for your project

Development

Run in Development Mode

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Test Configuration

Use the included test script:

python test_setup.py

This will verify:

• API keys are available
• Server configuration is correct
• Google credentials are valid
• Web interface files are present

File Monitoring

The --reload flag enables automatic server restarts when files change, making development more efficient.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the terms specified in the LICENSE file.

Get Started

Your web interface is ready to use! Simply run:

uvicorn main:app --reload

Then open http://127.0.0.1:8000 in your browser to start chatting with the NEAE assistant.

---