schedule-module 0.1.0__tar.gz

schedule_module-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+env/
+venv/
+.env
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+node_modules/
+.secrets

schedule_module-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,64 @@
+# 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/db/bootstrap/seed.sql

@@ -0,0 +1,8 @@
+-- Seed data (optional)
+-- Useful for testing or base categories
+
+INSERT INTO schedule_module.category (id, name, description, color, icon)
+VALUES 
+  ('00000000-0000-0000-0000-000000000001', 'Default', 'Default category', '#cccccc', 'default-icon'),
+  ('00000000-0000-0000-0000-000000000002', 'Work', 'Work related events', '#0000ff', 'work-icon')
+ON CONFLICT DO NOTHING;

schedule_module-0.1.0/db/ddl/001_init.sql

@@ -0,0 +1,22 @@
+CREATE SCHEMA IF NOT EXISTS schedule_module;
+
+DO $$ BEGIN
+    CREATE TYPE schedule_module.recurrency_type AS ENUM (
+        'daily',
+        'weekly',
+        'biweekly',
+        'monthly',
+        'custom_days'
+    );
+EXCEPTION
+    WHEN duplicate_object THEN null;
+END $$;
+
+DO $$ BEGIN
+    CREATE TYPE schedule_module.register_type AS ENUM (
+        'event',
+        'schedule'
+    );
+EXCEPTION
+    WHEN duplicate_object THEN null;
+END $$;

schedule_module-0.1.0/db/ddl/002_extensions.sql

@@ -0,0 +1 @@
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

schedule_module-0.1.0/db/ddl/schema.sql

@@ -0,0 +1,76 @@
+-- Full Schema Snapshot
+
+CREATE SCHEMA IF NOT EXISTS schedule_module;
+
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+DO $$ BEGIN
+    CREATE TYPE schedule_module.recurrency_type AS ENUM (
+        'daily',
+        'weekly',
+        'biweekly',
+        'monthly',
+        'custom_days'
+    );
+EXCEPTION
+    WHEN duplicate_object THEN null;
+END $$;
+
+DO $$ BEGIN
+    CREATE TYPE schedule_module.register_type AS ENUM (
+        'event',
+        'schedule'
+    );
+EXCEPTION
+    WHEN duplicate_object THEN null;
+END $$;
+
+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
+);
+
+CREATE TABLE IF NOT EXISTS schedule_module.category (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    color VARCHAR(50),
+    icon VARCHAR(255),
+    image VARCHAR(255),
+    note TEXT,
+    creation_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    update_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS schedule_module.scheduled_routine (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    name VARCHAR(255) NOT NULL,
+    category_id UUID REFERENCES schedule_module.category(id) ON DELETE SET NULL,
+    start_date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    end_date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    description TEXT,
+    note TEXT,
+    recurrency schedule_module.recurrency_type NOT NULL,
+    creation_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    update_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS schedule_module.date_register (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    type schedule_module.register_type NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    start_date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    end_date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    description TEXT,
+    note TEXT,
+    category_id UUID REFERENCES schedule_module.category(id) ON DELETE SET NULL,
+    scheduled_routine_id UUID REFERENCES schedule_module.scheduled_routine(id) ON DELETE SET NULL,
+    relationship_field VARCHAR(255),
+    creation_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    update_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_date_register_relationship ON schedule_module.date_register(relationship_field);
+CREATE INDEX IF NOT EXISTS idx_date_register_start_end ON schedule_module.date_register(start_date_time, end_date_time);
+CREATE INDEX IF NOT EXISTS idx_scheduled_routine_start_end ON schedule_module.scheduled_routine(start_date_time, end_date_time);

schedule_module-0.1.0/db/migrations/000_schema_version.sql

@@ -0,0 +1,5 @@
+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
+);

schedule_module-0.1.0/db/migrations/001_create_tables.sql

@@ -0,0 +1,43 @@
+CREATE TABLE IF NOT EXISTS schedule_module.category (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    color VARCHAR(50),
+    icon VARCHAR(255),
+    image VARCHAR(255),
+    note TEXT,
+    creation_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    update_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS schedule_module.scheduled_routine (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    name VARCHAR(255) NOT NULL,
+    category_id UUID REFERENCES schedule_module.category(id) ON DELETE SET NULL,
+    start_date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    end_date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    description TEXT,
+    note TEXT,
+    recurrency schedule_module.recurrency_type NOT NULL,
+    creation_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    update_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS schedule_module.date_register (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    type schedule_module.register_type NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    start_date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    end_date_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    description TEXT,
+    note TEXT,
+    category_id UUID REFERENCES schedule_module.category(id) ON DELETE SET NULL,
+    scheduled_routine_id UUID REFERENCES schedule_module.scheduled_routine(id) ON DELETE SET NULL,
+    relationship_field VARCHAR(255),
+    creation_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    update_date_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_date_register_relationship ON schedule_module.date_register(relationship_field);
+CREATE INDEX IF NOT EXISTS idx_date_register_start_end ON schedule_module.date_register(start_date_time, end_date_time);
+CREATE INDEX IF NOT EXISTS idx_scheduled_routine_start_end ON schedule_module.scheduled_routine(start_date_time, end_date_time);

schedule_module-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "schedule-module"
+version = "0.1.0"
+description = "A reusable scheduling capability module"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "sqlalchemy[asyncio]>=2.0.0",
+    "asyncpg>=0.28.0",
+    "pydantic>=2.0.0",
+    "python-dateutil>=2.8.2",
+    "pytz>=2023.3"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.1",
+    "testcontainers[postgres]>=3.7.1"
+]
+
+[project.scripts]
+schedule-module-cli = "src.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]

schedule_module-0.1.0/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"
+]

schedule_module-0.1.0/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()

schedule_module-0.1.0/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)

schedule_module-0.1.0/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

schedule_module-0.1.0/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

schedule_module-0.1.0/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()]

schedule_module-0.1.0/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

schedule_module-0.1.0/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)

schedule_module-0.1.0/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

schedule_module-0.1.0/tests/integration/test_service.py

@@ -0,0 +1,10 @@
+import pytest
+from datetime import datetime, timezone
+from src.services.schedule_service import Schedule
+from src.core.models import CategoryCreate
+
+@pytest.mark.asyncio
+async def test_create_category():
+    # Note: Requires a running postgres test DB to execute successfully
+    # For now, this is a placeholder demonstrating the integration testing pattern.
+    pass

schedule_module-0.1.0/tests/unit/test_utils.py

@@ -0,0 +1,21 @@
+import pytest
+from datetime import datetime
+from src.utils.date_utils import is_overlap
+
+def test_is_overlap():
+    start1 = datetime(2023, 1, 1, 10, 0)
+    end1 = datetime(2023, 1, 1, 12, 0)
+    
+    start2 = datetime(2023, 1, 1, 11, 0)
+    end2 = datetime(2023, 1, 1, 13, 0)
+    
+    assert is_overlap(start1, end1, start2, end2) == True
+
+def test_no_overlap():
+    start1 = datetime(2023, 1, 1, 10, 0)
+    end1 = datetime(2023, 1, 1, 12, 0)
+    
+    start2 = datetime(2023, 1, 1, 13, 0)
+    end2 = datetime(2023, 1, 1, 14, 0)
+    
+    assert is_overlap(start1, end1, start2, end2) == False