Initial commit: Howl M365 email management daemon
Full implementation of the Howl email triage system: - Microsoft Graph API integration with MSAL auth (client-credentials and delegated modes) - Claude LLM classification via tool use for structured output - PostgreSQL database with customers, vendors, whitelist, and email_log tables - Alembic migration for full schema - APScheduler daemon with graceful shutdown - Typer CLI (run, dry-run, status commands) - Business rule classifier with overrides (whitelist protection, low-confidence fallback) - Action executor (move to folders, flag, escalate with webhook) - 35 passing unit tests - README, SETUP, and NEXT_STEPS documentation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
commit
3bfda9e585
39 changed files with 3656 additions and 0 deletions
53
migrations/env.py
Normal file
53
migrations/env.py
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
from logging.config import fileConfig
|
||||
|
||||
from alembic import context
|
||||
from sqlalchemy import engine_from_config, pool
|
||||
|
||||
from howl.db.models import Base
|
||||
|
||||
config = context.config
|
||||
|
||||
# Allow DATABASE_URL env var to override alembic.ini
|
||||
database_url = os.environ.get("DATABASE_URL", "")
|
||||
if database_url:
|
||||
# Alembic uses psycopg (sync) driver for migrations
|
||||
sync_url = database_url.replace("postgresql+asyncpg://", "postgresql+psycopg://")
|
||||
config.set_main_option("sqlalchemy.url", sync_url)
|
||||
|
||||
if config.config_file_name is not None:
|
||||
fileConfig(config.config_file_name)
|
||||
|
||||
target_metadata = Base.metadata
|
||||
|
||||
|
||||
def run_migrations_offline() -> None:
|
||||
url = config.get_main_option("sqlalchemy.url")
|
||||
context.configure(
|
||||
url=url,
|
||||
target_metadata=target_metadata,
|
||||
literal_binds=True,
|
||||
dialect_opts={"paramstyle": "named"},
|
||||
)
|
||||
with context.begin_transaction():
|
||||
context.run_migrations()
|
||||
|
||||
|
||||
def run_migrations_online() -> None:
|
||||
connectable = engine_from_config(
|
||||
config.get_section(config.config_ini_section, {}),
|
||||
prefix="sqlalchemy.",
|
||||
poolclass=pool.NullPool,
|
||||
)
|
||||
with connectable.connect() as connection:
|
||||
context.configure(connection=connection, target_metadata=target_metadata)
|
||||
with context.begin_transaction():
|
||||
context.run_migrations()
|
||||
|
||||
|
||||
if context.is_offline_mode():
|
||||
run_migrations_offline()
|
||||
else:
|
||||
run_migrations_online()
|
||||
28
migrations/script.py.mako
Normal file
28
migrations/script.py.mako
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
"""${message}
|
||||
|
||||
Revision ID: ${up_revision}
|
||||
Revises: ${down_revision | comma,n}
|
||||
Create Date: ${create_date}
|
||||
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Sequence, Union
|
||||
|
||||
from alembic import op
|
||||
import sqlalchemy as sa
|
||||
${imports if imports else ""}
|
||||
|
||||
# revision identifiers, used by Alembic.
|
||||
revision: str = ${repr(up_revision)}
|
||||
down_revision: Union[str, None] = ${repr(down_revision)}
|
||||
branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
|
||||
depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
${upgrades if upgrades else "pass"}
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
${downgrades if downgrades else "pass"}
|
||||
200
migrations/versions/0001_initial_schema.py
Normal file
200
migrations/versions/0001_initial_schema.py
Normal file
|
|
@ -0,0 +1,200 @@
|
|||
"""Initial schema
|
||||
|
||||
Revision ID: 0001
|
||||
Revises:
|
||||
Create Date: 2026-04-01
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Sequence, Union
|
||||
|
||||
import sqlalchemy as sa
|
||||
from alembic import op
|
||||
from sqlalchemy.dialects import postgresql
|
||||
|
||||
revision: str = "0001"
|
||||
down_revision: Union[str, None] = None
|
||||
branch_labels: Union[str, Sequence[str], None] = None
|
||||
depends_on: Union[str, Sequence[str], None] = None
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
# Enum types
|
||||
sender_type = postgresql.ENUM(
|
||||
"customer", "vendor", "whitelist", "unknown",
|
||||
name="sender_type", create_type=True,
|
||||
)
|
||||
email_action = postgresql.ENUM(
|
||||
"inbox_keep", "flag_follow_up",
|
||||
"move_customer", "move_vendor", "move_whitelist",
|
||||
"move_spam", "move_review", "escalate",
|
||||
name="email_action", create_type=True,
|
||||
)
|
||||
processing_status = postgresql.ENUM(
|
||||
"pending", "processing", "completed", "failed", "skipped",
|
||||
name="processing_status", create_type=True,
|
||||
)
|
||||
sender_type.create(op.get_bind(), checkfirst=True)
|
||||
email_action.create(op.get_bind(), checkfirst=True)
|
||||
processing_status.create(op.get_bind(), checkfirst=True)
|
||||
|
||||
# updated_at trigger function
|
||||
op.execute("""
|
||||
CREATE OR REPLACE FUNCTION set_updated_at()
|
||||
RETURNS TRIGGER AS $$
|
||||
BEGIN
|
||||
NEW.updated_at = NOW();
|
||||
RETURN NEW;
|
||||
END;
|
||||
$$ LANGUAGE plpgsql;
|
||||
""")
|
||||
|
||||
# customers
|
||||
op.create_table(
|
||||
"customers",
|
||||
sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
|
||||
sa.Column("name", sa.Text, nullable=False),
|
||||
sa.Column("company", sa.Text),
|
||||
sa.Column("phone", sa.Text),
|
||||
sa.Column("notes", sa.Text),
|
||||
sa.Column("is_active", sa.Boolean, nullable=False, server_default="TRUE"),
|
||||
sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
)
|
||||
op.execute("""
|
||||
CREATE TRIGGER trg_customers_updated_at
|
||||
BEFORE UPDATE ON customers
|
||||
FOR EACH ROW EXECUTE FUNCTION set_updated_at();
|
||||
""")
|
||||
|
||||
# customer_emails
|
||||
op.create_table(
|
||||
"customer_emails",
|
||||
sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
|
||||
sa.Column("customer_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("customers.id", ondelete="CASCADE"), nullable=False),
|
||||
sa.Column("email_address", sa.Text, nullable=False),
|
||||
sa.Column("label", sa.Text),
|
||||
sa.Column("is_primary", sa.Boolean, nullable=False, server_default="FALSE"),
|
||||
sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
sa.UniqueConstraint("email_address", name="uq_customer_email"),
|
||||
)
|
||||
op.create_index("idx_customer_emails_address", "customer_emails", [sa.text("LOWER(email_address)")])
|
||||
|
||||
# vendors
|
||||
op.create_table(
|
||||
"vendors",
|
||||
sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
|
||||
sa.Column("name", sa.Text, nullable=False),
|
||||
sa.Column("company", sa.Text),
|
||||
sa.Column("service_category", sa.Text),
|
||||
sa.Column("phone", sa.Text),
|
||||
sa.Column("notes", sa.Text),
|
||||
sa.Column("is_active", sa.Boolean, nullable=False, server_default="TRUE"),
|
||||
sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
)
|
||||
op.execute("""
|
||||
CREATE TRIGGER trg_vendors_updated_at
|
||||
BEFORE UPDATE ON vendors
|
||||
FOR EACH ROW EXECUTE FUNCTION set_updated_at();
|
||||
""")
|
||||
|
||||
# vendor_emails
|
||||
op.create_table(
|
||||
"vendor_emails",
|
||||
sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
|
||||
sa.Column("vendor_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("vendors.id", ondelete="CASCADE"), nullable=False),
|
||||
sa.Column("email_address", sa.Text, nullable=False),
|
||||
sa.Column("label", sa.Text),
|
||||
sa.Column("is_primary", sa.Boolean, nullable=False, server_default="FALSE"),
|
||||
sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
sa.UniqueConstraint("email_address", name="uq_vendor_email"),
|
||||
)
|
||||
op.create_index("idx_vendor_emails_address", "vendor_emails", [sa.text("LOWER(email_address)")])
|
||||
|
||||
# whitelist
|
||||
op.create_table(
|
||||
"whitelist",
|
||||
sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
|
||||
sa.Column("email_address", sa.Text),
|
||||
sa.Column("domain", sa.Text),
|
||||
sa.Column("description", sa.Text),
|
||||
sa.Column("added_by", sa.Text),
|
||||
sa.Column("expires_at", sa.DateTime(timezone=True)),
|
||||
sa.Column("is_active", sa.Boolean, nullable=False, server_default="TRUE"),
|
||||
sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
sa.CheckConstraint("email_address IS NOT NULL OR domain IS NOT NULL", name="chk_whitelist_has_target"),
|
||||
)
|
||||
op.create_index(
|
||||
"idx_whitelist_email", "whitelist",
|
||||
[sa.text("LOWER(email_address)")],
|
||||
postgresql_where=sa.text("email_address IS NOT NULL"),
|
||||
)
|
||||
op.create_index(
|
||||
"idx_whitelist_domain", "whitelist",
|
||||
[sa.text("LOWER(domain)")],
|
||||
postgresql_where=sa.text("domain IS NOT NULL"),
|
||||
)
|
||||
|
||||
# email_log
|
||||
op.create_table(
|
||||
"email_log",
|
||||
sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
|
||||
sa.Column("graph_message_id", sa.Text, nullable=False, unique=True),
|
||||
sa.Column("graph_conversation_id", sa.Text),
|
||||
sa.Column("mailbox", sa.Text, nullable=False),
|
||||
sa.Column("sender_address", sa.Text, nullable=False),
|
||||
sa.Column("sender_name", sa.Text),
|
||||
sa.Column("subject", sa.Text),
|
||||
sa.Column("received_at", sa.DateTime(timezone=True)),
|
||||
sa.Column("has_attachments", sa.Boolean, nullable=False, server_default="FALSE"),
|
||||
sa.Column("sender_type", sa.Enum("customer", "vendor", "whitelist", "unknown", name="sender_type", create_type=False), nullable=False, server_default="unknown"),
|
||||
sa.Column("matched_entity_id", postgresql.UUID(as_uuid=True)),
|
||||
sa.Column("matched_entity_table", sa.Text),
|
||||
sa.Column("llm_model", sa.Text),
|
||||
sa.Column("llm_input_tokens", sa.Integer),
|
||||
sa.Column("llm_output_tokens", sa.Integer),
|
||||
sa.Column("llm_raw_response", postgresql.JSONB),
|
||||
sa.Column("llm_classification", sa.Text),
|
||||
sa.Column("llm_confidence", sa.Numeric(4, 3)),
|
||||
sa.Column("llm_reasoning", sa.Text),
|
||||
sa.Column("llm_suggested_action", sa.Enum("inbox_keep", "flag_follow_up", "move_customer", "move_vendor", "move_whitelist", "move_spam", "move_review", "escalate", name="email_action", create_type=False)),
|
||||
sa.Column("final_action", sa.Enum("inbox_keep", "flag_follow_up", "move_customer", "move_vendor", "move_whitelist", "move_spam", "move_review", "escalate", name="email_action", create_type=False), nullable=False, server_default="inbox_keep"),
|
||||
sa.Column("action_overridden", sa.Boolean, nullable=False, server_default="FALSE"),
|
||||
sa.Column("action_executed_at", sa.DateTime(timezone=True)),
|
||||
sa.Column("action_error", sa.Text),
|
||||
sa.Column("status", sa.Enum("pending", "processing", "completed", "failed", "skipped", name="processing_status", create_type=False), nullable=False, server_default="pending"),
|
||||
sa.Column("processing_started_at", sa.DateTime(timezone=True)),
|
||||
sa.Column("processing_completed_at", sa.DateTime(timezone=True)),
|
||||
sa.Column("error_message", sa.Text),
|
||||
sa.Column("retry_count", sa.Integer, nullable=False, server_default="0"),
|
||||
sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
|
||||
)
|
||||
op.create_index("idx_email_log_sender", "email_log", [sa.text("LOWER(sender_address)")])
|
||||
op.create_index(
|
||||
"idx_email_log_status", "email_log", ["status"],
|
||||
postgresql_where=sa.text("status IN ('pending', 'processing')"),
|
||||
)
|
||||
op.create_index("idx_email_log_received", "email_log", [sa.text("received_at DESC")])
|
||||
op.execute("""
|
||||
CREATE TRIGGER trg_email_log_updated_at
|
||||
BEFORE UPDATE ON email_log
|
||||
FOR EACH ROW EXECUTE FUNCTION set_updated_at();
|
||||
""")
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
op.execute("DROP TRIGGER IF EXISTS trg_email_log_updated_at ON email_log")
|
||||
op.drop_table("email_log")
|
||||
op.execute("DROP TRIGGER IF EXISTS trg_vendors_updated_at ON vendors")
|
||||
op.drop_table("vendor_emails")
|
||||
op.drop_table("vendors")
|
||||
op.execute("DROP TRIGGER IF EXISTS trg_customers_updated_at ON customers")
|
||||
op.drop_table("customer_emails")
|
||||
op.drop_table("customers")
|
||||
op.drop_table("whitelist")
|
||||
op.execute("DROP TYPE IF EXISTS sender_type")
|
||||
op.execute("DROP TYPE IF EXISTS email_action")
|
||||
op.execute("DROP TYPE IF EXISTS processing_status")
|
||||
op.execute("DROP FUNCTION IF EXISTS set_updated_at")
|
||||
Loading…
Add table
Add a link
Reference in a new issue