Interval-Scheduler-API

A small FastAPI service for optimal task selection over time intervals using the Weighted Interval Scheduling algorithm.

The repository is named Interval-Scheduler-API, while the packaged Python project and CLI are named smart-scheduler.

Overview

This project lets you submit tasks with:

• a unique ID
• a start time
• an end time
• a priority score
• optional metadata

It then computes the best non-overlapping schedule that maximizes total priority.

The service is designed as a lightweight scheduling API with:

• a FastAPI HTTP interface
• an in-memory task store
• a reusable scheduling algorithm module
• unit tests for both the algorithm and API behavior

Features

• Weighted interval scheduling for optimal non-overlapping task selection
• FastAPI-based REST API
• In-memory thread-safe task storage
• Preview scheduling without persisting tasks
• Automatic UUID generation when task_id is omitted
• Validation for invalid intervals and negative priorities
• Timezone-aware datetime enforcement at the API layer

Tech Stack

• Python 3.11+
• FastAPI
• Uvicorn
• Pytest

Project Structure

Interval-Scheduler-API/
├── pyproject.toml
├── src/
│   └── smart_scheduler/
│       ├── __init__.py
│       ├── algo.py          # weighted interval scheduling implementation
│       ├── api.py           # FastAPI app and request/response models
│       ├── cli.py           # CLI entrypoint for running the API server
│       ├── models.py        # task domain model and validation
│       └── store.py         # thread-safe in-memory task store
└── tests/
    ├── test_algo.py
    └── test_api.py

Scheduling Model

Each task represents a fixed time interval with a weight:

• task_id: str
• start: datetime
• end: datetime
• priority: int
• meta: dict | null

Intervals are treated as half-open:

[start, end)

That means a task ending at 11:00 is compatible with another task starting at 11:00.

Algorithm

The core solver implements Weighted Interval Scheduling:

1. Sort tasks by end time
2. For each task, find the latest compatible previous task
3. Use dynamic programming to compute the maximum achievable priority
4. Reconstruct the chosen task set

This gives an optimal solution for the non-overlapping subset under the current priority model.

Installation

Create a virtual environment and install the package in editable mode:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

If python3.11 is not available on your system, use your local Python 3.11+ interpreter instead.

Running the API

Start the development server using the installed CLI:

smart-scheduler --host 127.0.0.1 --port 8000

You can also run Uvicorn directly:

uvicorn smart_scheduler.api:app --host 127.0.0.1 --port 8000

Once running, the API is typically available at:

http://127.0.0.1:8000

API Endpoints

GET /health

Returns a simple health check response.

Example response:

{
  "status": "ok"
}

POST /tasks

Create or upsert a task in the in-memory store.

Request body:

{
  "task_id": "T1",
  "start": "2026-01-16T10:00:00+05:30",
  "end": "2026-01-16T11:00:00+05:30",
  "priority": 10,
  "meta": {
    "type": "meeting"
  }
}

Notes:

• task_id is optional; if omitted, the API generates a UUID
• API requests require timezone-aware datetimes
• end must be strictly after start
• priority must be non-negative

GET /tasks

List all stored tasks.

DELETE /tasks/{task_id}

Delete a stored task by ID.

POST /schedule

Run scheduling against the currently stored tasks.

Example response:

{
  "total_priority": 19,
  "tasks": [
    {
      "task_id": "T1",
      "start": "2026-01-16T10:00:00+05:30",
      "end": "2026-01-16T11:00:00+05:30",
      "priority": 10,
      "meta": null
    },
    {
      "task_id": "T3",
      "start": "2026-01-16T11:00:00+05:30",
      "end": "2026-01-16T12:00:00+05:30",
      "priority": 9,
      "meta": null
    }
  ]
}

POST /schedule/preview

Run scheduling on an ad hoc payload without writing tasks into the store.

Request body:

{
  "tasks": [
    {
      "task_id": "A",
      "start": "2026-01-16T10:00:00+05:30",
      "end": "2026-01-16T11:00:00+05:30",
      "priority": 10
    },
    {
      "task_id": "B",
      "start": "2026-01-16T10:30:00+05:30",
      "end": "2026-01-16T12:00:00+05:30",
      "priority": 15
    },
    {
      "task_id": "C",
      "start": "2026-01-16T12:00:00+05:30",
      "end": "2026-01-16T13:00:00+05:30",
      "priority": 9
    }
  ]
}

Example Workflow

Add a few tasks:

curl -X POST http://127.0.0.1:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "T1",
    "start": "2026-01-16T10:00:00+05:30",
    "end": "2026-01-16T11:00:00+05:30",
    "priority": 10
  }'

curl -X POST http://127.0.0.1:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "T2",
    "start": "2026-01-16T10:30:00+05:30",
    "end": "2026-01-16T12:00:00+05:30",
    "priority": 15
  }'

curl -X POST http://127.0.0.1:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "T3",
    "start": "2026-01-16T12:00:00+05:30",
    "end": "2026-01-16T13:00:00+05:30",
    "priority": 9
  }'

Then compute the optimal schedule:

curl -X POST http://127.0.0.1:8000/schedule

Expected behavior:

• T1 and T3 can both be selected together for total priority 19
• T2 conflicts with T1, so the algorithm chooses the best compatible combination

Development

Install dependencies:

python -m pip install -e ".[dev]"

Run tests:

pytest

Current Project Status

The codebase has a solid structure for a small scheduling service, but the current checked-in revision has an issue in src/smart_scheduler/algo.py:

• the file currently contains an indentation error
• because of that, the package cannot be imported successfully in its current state
• test collection fails until that syntax issue is fixed

So the project design, API layout, and tests are present, but the current snapshot needs a small code correction before the service can run successfully.

Notes and Limitations

• Storage is in-memory only; data is lost on restart
• No authentication or authorization is included
• No persistence layer or database integration is implemented
• No recurring-task support is present
• No resource constraints beyond time overlap are modeled
• API scheduling is single-objective: maximize total priority

Possible Next Improvements

• add persistent storage with SQLite or PostgreSQL
• expose update endpoints explicitly
• add pagination and filtering for task listing
• support recurring tasks and calendars
• add OpenAPI examples and richer validation messages
• fix the current indentation issue and add CI to prevent syntax regressions