Refactor/sched engine/c rewrite

.dockerignore

@@ -0,0 +1,11 @@
+__pycache__/
+.pytest_cache/
+.venv/
+.git/
+elastisched.db
+frontend/node_modules/
+offline-packages/
+docs/
+tests/
+learning/
+mcp/

.gitignore

@@ -5,8 +5,17 @@
 **/.vscode
 **/build
 **/logs
+**/node_modules
+**/dist
+**/.parcel-cache
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
 src/elastisched/engine/bin
 
 offline-packages
 
-elastisched.db
+elastisched.db
+elastischedcopy.db

Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONPATH=/app/backend
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential cmake \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN mkdir -p /app/data
+
+COPY README.md requirements.txt pyproject.toml /app/
+COPY core /app/core
+COPY engine /app/engine
+COPY backend /app/backend
+COPY frontend /app/frontend
+
+RUN pip install --upgrade pip \
+    && pip install -r requirements.txt \
+    && pip install -e .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "elastisched_api.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,15 +1,13 @@
 # Elastisched
 ![Elastisched UI](docs/ui-preview.png)
 
-Elastisched is a scheduling playground built around "blobs": flexible, schedulable blocks of time with constraints. The project includes a FastAPI backend and a lightweight UI for exploring day/week/month/year views.
-
-
+Elastisched is a scheduling and time management software built around "blobs": flexible, schedulable blocks of time with constraints.
 
 ## Core Concepts
 
-- Blobs represent tasks/events with a schedulable time range and optional policies.
+- Blobs represent tasks/events with a schedulable time range and optional policies (which guide the scheduler).
 - Policies can make blobs overlappable, invisible, or splittable to guide scheduling behavior.
-- Scheduling uses simulated annealing to search for good local minima under constraints.
+- Scheduling uses simulated annealing and preference learning to search for good local minima under constraints.
 
 ## Features
 
@@ -20,16 +18,60 @@ Elastisched is a scheduling playground built around "blobs": flexible, schedulab
 
 ## Project Layout
 
-- `src/elastisched/api`: FastAPI backend and models
+- `backend/elastisched_api`: FastAPI backend and models
+- `core`: core scheduling library
+- `engine`: C++ scheduler engine
 - `frontend`: UI (HTML/CSS/JS)
+- `learning`: preference learning and ML models
+- `integrations`: integrations with other calendar apps, i.e., Google Calendar
+- `mcp`: a FastMCP integration for elastisched
 - `tests`: API and recurrence tests
 
 ## Quick Start
 
+### Docker
+
+1. `docker compose up --build`
+2. Open `http://localhost:8000/ui`
+
+### Local (no Docker)
+
 1. Install dependencies.
 2. Run the API.
 3. Open the UI at `/ui` or open `frontend/index.html` directly.
 
 ## Troubleshooting
 
 - If you see a GLIB/GCC mismatch in native builds, align your Conda GCC/G++ with the version used to compile the library.
+
+## Miscellaneous
+
+### Scheduler Algorithm
+The scheduler algorithm uses simulated annealing, which is a form of stochastic optimization for often discrete, non-differentiable cost functions. 
+It will not always find the global minima, but tends to find good local minima. However, for calendars with not as many events, it will find the global
+minima with high probability. 
+
+#### Lookahead
+Lookahead is an important concept since it determines how many events the scheduler will have to work with at a time, affecting efficiency and solution
+quality. The default is set to 2 weeks, but can be changed in settings. Whenever a blob or recurrence is added or edited, the scheduler marks the old schedule
+as "dirty", prompting the user to run the scheduling algorithm.
+
+#### Preference Learning
+Apart from some the most primitive cost functions, the simulated annealer won't be able to truly capture a user's intent only through code, since 
+our preferences for what a good schedule might look like depends on the user and can't simply be hard coded in. Hence, elastisched also implements
+preference learning. The most primitive cost functions currently implemented are: illegal schedule cost (which may be deprecated to prevent illegal
+schedules entirely via simulated annealer), overlapping event cost (reduce the amount of overlap for overlappable events), and split count cost
+(reduce the amount of times that we split a splittable event). Naturally, most schedules conditioned by the simulated annealer are "optimal", which
+implies there are many potential global optima and requires tie-breaking.
+
+Preference learning helps to break ties by slowly learning the user's preferences over what schedules should be chosen when multiple global optima
+exists. 
+
+We can view the simulated annealer as a generative algorithm which generates optimal schedules. Preference learning then runs the learned cost function
+against multiple samples generated by the annealer and tries to learn the following distribution: P(U(A) > U(B)), where A and B are schedules returned by the
+annealer and U is some utility function implicitly learned by the preference learning model. We can then use this learned preference function to return 
+the most suitable schedule in O(S) time, where S is the number of samples discovered by the simulated annealer. 
+
+#### Semantic Preference Learning
+To help the preference learning algorithm, we utilize all information about an event including the description and recurrence name. 
+In the backend, we use a sentence-transformer model which can be optionally GPU accelerated if the user has a GPU. 

backend/elastisched_api/__init__.py

@@ -0,0 +1,3 @@
+from elastisched_api.main import app
+
+__all__ = ["app"]

src/elastisched/api/config.py → backend/elastisched_api/config.py

@@ -1,7 +1,7 @@
 import os
 
 
-DEFAULT_DATABASE_URL = "sqlite+aiosqlite:///./elastisched.db"
+DEFAULT_DATABASE_URL = "sqlite+aiosqlite:///./core.db"
 
 
 def get_database_url() -> str:

src/elastisched/api/db.py → backend/elastisched_api/db.py

@@ -4,7 +4,7 @@
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase
 
-from elastisched.api.config import get_database_url
+from elastisched_api.config import get_database_url
 
 
 DATABASE_URL = get_database_url()
@@ -23,10 +23,13 @@ async def get_session() -> AsyncGenerator[AsyncSession, None]:
 
 
 async def init_db() -> None:
+    # Ensure model metadata is registered on the current Base.
+    import elastisched_api.models as models  # noqa: F401
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
         if conn.dialect.name == "sqlite":
             await _ensure_sqlite_blob_columns(conn)
+            await _ensure_sqlite_scheduled_occurrence_columns(conn)
 
 
 async def _ensure_sqlite_blob_columns(conn) -> None:
@@ -39,3 +42,15 @@ async def _ensure_sqlite_blob_columns(conn) -> None:
         missing.append(("realized_end", "DATETIME"))
     for name, col_type in missing:
         await conn.execute(text(f"ALTER TABLE blobs ADD COLUMN {name} {col_type}"))
+
+
+async def _ensure_sqlite_scheduled_occurrence_columns(conn) -> None:
+    result = await conn.execute(text("PRAGMA table_info(scheduled_occurrences)"))
+    columns = {row[1] for row in result.fetchall()}
+    missing = []
+    if "segment_index" not in columns:
+        missing.append(("segment_index", "INTEGER DEFAULT 0"))
+    for name, col_type in missing:
+        await conn.execute(
+            text(f"ALTER TABLE scheduled_occurrences ADD COLUMN {name} {col_type}")
+        )

src/elastisched/api/main.py → backend/elastisched_api/main.py

@@ -3,17 +3,17 @@
 from fastapi import FastAPI
 from fastapi.staticfiles import StaticFiles
 
-from elastisched.api.db import init_db
-from elastisched.api.router import router as blob_router
-from elastisched.api.recurrence_router import (
+from elastisched_api.db import init_db
+from elastisched_api.router import router as blob_router
+from elastisched_api.recurrence_router import (
     occurrence_router,
     recurrence_router,
 )
-from elastisched.api.schedule_router import schedule_router
+from elastisched_api.schedule_router import schedule_router
 
 
 app = FastAPI(title="Elastisched API")
-_UI_DIR = Path(__file__).resolve().parents[3] / "frontend"
+_UI_DIR = Path(__file__).resolve().parents[2] / "frontend"
 if _UI_DIR.exists():
     app.mount("/ui", StaticFiles(directory=_UI_DIR, html=True), name="ui")
 

src/elastisched/api/models.py → backend/elastisched_api/models.py

@@ -3,7 +3,7 @@
 from sqlalchemy import Boolean, DateTime, Integer, JSON, String
 from sqlalchemy.orm import Mapped, mapped_column
 
-from elastisched.api.db import Base
+from elastisched_api.db import Base
 
 
 class BlobModel(Base):
@@ -36,6 +36,7 @@ class ScheduledOccurrenceModel(Base):
     __tablename__ = "scheduled_occurrences"
 
     id: Mapped[str] = mapped_column(String(200), primary_key=True)
+    segment_index: Mapped[int] = mapped_column(Integer, primary_key=True, default=0)
     realized_start: Mapped[datetime] = mapped_column(DateTime(timezone=True))
     realized_end: Mapped[datetime] = mapped_column(DateTime(timezone=True))