schedule-module 0.1.0__py3-none-any.whl

schedule_module-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: schedule-module
+Version: 0.1.0
+Summary: A reusable scheduling capability module
+Requires-Python: >=3.9
+Requires-Dist: asyncpg>=0.28.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: pytz>=2023.3
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.1; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: testcontainers[postgres]>=3.7.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Schedule Module
+
+A reusable, production-grade scheduling capability module designed for both human developers and AI agents.
+It provides a robust scheduling system that allows projects to create, manage, and query events, routines, and time-based records across systems using a strictly structured PostgreSQL database.
+
+## Architecture & Principles
+
+- **Installability**: Can be initialized easily via `make initial`.
+- **Backward Compatibility**: Migrations are versioned and immutable.
+- **Agent-First Design**: Includes MCP integration and YAML action definitions for native AI consumption.
+- **Human Usability**: Clean API, strongly typed Pydantic models.
+
+## Usage
+
+### 1. Installation
+
+To initialize the database locally via Docker Compose, simply run:
+```bash
+make initial
+```
+
+This will:
+1. Spin up a PostgreSQL container using `docker-compose.yml`.
+2. Apply the initial schema and tables (`/db/ddl`).
+3. Run all pending migrations (`/db/migrations`).
+
+### 2. Python API
+
+Use the `Schedule` service to interact with your data:
+
+```python
+from datetime import datetime, timezone
+import asyncio
+from uuid import uuid4
+from src import Schedule, ScheduledRoutineCreate, RecurrencyType
+
+async def main():
+    async with Schedule() as schedule_service:
+        routine = ScheduledRoutineCreate(
+            name="Daily Standup",
+            start_date_time=datetime.now(timezone.utc),
+            end_date_time=datetime.now(timezone.utc),
+            recurrency=RecurrencyType.daily
+        )
+        created_routine = await schedule_service.add_schedule(routine)
+        print("Created Routine ID:", created_routine.id)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 3. Agent Integration
+
+Refer to `agent/mcp.yaml` and `agent/actions.yaml` for using this module as a tool in AI workflows via MCP (Model Context Protocol).
+
+## Infrastructure
+
+We include boilerplate configurations for deployments:
+- `infra/docker-compose.yml`: For local deployments
+- `infra/terraform`: Example Terraform modules for AWS RDS Postgres deployments
+
+## Publishing
+
+The module includes a `.github/workflows/publish.yml` that automatically publishes to npm and PyPI whenever changes are merged into the `main` branch.

schedule_module-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+src/__init__.py,sha256=QaiQhviZkGg-UmK0q983LvQqSK29465_YbDSZTDx9rc,435
+src/cli.py,sha256=YYTanku6vtKLFIfAzNidbwgdexXaCC4gmEoiq4ZwoTs,3558
+src/core/models.py,sha256=kX1TF9PLuPVPzBO8FfWVveu7RwH3QgTHMrjJEVbOzF8,1847
+src/db/connection.py,sha256=PROYZ8DNOjtZK4Hnph004dz_FvyG6TWbG_dBf-5TlKQ,531
+src/repositories/category_repository.py,sha256=yf3VeEtz4XhCK_RpuH4qbwTJmnZt452Jb7j0FQ_LSpo,1325
+src/repositories/date_register_repository.py,sha256=4aZHTQMYcaDqV1SKw5Azn0yF6pnETIEgjaVraPz1JrQ,2558
+src/repositories/schedule_repository.py,sha256=kVZWdQyBnXlXLSHJpHaORHsrHTVRdtyoDF1QRyRGuW8,1561
+src/services/schedule_service.py,sha256=orNpYotng0wpmNOR9Rf_n_Cxcq1M-vxCk4JWIdNcxcg,2297
+src/utils/date_utils.py,sha256=NxniUVhMMvqUMDcqRrOA6CRDvD1PM6vSpevbgJ3apas,412
+schedule_module-0.1.0.dist-info/METADATA,sha256=t79b60rb967yLsyEFgWGftxSFTOKtX7kmfo3LA3G7nE,2739
+schedule_module-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+schedule_module-0.1.0.dist-info/entry_points.txt,sha256=5WpYPWq6sopoTteFpk_MOz9SS5BnFfPoUdpJ6jBXNWc,53
+schedule_module-0.1.0.dist-info/RECORD,,

schedule_module-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

schedule_module-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+schedule-module-cli = src.cli:main

src/__init__.py

@@ -0,0 +1,19 @@
+from .services.schedule_service import Schedule
+from .core.models import (
+    RecurrencyType, RegisterType, 
+    Category, CategoryCreate,
+    ScheduledRoutine, ScheduledRoutineCreate,
+    DateRegister, DateRegisterCreate
+)
+
+__all__ = [
+    "Schedule",
+    "RecurrencyType",
+    "RegisterType",
+    "Category",
+    "CategoryCreate",
+    "ScheduledRoutine",
+    "ScheduledRoutineCreate",
+    "DateRegister",
+    "DateRegisterCreate"
+]

src/cli.py

@@ -0,0 +1,109 @@
+import argparse
+import asyncio
+import os
+import re
+import asyncpg
+from src.db.connection import DATABASE_URL
+
+ASYNC_PG_URL = DATABASE_URL.replace("postgresql+asyncpg://", "postgresql://")
+
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+DB_DIR = os.path.join(BASE_DIR, "db")
+
+async def run_sql_file(conn, filepath):
+    with open(filepath, "r") as f:
+        sql = f.read()
+    if sql.strip():
+        await conn.execute(sql)
+
+async def init_schema_version(conn):
+    # Ensure the table exists
+    await conn.execute("""
+        CREATE SCHEMA IF NOT EXISTS schedule_module;
+        CREATE TABLE IF NOT EXISTS schedule_module.schema_version (
+            version INT PRIMARY KEY,
+            name VARCHAR(255) NOT NULL,
+            executed_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+        );
+    """)
+
+async def get_applied_migrations(conn):
+    rows = await conn.fetch("SELECT version FROM schedule_module.schema_version")
+    return {row['version'] for row in rows}
+
+async def apply_migrations(conn):
+    await init_schema_version(conn)
+    applied = await get_applied_migrations(conn)
+
+    migrations_dir = os.path.join(DB_DIR, "migrations")
+    files = sorted(os.listdir(migrations_dir))
+    
+    for filename in files:
+        if not filename.endswith(".sql"):
+            continue
+        
+        match = re.match(r"^(\d+)_", filename)
+        if match:
+            version = int(match.group(1))
+            if version not in applied:
+                print(f"Applying migration: {filename}")
+                filepath = os.path.join(migrations_dir, filename)
+                await run_sql_file(conn, filepath)
+                await conn.execute(
+                    "INSERT INTO schedule_module.schema_version (version, name) VALUES ($1, $2)",
+                    version, filename
+                )
+        else:
+            print(f"Skipping incorrectly formatted migration file: {filename}")
+
+async def bootstrap():
+    print("Running bootstrap...")
+    conn = await asyncpg.connect(ASYNC_PG_URL)
+    try:
+        # Run DDLs
+        ddl_dir = os.path.join(DB_DIR, "ddl")
+        for filename in sorted(os.listdir(ddl_dir)):
+            if filename.endswith(".sql") and filename != "schema.sql":
+                print(f"Applying DDL: {filename}")
+                await run_sql_file(conn, os.path.join(ddl_dir, filename))
+        
+        # Apply Migrations
+        await apply_migrations(conn)
+    finally:
+        await conn.close()
+    print("Bootstrap complete.")
+
+async def seed():
+    print("Running seed...")
+    conn = await asyncpg.connect(ASYNC_PG_URL)
+    try:
+        seed_path = os.path.join(DB_DIR, "bootstrap", "seed.sql")
+        if os.path.exists(seed_path):
+            await run_sql_file(conn, seed_path)
+            print("Seed complete.")
+        else:
+            print("No seed.sql found.")
+    finally:
+        await conn.close()
+
+def main():
+    parser = argparse.ArgumentParser(description="Schedule Module CLI")
+    parser.add_argument("command", choices=["bootstrap", "migrate", "seed"], help="Command to execute")
+
+    args = parser.parse_args()
+
+    if args.command == "bootstrap":
+        asyncio.run(bootstrap())
+    elif args.command == "migrate":
+        async def _migrate():
+            conn = await asyncpg.connect(ASYNC_PG_URL)
+            try:
+                await apply_migrations(conn)
+            finally:
+                await conn.close()
+        asyncio.run(_migrate())
+    elif args.command == "seed":
+        asyncio.run(seed())
+
+if __name__ == "__main__":
+    main()

src/core/models.py

@@ -0,0 +1,71 @@
+from enum import Enum
+from typing import Optional
+from datetime import datetime
+from uuid import UUID
+from pydantic import BaseModel, ConfigDict, Field
+
+class RecurrencyType(str, Enum):
+    daily = 'daily'
+    weekly = 'weekly'
+    biweekly = 'biweekly'
+    monthly = 'monthly'
+    custom_days = 'custom_days'
+
+class RegisterType(str, Enum):
+    event = 'event'
+    schedule = 'schedule'
+
+class CategoryBase(BaseModel):
+    name: str
+    description: Optional[str] = None
+    color: Optional[str] = None
+    icon: Optional[str] = None
+    image: Optional[str] = None
+    note: Optional[str] = None
+
+class CategoryCreate(CategoryBase):
+    pass
+
+class Category(CategoryBase):
+    id: UUID
+    creation_date_time: datetime
+    update_date_time: datetime
+    model_config = ConfigDict(from_attributes=True)
+
+class ScheduledRoutineBase(BaseModel):
+    name: str
+    category_id: Optional[UUID] = None
+    start_date_time: datetime
+    end_date_time: datetime
+    description: Optional[str] = None
+    note: Optional[str] = None
+    recurrency: RecurrencyType
+
+class ScheduledRoutineCreate(ScheduledRoutineBase):
+    pass
+
+class ScheduledRoutine(ScheduledRoutineBase):
+    id: UUID
+    creation_date_time: datetime
+    update_date_time: datetime
+    model_config = ConfigDict(from_attributes=True)
+
+class DateRegisterBase(BaseModel):
+    type: RegisterType
+    name: str
+    start_date_time: datetime
+    end_date_time: datetime
+    description: Optional[str] = None
+    note: Optional[str] = None
+    category_id: Optional[UUID] = None
+    scheduled_routine_id: Optional[UUID] = None
+    relationship_field: Optional[str] = None
+
+class DateRegisterCreate(DateRegisterBase):
+    pass
+
+class DateRegister(DateRegisterBase):
+    id: UUID
+    creation_date_time: datetime
+    update_date_time: datetime
+    model_config = ConfigDict(from_attributes=True)

src/db/connection.py

@@ -0,0 +1,17 @@
+import os
+from sqlalchemy.ext.asyncio import create_async_engine
+
+# Database settings
+DB_HOST = os.getenv("DB_HOST", "localhost")
+DB_PORT = os.getenv("DB_PORT", "5432")
+DB_USER = os.getenv("DB_USER", "postgres")
+DB_PASS = os.getenv("DB_PASS", "postgres")
+DB_NAME = os.getenv("DB_NAME", "postgres")
+
+DATABASE_URL = f"postgresql+asyncpg://{DB_USER}:{DB_PASS}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
+
+engine = create_async_engine(DATABASE_URL, echo=False)
+
+async def get_connection():
+    async with engine.begin() as conn:
+        yield conn

src/repositories/category_repository.py

@@ -0,0 +1,35 @@
+from uuid import UUID
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncConnection
+from typing import Optional, List
+from src.core.models import CategoryCreate, Category
+
+class CategoryRepository:
+    def __init__(self, conn: AsyncConnection):
+        self.conn = conn
+
+    async def create(self, category: CategoryCreate) -> Category:
+        query = text("""
+            INSERT INTO schedule_module.category 
+            (name, description, color, icon, image, note)
+            VALUES (:name, :description, :color, :icon, :image, :note)
+            RETURNING *
+        """)
+        result = await self.conn.execute(query, {
+            "name": category.name,
+            "description": category.description,
+            "color": category.color,
+            "icon": category.icon,
+            "image": category.image,
+            "note": category.note
+        })
+        row = result.fetchone()
+        return Category.model_validate(dict(row._mapping))
+
+    async def get_by_id(self, category_id: UUID) -> Optional[Category]:
+        query = text("SELECT * FROM schedule_module.category WHERE id = :id")
+        result = await self.conn.execute(query, {"id": category_id})
+        row = result.fetchone()
+        if row:
+            return Category.model_validate(dict(row._mapping))
+        return None

src/repositories/date_register_repository.py

@@ -0,0 +1,49 @@
+from uuid import UUID
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncConnection
+from typing import Optional, List
+from datetime import datetime
+from src.core.models import DateRegisterCreate, DateRegister
+
+class DateRegisterRepository:
+    def __init__(self, conn: AsyncConnection):
+        self.conn = conn
+
+    async def create(self, register: DateRegisterCreate) -> DateRegister:
+        query = text("""
+            INSERT INTO schedule_module.date_register 
+            (type, name, start_date_time, end_date_time, description, note, category_id, scheduled_routine_id, relationship_field)
+            VALUES (:type, :name, :start_date_time, :end_date_time, :description, :note, :category_id, :scheduled_routine_id, :relationship_field)
+            RETURNING *
+        """)
+        result = await self.conn.execute(query, {
+            "type": register.type.value,
+            "name": register.name,
+            "start_date_time": register.start_date_time,
+            "end_date_time": register.end_date_time,
+            "description": register.description,
+            "note": register.note,
+            "category_id": register.category_id,
+            "scheduled_routine_id": register.scheduled_routine_id,
+            "relationship_field": register.relationship_field
+        })
+        row = result.fetchone()
+        return DateRegister.model_validate(dict(row._mapping))
+
+    async def get_by_relationship(self, relationship_field: str) -> List[DateRegister]:
+        query = text("SELECT * FROM schedule_module.date_register WHERE relationship_field = :rel")
+        result = await self.conn.execute(query, {"rel": relationship_field})
+        return [DateRegister.model_validate(dict(row._mapping)) for row in result.fetchall()]
+
+    async def get_by_schedule(self, scheduled_routine_id: UUID) -> List[DateRegister]:
+        query = text("SELECT * FROM schedule_module.date_register WHERE scheduled_routine_id = :sch")
+        result = await self.conn.execute(query, {"sch": scheduled_routine_id})
+        return [DateRegister.model_validate(dict(row._mapping)) for row in result.fetchall()]
+
+    async def get_dates_from_range(self, start: datetime, end: datetime) -> List[DateRegister]:
+        query = text("""
+            SELECT * FROM schedule_module.date_register 
+            WHERE start_date_time < :end AND end_date_time > :start
+        """)
+        result = await self.conn.execute(query, {"start": start, "end": end})
+        return [DateRegister.model_validate(dict(row._mapping)) for row in result.fetchall()]

src/repositories/schedule_repository.py

@@ -0,0 +1,36 @@
+from uuid import UUID
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncConnection
+from typing import Optional
+from src.core.models import ScheduledRoutineCreate, ScheduledRoutine
+
+class ScheduleRepository:
+    def __init__(self, conn: AsyncConnection):
+        self.conn = conn
+
+    async def create(self, routine: ScheduledRoutineCreate) -> ScheduledRoutine:
+        query = text("""
+            INSERT INTO schedule_module.scheduled_routine 
+            (name, category_id, start_date_time, end_date_time, description, note, recurrency)
+            VALUES (:name, :category_id, :start_date_time, :end_date_time, :description, :note, :recurrency)
+            RETURNING *
+        """)
+        result = await self.conn.execute(query, {
+            "name": routine.name,
+            "category_id": routine.category_id,
+            "start_date_time": routine.start_date_time,
+            "end_date_time": routine.end_date_time,
+            "description": routine.description,
+            "note": routine.note,
+            "recurrency": routine.recurrency.value
+        })
+        row = result.fetchone()
+        return ScheduledRoutine.model_validate(dict(row._mapping))
+
+    async def get_by_id(self, routine_id: UUID) -> Optional[ScheduledRoutine]:
+        query = text("SELECT * FROM schedule_module.scheduled_routine WHERE id = :id")
+        result = await self.conn.execute(query, {"id": routine_id})
+        row = result.fetchone()
+        if row:
+            return ScheduledRoutine.model_validate(dict(row._mapping))
+        return None

src/services/schedule_service.py

@@ -0,0 +1,56 @@
+from uuid import UUID
+from typing import List, Optional
+from datetime import datetime
+from sqlalchemy.ext.asyncio import AsyncConnection
+
+from src.core.models import (
+    ScheduledRoutineCreate, ScheduledRoutine, 
+    DateRegisterCreate, DateRegister, RegisterType,
+    CategoryCreate, Category
+)
+from src.repositories.schedule_repository import ScheduleRepository
+from src.repositories.date_register_repository import DateRegisterRepository
+from src.repositories.category_repository import CategoryRepository
+from src.db.connection import engine
+
+class Schedule:
+    """Primary service class for the Schedule Module"""
+
+    def __init__(self, conn: Optional[AsyncConnection] = None):
+        self._conn = conn
+
+    async def __aenter__(self):
+        if self._conn is None:
+            self._engine_conn = engine.begin()
+            self.conn = await self._engine_conn.__aenter__()
+        else:
+            self.conn = self._conn
+        self._init_repos()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._conn is None:
+            await self._engine_conn.__aexit__(exc_type, exc_val, exc_tb)
+
+    def _init_repos(self):
+        self.schedule_repo = ScheduleRepository(self.conn)
+        self.date_register_repo = DateRegisterRepository(self.conn)
+        self.category_repo = CategoryRepository(self.conn)
+
+    async def add_category(self, category: CategoryCreate) -> Category:
+        return await self.category_repo.create(category)
+
+    async def add_date_record(self, register: DateRegisterCreate) -> DateRegister:
+        return await self.date_register_repo.create(register)
+
+    async def add_schedule(self, routine: ScheduledRoutineCreate) -> ScheduledRoutine:
+        return await self.schedule_repo.create(routine)
+
+    async def get_records_for_relationship(self, relationship_field: str) -> List[DateRegister]:
+        return await self.date_register_repo.get_by_relationship(relationship_field)
+
+    async def get_records_for_schedule(self, schedule_id: UUID) -> List[DateRegister]:
+        return await self.date_register_repo.get_by_schedule(schedule_id)
+
+    async def get_dates_from_range(self, start: datetime, end: datetime) -> List[DateRegister]:
+        return await self.date_register_repo.get_dates_from_range(start, end)

src/utils/date_utils.py

@@ -0,0 +1,12 @@
+from datetime import datetime
+import pytz
+
+def normalize_to_utc(dt: datetime) -> datetime:
+    """Normalize datetime to UTC."""
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=pytz.UTC)
+    return dt.astimezone(pytz.UTC)
+
+def is_overlap(start1: datetime, end1: datetime, start2: datetime, end2: datetime) -> bool:
+    """Check if two date ranges overlap."""
+    return start1 < end2 and start2 < end1