Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Timetable Agent

A production-ready timetable generation system powered by Google's Gemini LLM via LangChain.

Features

  • FastAPI Backend: REST API for timetable generation with robust error handling
  • Streamlit Frontend: User-friendly interface for CSV upload and timetable preview
  • LLM-Powered: Uses Google Gemini via LangChain for intelligent scheduling
  • Production-Ready: Structured logging, validation, error handling, and testing
  • Modular Architecture: Clean separation of concerns with single-responsibility modules

Project Structure

Timetablenew/
├── app/
│   ├── core/              # Configuration and logging setup
│   ├── api/               # FastAPI routes and endpoints
│   ├── llm/               # LangChain + Gemini integration
│   ├── services/          # Business logic (parsing, formatting, scheduling)
│   ├── utils/             # Helper utilities
│   ├── frontend/          # Streamlit UI
│   └── main.py            # FastAPI application entry point
├── tests/                 # Unit tests
├── samples/               # Example input/output CSV files
├── logs/                  # Application logs (created automatically)
├── requirements.txt       # Python dependencies
├── .env.example           # Environment variable template
├── .gitignore             # Git ignore patterns
└── bootstrap.sh           # Setup script

Quick Start

1. Clone and Setup

Linux/macOS:

# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Windows:

# Create virtual environment
python -m venv venv

# Activate virtual environment
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Or use the bootstrap script:

# Linux/macOS
chmod +x bootstrap.sh
./bootstrap.sh

# Windows (PowerShell)
# Use the commands above manually

2. Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit .env and add your Gemini API key
# GEMINI_API_KEY=your_api_key_here

Get your Gemini API key:

3. Run the Application

Terminal 1 - Backend API:

# Activate venv first (if not already active)
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Run FastAPI backend
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Terminal 2 - Frontend UI:

# Activate venv first (if not already active)
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Run Streamlit frontend
streamlit run app/frontend/app_streamlit.py --server.port 8501

Access the application:

4. Run Tests

# Activate venv first
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Run all tests
pytest -v

# Run with coverage
pytest --cov=app tests/

Usage

  1. Open the Streamlit UI at http://localhost:8501
  2. Upload a CSV file with your scheduling requirements (see samples/input_example.csv)
  3. (Optional) Set target total hours
  4. Click "Generate Timetable"
  5. Preview the generated timetable
  6. Download the CSV output

Input CSV Format

Your input CSV should include columns for subjects, lecturers, priorities, etc. See samples/input_example.csv for an example.

Example columns:

  • Subject
  • Lecturer
  • Priority
  • WeeklyHours
  • PreferredDays
  • (etc.)

Output CSV Format

The generated timetable includes:

  • Day
  • Start Time
  • End Time
  • Subject
  • Lecturer
  • Room
  • Topics
  • Duration (minutes)

Configuration

Edit .env to customize:

# Gemini API Configuration
GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-1.5-flash
GEMINI_TEMPERATURE=0.2

# FastAPI Configuration
FASTAPI_HOST=127.0.0.1
FASTAPI_PORT=8000

# Streamlit Configuration
STREAMLIT_PORT=8501

# Logging Configuration
LOG_LEVEL=INFO
LOG_PATH=logs/timetable.log

Troubleshooting

Missing GEMINI_API_KEY

Error: ValueError: GEMINI_API_KEY environment variable not set

Solution:

  1. Copy .env.example to .env
  2. Add your Gemini API key from https://makersuite.google.com/app/apikey
  3. Ensure .env is in the project root directory

Import Errors

Error: ModuleNotFoundError: No module named 'app'

Solution:

  • Ensure your virtual environment is activated
  • Run pip install -r requirements.txt
  • Run commands from the project root directory

Port Already in Use

Error: Address already in use

Solution:

  • Change the port in .env (FASTAPI_PORT or STREAMLIT_PORT)
  • Or kill the process using the port

LLM Response Errors

Error: 500 Internal Server Error - Failed to parse LLM response

Solution:

  • Check your API key is valid and has quota remaining
  • Check logs in logs/timetable.log for detailed error messages
  • The system retries 3 times with exponential backoff automatically

CSV Format Errors

Error: 400 Bad Request - Invalid CSV format

Solution:

  • Ensure your CSV has the required columns
  • Check samples/input_example.csv for the expected format
  • Ensure proper encoding (UTF-8)

Development

Project Architecture

  • app/core: Configuration management and logging setup
  • app/api: FastAPI routes and request/response handling
  • app/llm: LangChain integration with Gemini LLM
  • app/services: Core business logic (parsing, scheduling, formatting)
  • app/utils: Shared utilities and helpers
  • app/frontend: Streamlit user interface
  • tests: Unit and integration tests

Adding New Features

  1. New API endpoint: Add route in app/api/routes/
  2. New service logic: Add module in app/services/
  3. Configuration: Update app/core/config.py and .env.example
  4. Tests: Add test file in tests/

Logging

Logs are written to:

  • Console (stdout) - for development
  • File (logs/timetable.log) - rotating, max 10MB, keeps 5 backups

Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

API Documentation

POST /generate

Generate a timetable from uploaded CSV.

Request:

  • Method: POST
  • Content-Type: multipart/form-data
  • Body: file (CSV file)

Response:

  • Success (200): CSV file download
  • Bad Request (400): Invalid input
  • Server Error (500): LLM or processing error

Example using curl:

curl -X POST "http://localhost:8000/generate" \
  -F "file=@samples/input_example.csv" \
  --output generated_timetable.csv

Testing

The project includes unit tests for:

  • CSV parsing logic (tests/test_parser.py)
  • JSON parsing and validation (tests/test_json_parse.py)

Run tests with:

pytest -v                    # Verbose output
pytest --cov=app tests/      # With coverage report
pytest -k test_parser        # Run specific test

License

MIT License - feel free to use for any purpose.

Support

For issues or questions:

  1. Check the troubleshooting section above
  2. Review logs in logs/timetable.log
  3. Check API documentation at http://localhost:8000/docs
  4. Verify your .env configuration

Credits

Built with:

  • FastAPI - Modern web framework
  • Streamlit - Rapid UI development
  • LangChain - LLM orchestration
  • Google Gemini - AI-powered scheduling
  • Pydantic - Data validation

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages