ChronosAI - Intelligent Scheduling Assistant

An advanced calendar application powered by Claude AI and Google OR-Tools CP-SAT solver. Schedule events using natural language and let the system find optimal time slots while respecting your constraints.

Features

• 🤖 Natural Language Scheduling - Chat with Claude AI to schedule events: "Schedule a team meeting tomorrow at 2pm for 30 minutes"
• 🧠 CP-SAT Optimization - Uses Google OR-Tools constraint programming solver for intelligent scheduling
• 📅 Google Calendar Sync - Bidirectional sync with Google Calendar via Composio
• 🔔 Real-time Webhook Sync - Instant updates when Google Calendar changes
• 💾 SQLite Database - Local event persistence with optional cloud sync
• 🎨 Modern UI - React + TypeScript with Radix UI components
• ⚡ Real-time Conflict Detection - Automatically finds free time slots and avoids conflicts
• 🔄 Flexible Task Scheduling - Split tasks into multiple blocks with duration constraints

Architecture

Frontend (React + TypeScript)

• Framework: React 18.3 with Vite
• UI Library: Radix UI + Tailwind CSS
• State Management: React Hooks
• API Client: Native Fetch API

Backend (FastAPI + Python)

• Framework: FastAPI 0.115
• LLM: Anthropic Claude 3.5 Sonnet (via Anthropic SDK)
• Solver: Google OR-Tools CP-SAT 9.10
• Database: SQLAlchemy with SQLite (upgradeable to PostgreSQL)
• Calendar Integration: Google Calendar API

Installation

Prerequisites

• Node.js 18+ and npm
• Python 3.10+
• Anthropic API Key (for natural language parsing)
• Composio API Key (for Google Calendar sync) - Get one at https://composio.dev

1. Clone and Install Dependencies

# Install frontend dependencies
npm install

# Install backend dependencies
pip install -r requirements.txt

2. Backend Configuration

Create a .env file in the root directory:

cp .env.example .env

Edit .env and add your credentials:

# Required: Anthropic API Key
ANTHROPIC_API_KEY=sk-ant-api03-...

# Required for Google Calendar Sync: Composio API Key
COMPOSIO_API_KEY=your_composio_api_key_here

# Database (default SQLite)
DATABASE_URL=sqlite:///./chronos.db

# Optional: Legacy Google Calendar Integration (deprecated)
# GOOGLE_CLIENT_SECRETS_FILE=credentials.json

3. Frontend Configuration (Optional)

Create .env.local for frontend:

cp .env.frontend.example .env.local

Edit if you need to change the API URL:

VITE_API_URL=http://localhost:8000

4. Google Calendar Setup with Composio

Super simple setup - just 3 steps:

1. Sign up for Composio and get your API key (free)
2. Add COMPOSIO_API_KEY to your .env file
3. Start the servers and click "Connect Google Calendar" in the left sidebar

That's it! Events will auto-sync bidirectionally. No auth config, no JSON files, no complicated setup.

Quick start: See SIMPLIFIED_SETUP.md Detailed setup: See COMPOSIO_SETUP_UPDATED.md Testing: See TESTING_GUIDE.md

Running the Application

Start Backend Server

python main.py

The backend will start on http://localhost:8000

Check health: curl http://localhost:8000/health

Start Frontend Dev Server

npm run dev

The frontend will start on http://localhost:3000 (or http://localhost:5173 with newer Vite)

Usage

Basic Scheduling with Natural Language

1. Open the app and find the AI Assistant panel on the right
2. Type a natural language request like:
   • "Schedule a meeting with the team tomorrow at 2pm for 30 minutes"
   • "I need to study for 2 hours, available Thursday and Friday afternoon"
   • "Book dentist appointment next week"
3. The system will:
   • Parse your request with Claude AI
   • Find optimal time slots using CP-SAT solver
   • Create events in the database
   • Display them in your calendar

Scheduling Constraints

The CP-SAT solver respects:

• Work Hours: Default 9am-6pm, Mon-Fri (configurable)
• Buffers: 10-minute gaps between events (configurable)
• Deadlines: Events must be scheduled before deadline
• Availability Windows: Only schedule in specified time ranges
• No Overlaps: Automatically avoids busy times
• Task Splitting: Tasks can be split into multiple blocks

Google Calendar Sync (Composio)

Initial Setup

1. Get the OAuth URL: GET http://localhost:8000/composio/auth-url
2. Open the URL and authorize Google Calendar access
3. Check connection: GET http://localhost:8000/composio/status

Syncing Events

The integration provides automatic bidirectional sync:

Local → Google Calendar:

• Events created/updated/deleted in ChronosAI automatically sync to Google Calendar
• No manual action needed!

Google Calendar → Local:

• Manual sync: POST http://localhost:8000/composio/sync
• Or set up webhooks for real-time sync (see COMPOSIO_SETUP.md)

Run the demo:

python examples/composio_sync_example.py

API Endpoints

Core Scheduling

• POST /schedule-and-save - Natural language to scheduled event (end-to-end)
• POST /parse - Parse natural language to structured format
• POST /schedule_c - Run CP-SAT solver on structured items

Event CRUD

• GET /events - List all events
• POST /events - Create event
• PATCH /events/{id} - Update event
• DELETE /events/{id} - Delete event

Calendar CRUD

• GET /calendars - List all calendars
• POST /calendars - Create calendar

Google Calendar (Composio Integration)

• GET /composio/auth-url - Get OAuth authorization URL
• GET /composio/callback - OAuth callback handler
• GET /composio/status - Check connection status
• POST /composio/sync - Bidirectional sync (Google ↔ Local)
• POST /composio/sync-event/{event_id} - Sync specific event to Google
• POST /composio/webhook/{calendar_id} - Setup webhook for real-time sync
• POST /composio/webhook-notification - Webhook notification handler

Google Calendar (Legacy - Deprecated)

• GET /google/auth-url - Get OAuth URL
• GET /google/callback - OAuth callback handler
• GET /google/status - Check connection status
• POST /google/sync - Sync events from Google

Development

Project Structure

ChronosAI/
├── src/                          # Frontend React app
│   ├── components/               # React components
│   │   ├── AssistantPanel.tsx   # AI chat interface
│   │   ├── WeekView.tsx         # Calendar views
│   │   └── ...
│   ├── types/                   # TypeScript types
│   ├── utils/                   # API client, utilities
│   └── App.tsx                  # Main app component
├── app/                         # Backend Python app
│   ├── api.py                   # FastAPI endpoints
│   ├── parse_llm.py             # Claude AI integration
│   ├── cpsat_solver.py          # OR-Tools solver
│   ├── database.py              # SQLAlchemy models
│   ├── composio_calendar.py     # Composio Google Calendar client
│   ├── sync_service.py          # Bidirectional sync service
│   ├── google_calendar.py       # Legacy Google API client
│   ├── schemas.py               # Pydantic models
│   └── policy.py                # Scheduling policies
├── examples/                    # Example scripts
│   └── composio_sync_example.py # Composio sync demo
├── main.py                      # Backend entry point
├── requirements.txt             # Python dependencies
├── package.json                 # Node dependencies
├── COMPOSIO_SETUP.md           # Composio setup guide
└── vite.config.ts              # Vite configuration

Running Tests

# Backend tests
python -m pytest app/test_*.py

# Or run individual test files
python app/test_http.py
python app/test_inproc.py

Building for Production

# Build frontend
npm run build

# Serve with production backend
uvicorn app.api:app --host 0.0.0.0 --port 8000

Design Documentation

The system implements a CP-SAT first architecture as detailed in the design doc:

1. LLM Parsing - Claude converts natural language to structured scheduling contracts
2. Constraint Modeling - CP-SAT models events as interval variables with constraints
3. Optimization - Minimizes lateness, fragmentation, and context switching
4. Conflict Resolution - Automatic minimal relaxation when infeasible
5. Persistence - Save to SQLite + optionally sync to Google Calendar

See design doc for full details on the scheduling algorithm.

Troubleshooting

"Import could not be resolved" errors in IDE

These are normal - the Python environment needs to be activated. Run:

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

CORS errors

Make sure the backend is running on port 8000 and frontend on port 3000/5173. CORS is configured for these origins.

"ANTHROPIC_API_KEY not set"

The system will fall back to regex parsing if no API key is set. For full natural language understanding, add your Anthropic API key to .env.

Google Calendar sync not working

Using Composio (recommended):

1. Check COMPOSIO_API_KEY is set in .env
2. Verify connection: GET http://localhost:8000/composio/status
3. Re-authorize if needed: GET http://localhost:8000/composio/auth-url
4. Check logs for detailed error messages
5. See COMPOSIO_SETUP.md for detailed troubleshooting

Using legacy integration:

1. Verify credentials.json exists and is valid
2. Check OAuth redirect URI matches: http://localhost:8000/google/callback
3. Ensure Google Calendar API is enabled in Cloud Console

License

MIT

Credits

• Frontend design inspired by Figma template: Desktop Scheduling App
• Powered by Anthropic Claude
• Optimization by Google OR-Tools