sicily 0.2.3__tar.gz

sicily-0.2.3/.gitignore

@@ -0,0 +1,27 @@
+.DS_Store
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+
+# Credentials & Tokens
+google_credentials.json
+gmail_token.json
+gmail_token_*.json
+
+# User specific data
+.chat_id
+Data/
+settings.json
+
+# Dev folders
+Notes/
+Helper Scripts And Files/

sicily-0.2.3/Auth/gmail_auth.py

@@ -0,0 +1,71 @@
+import os
+import socket
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from google.auth.transport.requests import Request
+
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.modify",
+    "https://www.googleapis.com/auth/gmail.send",
+    "https://www.googleapis.com/auth/gmail.readonly",
+]
+
+CREDENTIALS_FILE = "google_credentials.json"
+PORT = 8080
+
+
+async def get_gmail_token() -> str:
+    """Get Gmail token, handling stale port from cancelled auth flows."""
+
+    token_file = "gmail_token.json"
+    creds = None
+
+    if os.path.exists(token_file):
+        creds = Credentials.from_authorized_user_file(token_file, SCOPES)
+
+    if creds and creds.expired and creds.refresh_token:
+        creds.refresh(Request())
+
+    elif not creds or not creds.valid:
+        if not os.path.exists(CREDENTIALS_FILE):
+            raise FileNotFoundError(f"❌ {CREDENTIALS_FILE} not found!")
+
+        # --- Free the port if it's stuck from a previous cancelled flow ---
+        if _is_port_in_use(PORT):
+            print(f"⚠️  Port {PORT} already in use — freeing it...")
+            _free_port(PORT)
+
+        flow = InstalledAppFlow.from_client_secrets_file(CREDENTIALS_FILE, SCOPES)
+        creds = flow.run_local_server(
+            port=PORT,
+            prompt='consent'
+        )
+
+    with open(token_file, "w") as f:
+        f.write(creds.to_json())
+
+    return creds.token
+
+
+def _is_port_in_use(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        return s.connect_ex(("localhost", port)) == 0
+
+
+def _free_port(port: int):
+    """Kill whatever process is holding the port."""
+    import subprocess, sys
+    if sys.platform == "win32":
+        result = subprocess.run(
+            f"for /f \"tokens=5\" %a in ('netstat -aon ^| find \":{port}\"') do taskkill /F /PID %a",
+            shell=True, capture_output=True
+        )
+    else:
+        # Linux / macOS
+        result = subprocess.run(
+            f"fuser -k {port}/tcp",
+            shell=True, capture_output=True
+        )
+    # Give the OS a moment to release the port
+    import time
+    time.sleep(0.5)

sicily-0.2.3/Auth/swiggy_auth.py

@@ -0,0 +1,54 @@
+import asyncio
+import hashlib, secrets, base64, time, webbrowser
+import httpx
+from urllib.parse import urlencode
+import os
+
+CLIENT_ID    = os.getenv("SWIGGY_CLIENT_ID")
+REDIRECT_URI = "http://localhost:8000/callback"
+_oauth_code_future = None
+
+_cache = {"token": None, "expires_at": 0}
+
+async def get_valid_token() -> str:
+    """Returns a cached token, or re-runs OAuth if expired."""
+    if _cache["token"] and time.time() < _cache["expires_at"] - 60:
+        return _cache["token"]
+
+    # PKCE
+    verifier  = secrets.token_urlsafe(32)
+    digest    = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+
+    # Open browser for phone + OTP
+    params = urlencode({
+        "response_type":         "code",
+        "client_id":             CLIENT_ID,
+        "redirect_uri":          REDIRECT_URI,
+        "code_challenge":        challenge,
+        "code_challenge_method": "S256",
+        "state":                 secrets.token_urlsafe(16),
+        "scope":                 "mcp:tools",
+    })
+    webbrowser.open(f"https://mcp.swiggy.com/auth/authorize?{params}")
+
+    global _oauth_code_future
+
+    loop = asyncio.get_running_loop()
+    _oauth_code_future = loop.create_future()
+    print("⏳ Waiting for OAuth redirect on http://localhost:8000/callback ...", flush=True)
+    code = await _oauth_code_future
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post("https://mcp.swiggy.com/auth/token", json={
+            "grant_type":    "authorization_code",
+            "code":          code,
+            "code_verifier": verifier,
+            "client_id":     CLIENT_ID,
+            "redirect_uri":  REDIRECT_URI,
+        })
+    
+    token = resp.json()["access_token"]
+    _cache["token"]      = token
+    _cache["expires_at"] = time.time() + 432000  # 5 days
+    return token

sicily-0.2.3/Auth/tavily_auth.py

@@ -0,0 +1,10 @@
+import os
+
+async def get_tavily_config() -> dict:
+    env = os.environ.copy()
+    
+    env.update({
+        "TAVILY_API_KEY": os.environ["TAVILY_API_KEY"],
+    })
+
+    return env

sicily-0.2.3/Auth/telegram_auth.py

@@ -0,0 +1,12 @@
+import os
+
+async def get_telegram_config() -> dict:
+    env = os.environ.copy()
+    
+    env.update({
+        "TELEGRAM_API_ID":         os.environ["TELEGRAM_API_ID"],
+        "TELEGRAM_API_HASH":       os.environ["TELEGRAM_API_HASH"],
+        "TELEGRAM_SESSION_STRING": os.environ["TELEGRAM_SESSION_STRING"],
+    })
+
+    return env

sicily-0.2.3/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: sicily
+Version: 0.2.3
+Summary: Add your description here
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: cryptography>=48.0.1
+Requires-Dist: fastapi>=0.136.1
+Requires-Dist: google-auth-oauthlib>=1.4.0
+Requires-Dist: google-auth>=2.53.0
+Requires-Dist: google-generativeai>=0.8.6
+Requires-Dist: langchain-anthropic>=1.4.3
+Requires-Dist: langchain-core>=1.4.0
+Requires-Dist: langchain-google-genai>=4.2.2
+Requires-Dist: langchain-mcp-adapters>=0.2.2
+Requires-Dist: langchain-openai>=1.2.1
+Requires-Dist: langchain>=1.3.0
+Requires-Dist: langgraph-checkpoint-sqlite>=3.1.0
+Requires-Dist: langgraph>=1.2.0
+Requires-Dist: langsmith>=0.8.3
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: openai>=2.36.0
+Requires-Dist: pyjwt>=2.13.0
+Requires-Dist: pytest>=9.0.3
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: python-multipart>=0.0.30
+Requires-Dist: python-telegram-bot>=22.7
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: requests>=2.34.0
+Requires-Dist: starlette>=1.1.0
+Requires-Dist: structlog>=26.1.0
+Requires-Dist: tiktoken>=0.13.0
+Requires-Dist: uvicorn>=0.46.0
+Description-Content-Type: text/markdown
+
+# Sicily — State-Locked Autonomous Agent Framework & Resilient Tool Orchestrator
+
+A production-grade, cost-efficient, and crash-resilient AI runtime powered by **LangGraph** and **Multi-Transport MCP**. Operating through an asynchronous **Telegram** interface, it can coordinate external tools, execute recurring tasks, maintain long-term memory, and persist workflow state across restarts.
+
+Designed as a persistent personal agent, Sicily emphasizes efficient reasoning, safe automation, and operational reliability.
+
+The system is built around five core principles:
+
+- **Cost-efficient reasoning** — use specialized models, selective context retrieval, and multi-stage tool filtering to maximize accuracy while minimizing token consumption.
+- **Scalable tool orchestration** — dynamically retrieve only the tools relevant to the current request, keeping reasoning focused even as the available toolset grows.
+- **Persistent memory** — learn user preferences over time and inject only contextually relevant information into conversations.
+- **Safe automation** — enforce human approval before executing potentially destructive actions.
+- **Operational resilience** — preserve sessions, checkpoints, and scheduled workflows across downtime and infrastructure failures.
+
+## Architecture Overview
+
+<img src="Images/main_system_workflow.svg" alt="Main System Workflow" width="75%">
+
+A message arrives via Telegram, passes through the FastAPI backend and session manager, then enters the LangGraph state graph. Inside the graph, the system prepares context (injecting relevant user preferences), fetches only the tools needed for this specific request, reasons with the main LLM, optionally pauses for human approval on destructive actions, executes tools, and sends back a response.
+
+---
+
+## Core Capabilities
+
+### Handles Unlimited Tools Without Losing Focus
+
+Most agents fall apart as you add more tools — the context window fills up, costs spike, and the model starts hallucinating wrong tool calls. This system solves that with a **two-stage retrieval pipeline** that filters tools *before* they ever reach the main LLM.
+
+<img src="Images/two_stage_tool_retrieval.svg" alt="Two-Stage Tool Retrieval" width="75%">
+
+**Stage 1 — Intent routing:** A cheap nano model reads the last few messages and decides which *services* are relevant right now (e.g. only Swiggy, not Gmail). Everything else is ignored entirely.
+
+**Stage 2 — Semantic filtering:** Within each selected service, tool descriptions are compared to the query using cosine similarity. Only the most relevant tools per service are passed forward.
+
+The result: the main LLM always sees a short, focused list of tools regardless of how many are registered. You can add so many more tools tomorrow from multiple servers and the model won't know or care about the ones that aren't relevant.
+
+---
+
+### Remembers You — And Gets Better Over Time
+
+The agent builds a personal profile of you automatically. Every session, after you've been idle for some time, an evaluator LLM analyses the conversation and extracts stable behavioural patterns — things like ordering preferences, communication style, time habits, or how you like information presented.
+
+<img src="Images/memory_and_personalization.svg" alt="Memory and Personalization" width="75%">
+
+These are stored as a clean flat list in `preferences.md`. When preferences contradict each other (you said you prefer concise responses last month but now you clearly want detail), the merge step resolves the conflict and keeps only the newer version.
+
+On every new session, only the preferences *relevant to your current request* are retrieved via semantic search and woven into the system prompt. You're not stuffing the context with everything — just what matters right now.
+
+The agent's core personality and tone live separately in `Souls/{name}.md`, which can be swapped out entirely without touching any application logic.
+
+---
+
+### Never Does Anything Destructive Without Asking
+
+Every tool call goes through a three-gate safety pipeline before execution.
+
+<img src="Images/hitl_safety_pipeline.svg" alt="HITL Safety Pipeline" width="75%">
+
+**Gate 1 — Prefix fast-path:** Tools starting with `get_`, `search_`, `read_` are immediately marked safe. No LLM call needed.
+
+**Gate 2 — Heuristic detection:** Tools starting with `update_`, `delete_`, `send_` are flagged as unsafe automatically.
+
+**Gate 3 — LLM safety net:** Anything ambiguous gets evaluated by a dedicated safety LLM that reads the tool description and the arguments being passed.
+
+If a tool is flagged unsafe, the LangGraph graph *pauses* and asks you: approve, abort, or edit the arguments. Nothing happens until you decide. If a tool hallucinated by the model doesn't exist, the executor catches it cleanly and returns a `ToolMessage` saying "Tool not found" — no graph crashes, no cascading errors.
+
+---
+
+### Always On — Scheduled Tasks Run 24/7
+
+The agent doesn't just respond to messages. It proactively executes tasks on a schedule, dispatching them into the main agent the same way a user message would be handled.
+
+<img src="Images/recurring_task_engine.svg" alt="Recurring Task Engine" width="75%">
+
+Tasks are defined in plain YAML — no code changes needed to add, modify, or disable them:
+
+```yaml
+- id: morning_news
+  enabled: true
+  task: "Summarize the top AI news headlines"
+  schedule:
+    mode: daily
+    at: "08:00"
+    days: [mon, tue, wed, thu, fri]
+
+- id: email_check
+  enabled: true
+  task: "Check unread emails and flag anything urgent"
+  schedule:
+    mode: interval
+    every: 30m
+    days: [mon, tue, wed]
+```
+
+Each enabled task gets its own independent async loop. Schedules support daily execution at a specific time, fixed intervals (minutes or hours), and optional weekday filters.
+
+---
+
+### Sessions Survive Server Downtime
+
+Sessions are persisted to SQLite and survive crashes, restarts, and planned downtime. On every boot, the system scans all stored sessions and reconciles them: sessions that expired while the server was down are cleaned up, and valid sessions have their idle timers reconstructed from where they left off.
+
+The LangGraph checkpoint store lives in the same database, so the full conversation context is restored exactly where it was — no lost history, no cold-start on reconnect.
+
+On unexpected shutdown, a 10-second graceful drain gives in-flight tasks time to settle their database commits before the process is force-killed.
+
+---
+
+### Keeps Context Sharp as Conversations Grow Long
+
+Long conversations accumulate fast, especially with tool calls. Once the message history exceeds tokens threshold, the context trimmer kicks in.
+
+<img src="Images/context_trimming.svg" alt="Context Trimming" width="75%">
+
+It walks backward through the message history to find a safe cut point — specifically, it never splits an `AIMessage` (tool call) from its corresponding `ToolMessage` (result), because the OpenAI API rejects sequences where a tool call has no matching result. Everything before the cut is compressed into a single summary message. The active portion of the conversation stays intact.

sicily-0.2.3/README.md

@@ -0,0 +1,115 @@
+# Sicily — State-Locked Autonomous Agent Framework & Resilient Tool Orchestrator
+
+A production-grade, cost-efficient, and crash-resilient AI runtime powered by **LangGraph** and **Multi-Transport MCP**. Operating through an asynchronous **Telegram** interface, it can coordinate external tools, execute recurring tasks, maintain long-term memory, and persist workflow state across restarts.
+
+Designed as a persistent personal agent, Sicily emphasizes efficient reasoning, safe automation, and operational reliability.
+
+The system is built around five core principles:
+
+- **Cost-efficient reasoning** — use specialized models, selective context retrieval, and multi-stage tool filtering to maximize accuracy while minimizing token consumption.
+- **Scalable tool orchestration** — dynamically retrieve only the tools relevant to the current request, keeping reasoning focused even as the available toolset grows.
+- **Persistent memory** — learn user preferences over time and inject only contextually relevant information into conversations.
+- **Safe automation** — enforce human approval before executing potentially destructive actions.
+- **Operational resilience** — preserve sessions, checkpoints, and scheduled workflows across downtime and infrastructure failures.
+
+## Architecture Overview
+
+<img src="Images/main_system_workflow.svg" alt="Main System Workflow" width="75%">
+
+A message arrives via Telegram, passes through the FastAPI backend and session manager, then enters the LangGraph state graph. Inside the graph, the system prepares context (injecting relevant user preferences), fetches only the tools needed for this specific request, reasons with the main LLM, optionally pauses for human approval on destructive actions, executes tools, and sends back a response.
+
+---
+
+## Core Capabilities
+
+### Handles Unlimited Tools Without Losing Focus
+
+Most agents fall apart as you add more tools — the context window fills up, costs spike, and the model starts hallucinating wrong tool calls. This system solves that with a **two-stage retrieval pipeline** that filters tools *before* they ever reach the main LLM.
+
+<img src="Images/two_stage_tool_retrieval.svg" alt="Two-Stage Tool Retrieval" width="75%">
+
+**Stage 1 — Intent routing:** A cheap nano model reads the last few messages and decides which *services* are relevant right now (e.g. only Swiggy, not Gmail). Everything else is ignored entirely.
+
+**Stage 2 — Semantic filtering:** Within each selected service, tool descriptions are compared to the query using cosine similarity. Only the most relevant tools per service are passed forward.
+
+The result: the main LLM always sees a short, focused list of tools regardless of how many are registered. You can add so many more tools tomorrow from multiple servers and the model won't know or care about the ones that aren't relevant.
+
+---
+
+### Remembers You — And Gets Better Over Time
+
+The agent builds a personal profile of you automatically. Every session, after you've been idle for some time, an evaluator LLM analyses the conversation and extracts stable behavioural patterns — things like ordering preferences, communication style, time habits, or how you like information presented.
+
+<img src="Images/memory_and_personalization.svg" alt="Memory and Personalization" width="75%">
+
+These are stored as a clean flat list in `preferences.md`. When preferences contradict each other (you said you prefer concise responses last month but now you clearly want detail), the merge step resolves the conflict and keeps only the newer version.
+
+On every new session, only the preferences *relevant to your current request* are retrieved via semantic search and woven into the system prompt. You're not stuffing the context with everything — just what matters right now.
+
+The agent's core personality and tone live separately in `Souls/{name}.md`, which can be swapped out entirely without touching any application logic.
+
+---
+
+### Never Does Anything Destructive Without Asking
+
+Every tool call goes through a three-gate safety pipeline before execution.
+
+<img src="Images/hitl_safety_pipeline.svg" alt="HITL Safety Pipeline" width="75%">
+
+**Gate 1 — Prefix fast-path:** Tools starting with `get_`, `search_`, `read_` are immediately marked safe. No LLM call needed.
+
+**Gate 2 — Heuristic detection:** Tools starting with `update_`, `delete_`, `send_` are flagged as unsafe automatically.
+
+**Gate 3 — LLM safety net:** Anything ambiguous gets evaluated by a dedicated safety LLM that reads the tool description and the arguments being passed.
+
+If a tool is flagged unsafe, the LangGraph graph *pauses* and asks you: approve, abort, or edit the arguments. Nothing happens until you decide. If a tool hallucinated by the model doesn't exist, the executor catches it cleanly and returns a `ToolMessage` saying "Tool not found" — no graph crashes, no cascading errors.
+
+---
+
+### Always On — Scheduled Tasks Run 24/7
+
+The agent doesn't just respond to messages. It proactively executes tasks on a schedule, dispatching them into the main agent the same way a user message would be handled.
+
+<img src="Images/recurring_task_engine.svg" alt="Recurring Task Engine" width="75%">
+
+Tasks are defined in plain YAML — no code changes needed to add, modify, or disable them:
+
+```yaml
+- id: morning_news
+  enabled: true
+  task: "Summarize the top AI news headlines"
+  schedule:
+    mode: daily
+    at: "08:00"
+    days: [mon, tue, wed, thu, fri]
+
+- id: email_check
+  enabled: true
+  task: "Check unread emails and flag anything urgent"
+  schedule:
+    mode: interval
+    every: 30m
+    days: [mon, tue, wed]
+```
+
+Each enabled task gets its own independent async loop. Schedules support daily execution at a specific time, fixed intervals (minutes or hours), and optional weekday filters.
+
+---
+
+### Sessions Survive Server Downtime
+
+Sessions are persisted to SQLite and survive crashes, restarts, and planned downtime. On every boot, the system scans all stored sessions and reconciles them: sessions that expired while the server was down are cleaned up, and valid sessions have their idle timers reconstructed from where they left off.
+
+The LangGraph checkpoint store lives in the same database, so the full conversation context is restored exactly where it was — no lost history, no cold-start on reconnect.
+
+On unexpected shutdown, a 10-second graceful drain gives in-flight tasks time to settle their database commits before the process is force-killed.
+
+---
+
+### Keeps Context Sharp as Conversations Grow Long
+
+Long conversations accumulate fast, especially with tool calls. Once the message history exceeds tokens threshold, the context trimmer kicks in.
+
+<img src="Images/context_trimming.svg" alt="Context Trimming" width="75%">
+
+It walks backward through the message history to find a safe cut point — specifically, it never splits an `AIMessage` (tool call) from its corresponding `ToolMessage` (result), because the OpenAI API rejects sequences where a tool call has no matching result. Everything before the cut is compressed into a single summary message. The active portion of the conversation stays intact.

sicily-0.2.3/Recurring_Tasks/recurring_tasks.py

@@ -0,0 +1,239 @@
+import asyncio
+import re
+import yaml
+from pathlib import Path
+
+from datetime import datetime, timedelta
+
+YAML_FILE = Path.cwd() / "Recurring_Tasks" / "recurring_tasks.yaml"
+
+_dispatch = None
+
+def set_dispatch(fn):
+    global _dispatch
+    _dispatch = fn
+
+VALID_DAYS = {
+    "mon", "tue", "wed", "thu", "fri", "sat", "sun"
+}
+
+WEEKDAY_MAP = {
+    0: "mon",
+    1: "tue",
+    2: "wed",
+    3: "thu",
+    4: "fri",
+    5: "sat",
+    6: "sun",
+}
+
+
+# PUBLIC ENTRYPOINT
+async def start_recurring_tasks():
+
+    tasks = load_and_validate_yaml()
+
+    enabled_tasks = [t for t in tasks if t["enabled"]]
+
+    print(f"🔁 Starting {len(enabled_tasks)} recurring task(s)...")
+
+    for task_config in enabled_tasks:
+        asyncio.create_task(task_runner(task_config))
+
+
+# YAML LOADING + VALIDATION
+def load_and_validate_yaml():
+
+    with open(YAML_FILE, "r") as f:
+        data = yaml.safe_load(f)
+
+    if not data or "tasks" not in data:
+        raise ValueError("Missing 'tasks' in YAML.")
+
+    tasks = data["tasks"]
+
+    if not isinstance(tasks, list):
+        raise ValueError("'tasks' must be a list.")
+
+    seen_ids = set()
+
+    for task in tasks:
+
+        required_fields = ["id", "enabled", "task", "schedule"]
+
+        for field in required_fields:
+            if field not in task:
+                raise ValueError(f"Task missing required field: {field}")
+
+        task_id = task["id"]
+
+        if task_id in seen_ids:
+            raise ValueError(f"Duplicate task id: {task_id}")
+
+        seen_ids.add(task_id)
+
+        validate_schedule(task_id, task["schedule"])
+
+    return tasks
+
+
+def validate_schedule(task_id, schedule):
+
+    if "mode" not in schedule:
+        raise ValueError(f"[{task_id}] Missing schedule.mode")
+
+    mode = schedule["mode"]
+
+    if mode not in ["daily", "interval"]:
+        raise ValueError(f"[{task_id}] Invalid mode: {mode}")
+
+    # ── DAILY ────────────────────────────────────────────────
+    if mode == "daily":
+
+        if "at" not in schedule:
+            raise ValueError(f"[{task_id}] daily mode requires 'at'")
+
+        validate_time(schedule["at"], task_id)
+
+    # ── INTERVAL ─────────────────────────────────────────────
+    elif mode == "interval":
+
+        if "every" not in schedule:
+            raise ValueError(f"[{task_id}] interval mode requires 'every'")
+
+        validate_interval(schedule["every"], task_id)
+
+        if "start" in schedule:
+            validate_time(schedule["start"], task_id)
+
+    # ── DAYS ────────────────────────────────────────────────
+    if "days" in schedule:
+
+        if not isinstance(schedule["days"], list):
+            raise ValueError(f"[{task_id}] days must be a list")
+
+        for d in schedule["days"]:
+            if d not in VALID_DAYS:
+                raise ValueError(f"[{task_id}] Invalid day: {d}")
+
+
+def validate_time(value, task_id):
+
+    if not re.fullmatch(r"\d{2}:\d{2}", value):
+        raise ValueError(f"[{task_id}] Invalid time format: {value}")
+
+    hour, minute = map(int, value.split(":"))
+
+    if not (0 <= hour <= 23 and 0 <= minute <= 59):
+        raise ValueError(f"[{task_id}] Invalid time: {value}")
+
+
+def validate_interval(value, task_id):
+
+    if not re.fullmatch(r"\d+[mh]", value):
+        raise ValueError(f"[{task_id}] Invalid interval: {value}")
+
+
+# TASK RUNNER
+async def task_runner(task_config):
+
+    task_id = task_config["id"]
+    task_text = task_config["task"]
+    schedule = task_config["schedule"]
+
+    mode = schedule["mode"]
+
+    print(f"✅ Task loaded: {task_id}")
+
+    while True:
+
+        now = datetime.now()
+
+        # DAILY MODE
+        if mode == "daily":
+
+            run_time = build_today_datetime(schedule["at"])
+
+            if run_time <= now:
+                run_time += timedelta(days=1)
+
+            wait_seconds = (run_time - now).total_seconds()
+
+            await asyncio.sleep(wait_seconds)
+
+            if should_run_today(schedule):
+                await execute_task(task_id, task_text)
+
+        # INTERVAL MODE
+        elif mode == "interval":
+
+            if "start" in schedule:
+
+                first_run = build_today_datetime(schedule["start"])
+
+                if first_run > now:
+                    wait_seconds = (first_run - now).total_seconds()
+                    await asyncio.sleep(wait_seconds)
+
+            if should_run_today(schedule):
+                await execute_task(task_id, task_text)
+
+            interval_seconds = parse_interval(schedule["every"])
+
+            await asyncio.sleep(interval_seconds)
+
+
+# HELPERS
+async def execute_task(task_id, task_text):
+
+    print(
+        f"\n🔁 TASK EXECUTED"
+        f"\n🆔 ID   : {task_id}"
+        f"\n📝 Task : {task_text}"
+        f"\n🕒 Time : {datetime.now()}\n",
+        flush=True
+    )
+
+    if _dispatch is None:
+        print(f"⚠️  No dispatch set — skipping task {task_id}")
+        return
+
+    await _dispatch(task_id, task_text)
+
+
+def build_today_datetime(time_str):
+
+    hour, minute = map(int, time_str.split(":"))
+
+    now = datetime.now()
+
+    return now.replace(
+        hour=hour,
+        minute=minute,
+        second=0,
+        microsecond=0
+    )
+
+
+def parse_interval(value):
+
+    amount = int(value[:-1])
+    unit = value[-1]
+
+    if unit == "m":
+        return amount * 60
+
+    if unit == "h":
+        return amount * 60 * 60
+
+    raise ValueError(f"Invalid interval unit: {value}")
+
+
+def should_run_today(schedule):
+
+    if "days" not in schedule:
+        return True
+
+    today = WEEKDAY_MAP[datetime.now().weekday()]
+
+    return today in schedule["days"]