minizen 0.1.0__py3-none-any.whl

minizen/__init__.py

@@ -0,0 +1,29 @@
+"""minizen — A quieter way to stay informed."""
+
+from minizen.ai import DigestAgent, DigestResult
+from minizen.config import (
+    AIConfig,
+    EmailConfig,
+    MinifluxConfig,
+    Settings,
+    load_settings,
+)
+from minizen.core import run_pipeline
+from minizen.providers.email import EmailProvider
+from minizen.providers.rss import Article, MinifluxProvider
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AIConfig",
+    "Article",
+    "DigestAgent",
+    "DigestResult",
+    "EmailConfig",
+    "EmailProvider",
+    "MinifluxConfig",
+    "MinifluxProvider",
+    "Settings",
+    "load_settings",
+    "run_pipeline",
+]

minizen/ai/__init__.py

@@ -0,0 +1,5 @@
+"""Public AI agent API for minizen."""
+
+from minizen.ai.agent import DigestAgent, DigestResult
+
+__all__ = ["DigestAgent", "DigestResult"]

minizen/ai/agent.py

@@ -0,0 +1,74 @@
+import logging
+from typing import cast
+
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent, AgentRunResult
+
+from minizen.providers.rss.miniflux import Article
+
+logger = logging.getLogger(__name__)
+
+_SYSTEM_PROMPT = """\
+You are a personal news curator. You receive a list of unread articles and must:
+1. Select the top N most important and interesting articles.
+2. Write a cohesive, well-structured Markdown digest covering those articles.
+3. Return the digest and the IDs of the articles you selected.
+
+Each article section must include a direct link to the original article URL.
+Be concise. Prioritise articles with broad significance over niche topics.
+"""
+
+
+class DigestResult(BaseModel):
+    """Structured output from the AI digest agent."""
+
+    markdown: str = Field(description="Markdown digest text produced by the agent.")
+    articles_used: list[int] = Field(
+        description="IDs of the articles selected for the digest."
+    )
+
+
+class DigestAgent:
+    """AI-powered agent that selects and summarises articles into a Markdown digest."""
+
+    def __init__(self, *, model: str, top_n: int) -> None:
+        """Initialise the agent with the given model and article limit.
+
+        Args:
+            model: pydantic-ai model identifier (e.g. ``anthropic:claude-haiku-4-5``).
+            top_n: Maximum number of articles to include in the digest.
+        """
+        logger.debug("Initialising DigestAgent: model=%s, top_n=%d", model, top_n)
+        self._top_n = top_n
+        self._agent = Agent(
+            model=model,
+            output_type=DigestResult,
+            system_prompt=_SYSTEM_PROMPT,
+        )
+
+    def run(self, *, articles: list[Article]) -> DigestResult:
+        """Select the top N articles and return a structured Markdown digest.
+
+        Args:
+            articles: Full list of unread articles to choose from.
+
+        Returns:
+            A ``DigestResult`` containing the Markdown text and the IDs of
+            articles that were included.
+        """
+        logger.info("Running AI agent on %d article(s)", len(articles))
+        articles_text = "\n\n---\n\n".join(
+            f"ID: {a.id}\n"
+            f"Feed: {a.feed_name}\n"
+            f"Title: {a.title}\n"
+            f"URL: {a.url}\n"
+            f"Published: {a.published_at.isoformat()}\n\n"
+            f"{a.content}"
+            for a in articles
+        )
+        user_prompt = (
+            f"Please select the top {self._top_n} most important articles "  # noqa: S608
+            f"from the following and write a digest:\n\n{articles_text}"
+        )
+        result = self._agent.run_sync(user_prompt)
+        return cast(AgentRunResult[DigestResult], result).output

minizen/cli/__init__.py

@@ -0,0 +1,34 @@
+from typing import Annotated
+
+import typer
+
+from minizen.cli.commands import (
+    config as config_module,
+    digest as digest_module,
+)
+from minizen.cli.commands.run import run
+from minizen.cli.commands.setup import setup
+from minizen.cli.state import configure_logging
+
+app = typer.Typer(
+    name="minizen",
+    help="A quieter way to stay informed.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def _callback(
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="Enable debug logging."),
+    ] = False,
+) -> None:
+    """Configure logging for the CLI session."""
+    configure_logging(verbose=verbose)
+
+
+app.command("run")(run)
+app.command("setup")(setup)
+app.add_typer(config_module.app, name="config")
+app.add_typer(digest_module.app, name="digest")

minizen/cli/commands/config.py

@@ -0,0 +1,105 @@
+import contextlib
+import tomllib
+from pathlib import Path
+from typing import Annotated
+
+import tomli_w
+import typer
+
+from minizen.config.loader import load_settings
+
+_DEFAULT_CONFIG = Path.home() / ".config" / "minizen" / "config.toml"
+
+_CONFIG_OPTION = Annotated[
+    Path,
+    typer.Option(help="Path to the TOML configuration file.", show_default=True),
+]
+
+app = typer.Typer(help="Inspect and update configuration.")
+
+
+@app.command("show")
+def show(config: _CONFIG_OPTION = _DEFAULT_CONFIG) -> None:
+    """Display the current configuration."""
+    try:
+        with open(config, "rb") as f:
+            data = tomllib.load(f)
+    except FileNotFoundError:
+        typer.echo(f"Config file not found: {config}")
+        typer.echo("Run `minizen setup` to create one.")
+        raise typer.Exit(code=1)
+
+    typer.echo(f"Config file: {config}")
+    mf = data.get("miniflux", {})
+    em = data.get("email", {})
+    ai = data.get("ai", {})
+    typer.echo(f"  miniflux.url:       {mf.get('url', '(unset)')}")
+    typer.echo(f"  miniflux.api_key:   {'(from env)' if mf.get('url') else '(unset)'}")
+    typer.echo(f"  email.smtp_host:    {em.get('smtp_host', '(unset)')}")
+    typer.echo(f"  email.smtp_port:    {em.get('smtp_port', '(unset)')}")
+    typer.echo(f"  email.from_addr:    {em.get('from_addr', '(unset)')}")
+    typer.echo(f"  email.to_addr:      {em.get('to_addr', '(unset)')}")
+    typer.echo(f"  ai.model:           {ai.get('model', 'anthropic:claude-haiku-4-5')}")
+    typer.echo(f"  ai.top_n:           {ai.get('top_n', 5)}")
+
+
+@app.command("validate")
+def validate(config: _CONFIG_OPTION = _DEFAULT_CONFIG) -> None:
+    """Validate the configuration file and environment variables."""
+    try:
+        load_settings(config_path=config)
+    except FileNotFoundError:
+        typer.echo(f"Config file not found: {config}")
+        typer.echo("Run `minizen setup` to create one.")
+        raise typer.Exit(code=1)
+    except KeyError as e:
+        typer.echo(f"Error: missing environment variable {e.args[0]}")
+        raise typer.Exit(code=1)
+    typer.echo("Configuration is valid.")
+
+
+_ALLOWED_KEYS = {
+    "miniflux.url",
+    "ai.model",
+    "ai.top_n",
+    "email.smtp_host",
+    "email.smtp_port",
+    "email.from_addr",
+    "email.to_addr",
+}
+
+
+@app.command("set")
+def set_value(
+    key: Annotated[
+        str, typer.Argument(help="Dot-separated config key (e.g. ai.top_n).")
+    ],
+    value: Annotated[str, typer.Argument(help="New value.")],
+    config: _CONFIG_OPTION = _DEFAULT_CONFIG,
+) -> None:
+    """Set a configuration value in the TOML file."""
+    if key not in _ALLOWED_KEYS:
+        allowed = ", ".join(sorted(_ALLOWED_KEYS))
+        typer.echo(f"Error: unknown config key '{key}'. Allowed: {allowed}")
+        raise typer.Exit(code=1)
+
+    try:
+        with open(config, "rb") as f:
+            data = tomllib.load(f)
+    except FileNotFoundError:
+        typer.echo(f"Config file not found: {config}")
+        typer.echo("Run `minizen setup` to create one.")
+        raise typer.Exit(code=1)
+
+    section, field = key.split(".", 1)
+    if section not in data:
+        data[section] = {}
+
+    # Coerce numeric strings to int
+    coerced: str | int = value
+    with contextlib.suppress(ValueError):
+        coerced = int(value)
+
+    data[section][field] = coerced
+    config.write_bytes(tomli_w.dumps(data).encode())
+    typer.echo(f"Set {key} = {coerced!r}")

minizen/cli/commands/digest.py

@@ -0,0 +1,135 @@
+from datetime import date
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from minizen.ai.agent import DigestAgent
+from minizen.cli.state import configure_logging
+from minizen.config.loader import load_settings
+from minizen.config.models import Settings
+from minizen.providers.email.smtp import EmailProvider
+from minizen.providers.email.template import render_email
+from minizen.providers.rss.miniflux import MinifluxProvider
+
+_DEFAULT_CONFIG = Path.home() / ".config" / "minizen" / "config.toml"
+
+_CONFIG_OPTION = Annotated[
+    Path,
+    typer.Option(help="Path to the TOML configuration file.", show_default=True),
+]
+
+_VERBOSE_OPTION = Annotated[
+    bool,
+    typer.Option("--verbose", "-v", help="Enable debug logging."),
+]
+
+_DRY_RUN_OPTION = Annotated[
+    bool,
+    typer.Option(
+        "--dry-run",
+        help="Fetch articles but skip LLM call and any external sends.",
+    ),
+]
+
+app = typer.Typer(help="Preview or test the digest without marking articles as read.")
+
+
+def _load(config: Path) -> Settings:
+    """Load settings from a TOML file, exiting with an error message on failure.
+
+    Args:
+        config: Path to the TOML configuration file.
+
+    Returns:
+        Fully loaded application settings.
+    """
+    try:
+        return load_settings(config_path=config)
+    except FileNotFoundError:
+        typer.echo(f"Config file not found: {config}")
+        typer.echo("Run `minizen setup` to create one.")
+        raise typer.Exit(code=1)
+    except KeyError as e:
+        typer.echo(f"Error: missing environment variable {e.args[0]}")
+        raise typer.Exit(code=1)
+
+
+@app.command("fetch")
+def fetch(
+    config: _CONFIG_OPTION = _DEFAULT_CONFIG,
+    verbose: _VERBOSE_OPTION = False,
+) -> None:
+    """Fetch unread articles and print their titles and URLs."""
+    configure_logging(verbose=verbose)
+    settings = _load(config)
+    rss = MinifluxProvider(config=settings.miniflux)
+    articles = rss.fetch_unread()
+    if not articles:
+        typer.echo("No unread articles.")
+        return
+    typer.echo(f"{len(articles)} unread article(s):\n")
+    for article in articles:
+        typer.echo(f"[{article.feed_name}] {article.title}")
+        typer.echo(f"  {article.url}")
+
+
+@app.command("preview")
+def preview(
+    config: _CONFIG_OPTION = _DEFAULT_CONFIG,
+    verbose: _VERBOSE_OPTION = False,
+    dry_run: _DRY_RUN_OPTION = False,
+) -> None:
+    """Fetch and summarise articles, then print the Markdown digest."""
+    configure_logging(verbose=verbose)
+    settings = _load(config)
+    rss = MinifluxProvider(config=settings.miniflux)
+    articles = rss.fetch_unread()
+    if not articles:
+        typer.echo("No unread articles.")
+        return
+    if dry_run:
+        typer.echo(f"{len(articles)} unread article(s):\n")
+        for article in articles:
+            typer.echo(f"[{article.feed_name}] {article.title}")
+            typer.echo(f"  {article.url}")
+        return
+    agent = DigestAgent(model=settings.ai.model, top_n=settings.ai.top_n)
+    result = agent.run(articles=articles)
+    typer.echo(result.markdown)
+
+
+@app.command("send-test")
+def send_test(
+    config: _CONFIG_OPTION = _DEFAULT_CONFIG,
+    verbose: _VERBOSE_OPTION = False,
+    dry_run: _DRY_RUN_OPTION = False,
+) -> None:
+    """Send a test digest email without marking articles as read."""
+    configure_logging(verbose=verbose)
+    settings = _load(config)
+    rss = MinifluxProvider(config=settings.miniflux)
+    articles = rss.fetch_unread()
+    if not articles:
+        typer.echo("No unread articles.")
+        return
+    if dry_run:
+        typer.confirm(
+            "This will make a real LLM API call but will not send an email. Continue?",
+            abort=True,
+        )
+    agent = DigestAgent(model=settings.ai.model, top_n=settings.ai.top_n)
+    result = agent.run(articles=articles)
+    html, plain_text = render_email(result.markdown)
+    if dry_run:
+        typer.echo("Dry run — email not sent:\n")
+        typer.echo(plain_text)
+        return
+    today = date.today().strftime("%B %-d, %Y")
+    email = EmailProvider(config=settings.email)
+    email.send(
+        subject=f"[TEST] Your Daily Zen — {today}",
+        html=html,
+        plain_text=plain_text,
+    )
+    typer.echo("Test digest sent.")

minizen/cli/commands/run.py

@@ -0,0 +1,224 @@
+from pathlib import Path
+from typing import Annotated, cast
+
+import typer
+
+from minizen.config.loader import load_settings
+from minizen.config.models import AIConfig, EmailConfig, MinifluxConfig, Settings
+from minizen.core.pipeline import run_pipeline
+
+_DEFAULT_CONFIG = Path.home() / ".config" / "minizen" / "config.toml"
+_DEFAULT_MINIFLUX_URL = "https://reader.miniflux.app"
+_DEFAULT_MODEL = "anthropic:claude-haiku-4-5"
+_DEFAULT_TOP_N = 5
+
+_DRY_RUN_OPTION = Annotated[
+    bool,
+    typer.Option(
+        "--dry-run",
+        help="Fetch articles but skip LLM call, email send, and mark-as-read.",
+    ),
+]
+
+
+def apply_overrides(
+    settings: Settings,
+    *,
+    miniflux_url: str | None = None,
+    miniflux_api_key: str | None = None,
+    model: str | None = None,
+    top_n: int | None = None,
+    from_addr: str | None = None,
+    to_addr: str | None = None,
+    smtp_host: str | None = None,
+    smtp_port: int | None = None,
+    email_username: str | None = None,
+    email_password: str | None = None,
+) -> Settings:
+    """Return a copy of settings with any non-None flag values applied.
+
+    Args:
+        settings: The base settings to override.
+        miniflux_url: Override for miniflux.url.
+        miniflux_api_key: Override for miniflux.api_key.
+        model: Override for ai.model.
+        top_n: Override for ai.top_n.
+        from_addr: Override for email.from_addr.
+        to_addr: Override for email.to_addr.
+        smtp_host: Override for email.smtp_host.
+        smtp_port: Override for email.smtp_port.
+        email_username: Override for email.username.
+        email_password: Override for email.password.
+
+    Returns:
+        A new Settings instance with overrides applied.
+    """
+    miniflux_updates = {
+        k: v
+        for k, v in {"url": miniflux_url, "api_key": miniflux_api_key}.items()
+        if v is not None
+    }
+    ai_updates = {
+        k: v for k, v in {"model": model, "top_n": top_n}.items() if v is not None
+    }
+    email_updates = {
+        k: v
+        for k, v in {
+            "from_addr": from_addr,
+            "to_addr": to_addr,
+            "smtp_host": smtp_host,
+            "smtp_port": smtp_port,
+            "username": email_username,
+            "password": email_password,
+        }.items()
+        if v is not None
+    }
+    return settings.model_copy(
+        deep=True,
+        update={
+            "miniflux": settings.miniflux.model_copy(update=miniflux_updates),
+            "ai": settings.ai.model_copy(update=ai_updates),
+            "email": settings.email.model_copy(update=email_updates),
+        },
+    )
+
+
+def _build_settings_from_flags(
+    *,
+    miniflux_url: str | None,
+    miniflux_api_key: str | None,
+    model: str | None,
+    top_n: int | None,
+    from_addr: str | None,
+    to_addr: str | None,
+    smtp_host: str | None,
+    smtp_port: int | None,
+    email_username: str | None,
+    email_password: str | None,
+) -> Settings:
+    """Build a Settings object entirely from CLI flags.
+
+    Args:
+        miniflux_url: Miniflux base URL (defaults to hosted instance if None).
+        miniflux_api_key: Miniflux API key; required.
+        model: AI model identifier (defaults to claude-haiku-4-5 if None).
+        top_n: Max articles in digest (defaults to 5 if None).
+        from_addr: Sender email address; required.
+        to_addr: Recipient email address; required.
+        smtp_host: SMTP server hostname; required.
+        smtp_port: SMTP server port; required.
+        email_username: SMTP login username; required.
+        email_password: SMTP login password; required.
+
+    Returns:
+        A fully populated Settings instance.
+
+    Raises:
+        typer.Exit: With code 1 if any required field is absent.
+    """
+    required = {
+        "--miniflux-api-key": miniflux_api_key,
+        "--from-addr": from_addr,
+        "--to-addr": to_addr,
+        "--smtp-host": smtp_host,
+        "--smtp-port": smtp_port,
+        "--email-username": email_username,
+        "--email-password": email_password,
+    }
+    missing = [flag for flag, value in required.items() if value is None]
+    if missing:
+        typer.echo("Config file not found. Required flags:")
+        for flag in missing:
+            typer.echo(f"  {flag}")
+        raise typer.Exit(code=1)
+
+    return Settings(
+        miniflux=MinifluxConfig(
+            url=miniflux_url or _DEFAULT_MINIFLUX_URL,
+            api_key=cast(str, miniflux_api_key),
+        ),
+        email=EmailConfig(
+            smtp_host=cast(str, smtp_host),
+            smtp_port=cast(int, smtp_port),
+            from_addr=cast(str, from_addr),
+            to_addr=cast(str, to_addr),
+            username=cast(str, email_username),
+            password=cast(str, email_password),
+        ),
+        ai=AIConfig(
+            model=model or _DEFAULT_MODEL,
+            top_n=top_n or _DEFAULT_TOP_N,
+        ),
+    )
+
+
+def run(
+    config: Annotated[
+        Path,
+        typer.Option(help="Path to the TOML configuration file.", show_default=True),
+    ] = _DEFAULT_CONFIG,
+    dry_run: _DRY_RUN_OPTION = False,
+    miniflux_url: Annotated[
+        str | None,
+        typer.Option("--miniflux-url", help="Miniflux base URL."),
+    ] = None,
+    miniflux_api_key: Annotated[
+        str | None,
+        typer.Option("--miniflux-api-key", help="Miniflux API key."),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", help="AI model identifier."),
+    ] = None,
+    top_n: Annotated[
+        int | None,
+        typer.Option("--top-n", help="Number of top articles to include."),
+    ] = None,
+    from_addr: Annotated[
+        str | None,
+        typer.Option("--from-addr", help="Sender email address."),
+    ] = None,
+    to_addr: Annotated[
+        str | None,
+        typer.Option("--to-addr", help="Recipient email address."),
+    ] = None,
+    smtp_host: Annotated[
+        str | None,
+        typer.Option("--smtp-host", help="SMTP server hostname."),
+    ] = None,
+    smtp_port: Annotated[
+        int | None,
+        typer.Option("--smtp-port", help="SMTP server port."),
+    ] = None,
+    email_username: Annotated[
+        str | None,
+        typer.Option("--email-username", help="SMTP login username."),
+    ] = None,
+    email_password: Annotated[
+        str | None,
+        typer.Option("--email-password", help="SMTP login password."),
+    ] = None,
+) -> None:
+    """Run the full digest pipeline: fetch, summarise, and email."""
+    _flag_kwargs = {
+        "miniflux_url": miniflux_url,
+        "miniflux_api_key": miniflux_api_key,
+        "model": model,
+        "top_n": top_n,
+        "from_addr": from_addr,
+        "to_addr": to_addr,
+        "smtp_host": smtp_host,
+        "smtp_port": smtp_port,
+        "email_username": email_username,
+        "email_password": email_password,
+    }
+    try:
+        settings = load_settings(config_path=config)
+    except FileNotFoundError:
+        settings = _build_settings_from_flags(**_flag_kwargs)
+    except KeyError as e:
+        typer.echo(f"Error: missing environment variable {e.args[0]}")
+        raise typer.Exit(code=1)
+    else:
+        settings = apply_overrides(settings=settings, **_flag_kwargs)
+    run_pipeline(settings=settings, dry_run=dry_run)