keep-up-with 0.1.0__py3-none-any.whl

keep_up_with/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

keep_up_with/cli/agent/events.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from keep_up_with.cli.agent.output import echo_json, echo_jsonl, fail
+from keep_up_with.core.config import get_config
+from keep_up_with.core.events import EventStore
+
+MAX_EVENTS = 100
+
+app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    help="View recorded events",
+    no_args_is_help=True,
+)
+
+
+@app.command("list", help="Print recorded events as JSONL")
+def list_command(
+    limit: Annotated[
+        int | None,
+        typer.Option(
+            "--limit",
+            "-n",
+            help=f"Maximum events to print, hard-capped at {MAX_EVENTS}",
+            min=1,
+            max=MAX_EVENTS,
+        ),
+    ] = None,
+    since: Annotated[
+        str | None,
+        typer.Option(help="Only include events at or after this ISO timestamp"),
+    ] = None,
+    until: Annotated[
+        str | None,
+        typer.Option(help="Only include events at or before this ISO timestamp"),
+    ] = None,
+    query: Annotated[
+        str | None,
+        typer.Option(
+            "--query",
+            "-q",
+            help="Only include events containing this text, e.g. a URL or keyword",
+        ),
+    ] = None,
+) -> None:
+    echo_jsonl(
+        EventStore(get_config()).list_events(
+            limit=limit or MAX_EVENTS,
+            since=since,
+            until=until,
+            query=query,
+        )
+    )
+
+
+@app.command("show", help="Show one event by id or unique prefix")
+def show_command(
+    event_id: Annotated[str, typer.Argument(help="Event id or unique prefix")],
+) -> None:
+    event = EventStore(get_config()).get_event(event_id)
+    if event is None:
+        fail("unknown or ambiguous event", id=event_id)
+    echo_json(event)

keep_up_with/cli/agent/inbox.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from keep_up_with.cli.agent.output import echo_json, echo_jsonl, fail
+from keep_up_with.core.config import get_config
+from keep_up_with.core.events import EventStore
+
+app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    help="Handle pending events",
+    no_args_is_help=True,
+)
+
+
+@app.command("list", help="Print pending events as JSONL")
+def list_command(
+    unnotified: Annotated[
+        bool,
+        typer.Option("--unnotified", help="Only show items not yet sent into Codex"),
+    ] = False,
+    dismissed: Annotated[
+        bool,
+        typer.Option(
+            "--dismissed",
+            help="Show dismissed items with their dispositions instead of pending ones",
+        ),
+    ] = False,
+) -> None:
+    echo_jsonl(
+        EventStore(get_config()).list_inbox(
+            only_unnotified=unnotified,
+            dismissed=dismissed,
+        )
+    )
+
+
+@app.command("dismiss", help="Resolve pending events, recording their disposition")
+def dismiss_command(
+    event_ids: Annotated[
+        list[str],
+        typer.Argument(help="Event ids or unique prefixes; batch ids that share one disposition"),
+    ],
+    reason: Annotated[
+        str,
+        typer.Option(
+            "--reason",
+            help="Disposition: the published message/thread link, the prior coverage, or why it was skipped",
+        ),
+    ],
+) -> None:
+    store = EventStore(get_config())
+    unknown = []
+    for event_id in event_ids:
+        if store.dismiss_inbox(event_id, reason=reason):
+            echo_json({"dismissed": True, "id": event_id, "reason": reason})
+        else:
+            unknown.append(event_id)
+    if unknown:
+        fail("unknown inbox items", ids=unknown)

keep_up_with/cli/agent/main.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import typer
+
+from keep_up_with.cli.agent import events, inbox, message, space, subscriptions, thread, tools
+
+app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    help="Agent-side commands for keep-up-with",
+    no_args_is_help=True,
+)
+
+
+app.add_typer(events.app, name="events")
+app.add_typer(inbox.app, name="inbox")
+app.add_typer(message.app, name="message")
+app.add_typer(space.app, name="space")
+app.add_typer(thread.app, name="thread")
+app.add_typer(tools.app, name="tools")
+app.add_typer(subscriptions.app, name="subs")

keep_up_with/cli/agent/message.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from keep_up_with.cli.agent.output import echo_json, echo_jsonl, fail
+from keep_up_with.core.config import get_config
+from keep_up_with.integrations.registry import messaging_client
+
+app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    help="Send and list messages",
+    no_args_is_help=True,
+)
+
+
+@app.command("send", help="Send a message")
+def send_command(
+    text: Annotated[str, typer.Option("--text", "-t", help="Message text")] = "",
+    channel: Annotated[str | None, typer.Option(help="Channel name or id")] = None,
+    reply_to: Annotated[str | None, typer.Option(help="Message id to reply to")] = None,
+    attachment: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--attachment",
+            "-a",
+            help="File path to attach, repeat for multiple files",
+        ),
+    ] = None,
+) -> None:
+    client = messaging_client(get_config())
+    try:
+        result = asyncio.run(
+            client.send_message(
+                text=text,
+                channel=channel,
+                reply_to=reply_to,
+                attachments=attachment or [],
+            )
+        )
+    except ValueError as error:
+        fail(str(error))
+    echo_json(result)
+
+
+@app.command("list", help="List recent messages")
+def list_command(
+    channel: Annotated[str | None, typer.Option(help="Channel name or id")] = None,
+    thread_id: Annotated[str | None, typer.Option(help="Thread id")] = None,
+    limit: Annotated[
+        int,
+        typer.Option(
+            "--limit", "-n", help="Maximum recent messages to scan per channel"
+        ),
+    ] = 25,
+    query: Annotated[
+        str | None,
+        typer.Option(
+            "--query",
+            "-q",
+            help="Only include messages containing text; without --channel or --thread-id this searches every channel and the DM",
+        ),
+    ] = None,
+    author: Annotated[
+        str | None,
+        typer.Option(help="Only include messages by author id or exact name"),
+    ] = None,
+) -> None:
+    client = messaging_client(get_config())
+    try:
+        messages = asyncio.run(
+            client.list_messages(
+                channel=channel,
+                thread_id=thread_id,
+                limit=limit,
+                query=query,
+                author=author,
+            )
+        )
+    except ValueError as error:
+        fail(str(error))
+    echo_jsonl(messages)
+
+
+@app.command("around", help="Show messages around a message")
+def around_command(
+    message_id: Annotated[str, typer.Argument(help="Message id")],
+    channel: Annotated[str | None, typer.Option(help="Channel name or id")] = None,
+    thread_id: Annotated[str | None, typer.Option(help="Thread id")] = None,
+    before: Annotated[int, typer.Option(help="Messages before the target")] = 10,
+    after: Annotated[int, typer.Option(help="Messages after the target")] = 20,
+) -> None:
+    client = messaging_client(get_config())
+    try:
+        messages = asyncio.run(
+            client.messages_around(
+                message_id=message_id,
+                channel=channel,
+                thread_id=thread_id,
+                before=before,
+                after=after,
+            )
+        )
+    except ValueError as error:
+        fail(str(error))
+    echo_jsonl(messages)
+
+
+@app.command("edit", help="Edit a message")
+def edit_command(
+    message_id: Annotated[str, typer.Argument(help="Message id")],
+    text: Annotated[str, typer.Option("--text", "-t", help="Replacement text")],
+    channel: Annotated[str | None, typer.Option(help="Channel name or id")] = None,
+    thread_id: Annotated[str | None, typer.Option(help="Thread id")] = None,
+) -> None:
+    client = messaging_client(get_config())
+    try:
+        result = asyncio.run(
+            client.edit_message(
+                message_id=message_id,
+                text=text,
+                channel=channel,
+                thread_id=thread_id,
+            )
+        )
+    except ValueError as error:
+        fail(str(error))
+    echo_json(result)
+
+
+@app.command("delete", help="Delete a message")
+def delete_command(
+    message_id: Annotated[str, typer.Argument(help="Message id")],
+    channel: Annotated[str | None, typer.Option(help="Channel name or id")] = None,
+    thread_id: Annotated[str | None, typer.Option(help="Thread id")] = None,
+) -> None:
+    client = messaging_client(get_config())
+    try:
+        asyncio.run(
+            client.delete_message(
+                message_id=message_id,
+                channel=channel,
+                thread_id=thread_id,
+            )
+        )
+    except ValueError as error:
+        fail(str(error))
+    echo_json({"deleted": True, "id": message_id})

keep_up_with/cli/agent/output.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+import typer
+
+
+def echo_json(value: Any, *, err: bool = False) -> None:
+    typer.echo(
+        json.dumps(_jsonable(value), ensure_ascii=False, sort_keys=True),
+        err=err,
+    )
+
+
+def echo_jsonl(values: Any) -> None:
+    for value in values:
+        echo_json(value)
+
+
+def fail(message: str, **extra: Any) -> None:
+    echo_json({"error": message, **extra}, err=True)
+    raise typer.Exit(1)
+
+
+def _jsonable(value: Any) -> Any:
+    if is_dataclass(value):
+        return _jsonable(asdict(value))
+    if isinstance(value, dict):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_jsonable(item) for item in value]
+    return value

keep_up_with/cli/agent/space.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from keep_up_with.cli.agent.output import echo_json, echo_jsonl
+from keep_up_with.core.config import get_config
+from keep_up_with.integrations.registry import messaging_client
+
+app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    help="Manage message space layout",
+    no_args_is_help=True,
+)
+channels_app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    help="Manage channels",
+    no_args_is_help=True,
+)
+sections_app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    help="Manage channel sections",
+    no_args_is_help=True,
+)
+
+
+@channels_app.command("list", help="List channels")
+def list_channels_command() -> None:
+    client = messaging_client(get_config())
+    echo_jsonl(asyncio.run(client.list_channels()))
+
+
+@channels_app.command("create", help="Create a channel")
+def create_channel_command(
+    name: Annotated[str, typer.Option(help="Channel name")],
+    section: Annotated[str | None, typer.Option(help="Section name or id")] = None,
+    description: Annotated[
+        str | None,
+        typer.Option(help="Channel description"),
+    ] = None,
+) -> None:
+    client = messaging_client(get_config())
+    echo_json(
+        asyncio.run(
+            client.create_channel(
+                name=name,
+                section=section,
+                description=description,
+            )
+        )
+    )
+
+
+@channels_app.command("rename", help="Rename a channel")
+def rename_channel_command(
+    channel: Annotated[str, typer.Option(help="Channel name or id")],
+    name: Annotated[str, typer.Option(help="New channel name")],
+) -> None:
+    client = messaging_client(get_config())
+    echo_json(asyncio.run(client.rename_channel(channel=channel, name=name)))
+
+
+@channels_app.command("move", help="Move a channel")
+def move_channel_command(
+    channel: Annotated[str, typer.Option(help="Channel name or id")],
+    section: Annotated[str | None, typer.Option(help="Section name or id")] = None,
+    before: Annotated[
+        str | None,
+        typer.Option(help="Place before this channel name or id"),
+    ] = None,
+    after: Annotated[
+        str | None,
+        typer.Option(help="Place after this channel name or id"),
+    ] = None,
+) -> None:
+    client = messaging_client(get_config())
+    echo_json(
+        asyncio.run(
+            client.move_channel(
+                channel=channel,
+                section=section,
+                before=before,
+                after=after,
+            )
+        )
+    )
+
+
+@sections_app.command("list", help="List channel sections")
+def list_sections_command() -> None:
+    client = messaging_client(get_config())
+    echo_jsonl(asyncio.run(client.list_sections()))
+
+
+@sections_app.command("create", help="Create a channel section")
+def create_section_command(
+    name: Annotated[str, typer.Option(help="Section name")],
+) -> None:
+    client = messaging_client(get_config())
+    echo_json(asyncio.run(client.create_section(name=name)))
+
+
+@sections_app.command("rename", help="Rename a channel section")
+def rename_section_command(
+    section: Annotated[str, typer.Option(help="Section name or id")],
+    name: Annotated[str, typer.Option(help="New section name")],
+) -> None:
+    client = messaging_client(get_config())
+    echo_json(asyncio.run(client.rename_section(section=section, name=name)))
+
+
+@sections_app.command("move", help="Move a channel section")
+def move_section_command(
+    section: Annotated[str, typer.Option(help="Section name or id")],
+    before: Annotated[
+        str | None,
+        typer.Option(help="Place before this section name or id"),
+    ] = None,
+    after: Annotated[
+        str | None,
+        typer.Option(help="Place after this section name or id"),
+    ] = None,
+) -> None:
+    client = messaging_client(get_config())
+    echo_json(
+        asyncio.run(
+            client.move_section(
+                section=section,
+                before=before,
+                after=after,
+            )
+        )
+    )
+
+
+app.add_typer(channels_app, name="channels")
+app.add_typer(sections_app, name="sections")

keep_up_with/cli/agent/subscriptions.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from keep_up_with.cli.agent.output import echo_jsonl
+from keep_up_with.core.config import get_config
+from keep_up_with.integrations.base import DataIntegration, Subscription
+from keep_up_with.integrations.registry import (
+    available_data_integrations,
+    missing_env,
+)
+
+app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    help="List enabled subscriptions",
+    no_args_is_help=True,
+)
+
+
+@app.command("list", help="Print enabled subscriptions as JSONL")
+def list_command() -> None:
+    echo_jsonl(subscription_rows())
+
+
+def subscription_rows() -> list[dict[str, Any]]:
+    config = get_config()
+    rows: list[dict[str, Any]] = []
+    for integration in sorted(available_data_integrations(), key=lambda item: item.name):
+        settings = config.integration(integration.name)
+        enabled = config.integration_enabled(integration.name)
+        if not enabled:
+            continue
+        missing = list(missing_env(config, integration))
+        rows.extend(
+            subscription_row(
+                integration=integration.name,
+                kind="data",
+                enabled=enabled,
+                settings=settings,
+                missing=missing,
+                subscription=subscription,
+                watches=watches(integration, settings),
+            )
+            for subscription in integration.subscriptions
+        )
+    return rows
+
+
+def subscription_row(
+    *,
+    integration: str,
+    kind: str,
+    enabled: bool,
+    settings: dict[str, Any],
+    missing: list[str],
+    subscription: Subscription,
+    watches: dict[str, Any],
+) -> dict[str, Any]:
+    return {
+        "integration": integration,
+        "kind": kind,
+        "subscription": subscription.name,
+        "enabled": enabled,
+        "runnable": enabled and not missing,
+        "interval_seconds": interval_seconds(subscription, settings),
+        "missing_env": missing,
+        "watches": watches,
+    }
+
+
+def interval_seconds(
+    subscription: Subscription,
+    settings: dict[str, Any],
+) -> float | None:
+    if subscription.default_interval_seconds is None:
+        return None
+    return float(settings.get("interval_seconds") or subscription.default_interval_seconds)
+
+
+def watches(integration: DataIntegration, settings: dict[str, Any]) -> dict[str, Any]:
+    return {
+        parameter.name: settings.get(parameter.name) or []
+        for parameter in integration.parameters
+    }