A production-ready timetable generation system powered by Google's Gemini LLM via LangChain.
- 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
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
Linux/macOS:
# Create virtual environment
python -m venv venv
# Activate virtual environment
source venv/bin/activate
# Install dependencies
pip install -r requirements.txtWindows:
# Create virtual environment
python -m venv venv
# Activate virtual environment
venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtOr use the bootstrap script:
# Linux/macOS
chmod +x bootstrap.sh
./bootstrap.sh
# Windows (PowerShell)
# Use the commands above manually# Copy the example environment file
cp .env.example .env
# Edit .env and add your Gemini API key
# GEMINI_API_KEY=your_api_key_hereGet your Gemini API key:
- Visit https://makersuite.google.com/app/apikey
- Create a new API key
- Add it to your
.envfile
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 --reloadTerminal 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 8501Access the application:
- Frontend UI: http://localhost:8501
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
# 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/- Open the Streamlit UI at http://localhost:8501
- Upload a CSV file with your scheduling requirements (see
samples/input_example.csv) - (Optional) Set target total hours
- Click "Generate Timetable"
- Preview the generated timetable
- Download the CSV output
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.)
The generated timetable includes:
- Day
- Start Time
- End Time
- Subject
- Lecturer
- Room
- Topics
- Duration (minutes)
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.logError: ValueError: GEMINI_API_KEY environment variable not set
Solution:
- Copy
.env.exampleto.env - Add your Gemini API key from https://makersuite.google.com/app/apikey
- Ensure
.envis in the project root directory
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
Error: Address already in use
Solution:
- Change the port in
.env(FASTAPI_PORT or STREAMLIT_PORT) - Or kill the process using the port
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.logfor detailed error messages - The system retries 3 times with exponential backoff automatically
Error: 400 Bad Request - Invalid CSV format
Solution:
- Ensure your CSV has the required columns
- Check
samples/input_example.csvfor the expected format - Ensure proper encoding (UTF-8)
- 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
- New API endpoint: Add route in
app/api/routes/ - New service logic: Add module in
app/services/ - Configuration: Update
app/core/config.pyand.env.example - Tests: Add test file in
tests/
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
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.csvThe 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 testMIT License - feel free to use for any purpose.
For issues or questions:
- Check the troubleshooting section above
- Review logs in
logs/timetable.log - Check API documentation at http://localhost:8000/docs
- Verify your
.envconfiguration
Built with:
- FastAPI - Modern web framework
- Streamlit - Rapid UI development
- LangChain - LLM orchestration
- Google Gemini - AI-powered scheduling
- Pydantic - Data validation