deepagents-talon 0.0.1__py3-none-any.whl

deepagents_talon/__init__.py

@@ -0,0 +1,68 @@
+"""Local runtime host for long-running Deep Agents.
+
+Talon is an experimental runtime and is subject to change or removal at any time.
+"""
+
+from deepagents_talon._version import __version__
+from deepagents_talon.config import TalonConfig
+from deepagents_talon.cron import (
+    CronJob,
+    CronJobError,
+    CronJobStore,
+    CronOrigin,
+    CronSchedule,
+    CronTools,
+    PersistentCronScheduler,
+)
+from deepagents_talon.host import TalonHost
+from deepagents_talon.interfaces import (
+    AgentRequest,
+    AgentResult,
+    AgentRuntime,
+    ChannelAdapter,
+    ChannelMedia,
+    ChannelMessage,
+    ChannelStatus,
+    CronScheduler,
+    ToolApprovalDecision,
+    ToolApprovalHandler,
+    ToolApprovalRequest,
+)
+from deepagents_talon.runtime import DeepAgentRuntime, EchoAgentRuntime, RuntimeAgentComponents
+from deepagents_talon.speech import (
+    DEFAULT_LOCAL_VOICE_TRANSCRIPTION_MODEL,
+    LocalParakeetVoiceTranscriber,
+    OpenAIVoiceTranscriber,
+    VoiceTranscriber,
+)
+
+__all__ = [
+    "DEFAULT_LOCAL_VOICE_TRANSCRIPTION_MODEL",
+    "AgentRequest",
+    "AgentResult",
+    "AgentRuntime",
+    "ChannelAdapter",
+    "ChannelMedia",
+    "ChannelMessage",
+    "ChannelStatus",
+    "CronJob",
+    "CronJobError",
+    "CronJobStore",
+    "CronOrigin",
+    "CronSchedule",
+    "CronScheduler",
+    "CronTools",
+    "DeepAgentRuntime",
+    "EchoAgentRuntime",
+    "LocalParakeetVoiceTranscriber",
+    "OpenAIVoiceTranscriber",
+    "PersistentCronScheduler",
+    "RuntimeAgentComponents",
+    "TalonConfig",
+    "TalonHost",
+    "ToolApprovalDecision",
+    "ToolApprovalHandler",
+    "ToolApprovalRequest",
+    "VoiceTranscriber",
+    "__version__",
+]

deepagents_talon/__main__.py

@@ -0,0 +1,218 @@
+"""Command line entry point for the Talon runtime host.
+
+Talon is an experimental runtime and is subject to change or removal at any time.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import logging
+import os
+import sys
+from typing import TYPE_CHECKING
+
+from deepagents_talon.channels.whatsapp import WhatsAppChannel, WhatsAppChannelConfig
+from deepagents_talon.config import TalonConfig
+from deepagents_talon.cron import CronJobStore, PersistentCronScheduler
+from deepagents_talon.data_lifecycle import cleanup_sensitive_state
+from deepagents_talon.fleet import FleetAgentComponents, load_fleet_agent_components
+from deepagents_talon.host import TalonHost
+from deepagents_talon.mcp import load_mcp_tools, print_mcp_config_paths
+from deepagents_talon.runtime import (
+    DeepAgentRuntime,
+    EchoAgentRuntime,
+    RuntimeAgentComponents,
+)
+from deepagents_talon.speech import build_voice_transcriber
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from deepagents_talon.cron import CronJob
+    from deepagents_talon.interfaces import ChannelAdapter
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    """Run the Talon host with the placeholder runtime."""
+    parser = argparse.ArgumentParser(description="Run the Deep Agents Talon host.")
+    parser.add_argument(
+        "--once",
+        action="store_true",
+        help="Start and stop immediately after bootstrapping the host.",
+    )
+    parser.add_argument(
+        "--whatsapp",
+        action="store_true",
+        help="Attach the WhatsApp channel adapter.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+    _add_mcp_parsers(subparsers)
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s:%(name)s:%(message)s")
+
+    config = TalonConfig.from_env()
+    if args.command == "mcp":
+        sys.exit(asyncio.run(_run_mcp_command(args, config)))
+
+    cron_factory = CronJobStore
+    cron_store = cron_factory(assistant_id=config.assistant_id, cron_dir=config.cron_dir)
+    config.ensure_home()
+    cleanup_sensitive_state(config=config, cron_store=cron_store)
+
+    channels = _channels(config, enabled=args.whatsapp)
+    host = TalonHost(
+        config=config,
+        agent=asyncio.run(_agent_runtime(config, cron_store)),
+        channels=channels,
+        voice_transcriber=build_voice_transcriber(config),
+    )
+    if channels:
+        host.scheduler = PersistentCronScheduler(
+            store=cron_store,
+            run_job=host.run_scheduled_job,
+            deliver_result=lambda job, text: _deliver_cron_result(host, channels, job, text),
+        )
+
+    if args.once:
+        asyncio.run(_run_once(host))
+        return
+
+    asyncio.run(host.run_until_stopped())
+
+
+def _add_mcp_parsers(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    mcp = subparsers.add_parser("mcp", help="Manage MCP servers")
+    mcp_sub = mcp.add_subparsers(dest="mcp_command")
+
+    mcp_sub.add_parser("config", help="Show MCP config discovery paths")
+
+    login = mcp_sub.add_parser("login", help="Run OAuth login for an MCP server")
+    login.add_argument("server", help="Server name from mcpServers")
+    login.add_argument("--mcp-config", dest="config_path", default=None)
+
+
+async def _agent_runtime(
+    config: TalonConfig,
+    cron_store: CronJobStore,
+) -> EchoAgentRuntime | DeepAgentRuntime:
+    env = _runtime_env(config)
+    if config.fleet_dir is not None:
+        fleet_dir = config.fleet_dir
+        components = await load_fleet_agent_components(fleet_dir, env=env)
+        runtime_components = _runtime_components_from_fleet(config, components)
+
+        async def reload_fleet_components() -> RuntimeAgentComponents:
+            refreshed = await load_fleet_agent_components(fleet_dir, env=env)
+            return _runtime_components_from_fleet(config, refreshed)
+
+        return DeepAgentRuntime(
+            model=runtime_components.model,
+            tools=runtime_components.tools,
+            system_prompt=runtime_components.system_prompt,
+            subagents=runtime_components.subagents,
+            skills=runtime_components.skills,
+            middleware=runtime_components.middleware,
+            interrupt_on=runtime_components.interrupt_on,
+            cron_store=cron_store,
+            env=env,
+            reload_agent_components=reload_fleet_components,
+        )
+
+    if config.model is None:
+        return EchoAgentRuntime()
+
+    mcp = await load_mcp_tools(config)
+    for server in mcp.servers:
+        if server.error is not None:
+            logger.warning("MCP server %s failed: %s", server.name, server.error)
+        else:
+            logger.info("MCP server %s loaded %d tool(s)", server.name, len(server.tools))
+    return DeepAgentRuntime(
+        model=config.model,
+        tools=mcp.tools,
+        assistant_dir=config.manifest_dir,
+        cron_store=cron_store,
+        env=env,
+    )
+
+
+def _runtime_components_from_fleet(
+    config: TalonConfig,
+    components: FleetAgentComponents,
+) -> RuntimeAgentComponents:
+    return RuntimeAgentComponents(
+        model=config.model or components.model,
+        tools=components.tools,
+        system_prompt=components.system_prompt,
+        subagents=components.subagents,
+        skills=components.skills,
+        middleware=components.middleware,
+        interrupt_on=components.interrupt_on,
+    )
+
+
+async def _run_mcp_command(args: argparse.Namespace, config: TalonConfig) -> int:
+    if args.mcp_command == "config":
+        print_mcp_config_paths(config)
+        return 0
+    if args.mcp_command == "login":
+        return await _run_mcp_login(args)
+    print("Specify an MCP command: config or login", file=sys.stderr)  # noqa: T201
+    return 2
+
+
+async def _run_mcp_login(args: argparse.Namespace) -> int:
+    try:
+        module = importlib.import_module("deepagents_code.mcp_commands")
+    except ImportError:
+        print(  # noqa: T201
+            "MCP login requires deepagents-code to be installed in this environment.",
+            file=sys.stderr,
+        )
+        return 1
+    run_mcp_login = module.run_mcp_login
+    return await run_mcp_login(server=args.server, config_path=args.config_path)
+
+
+async def _run_once(host: TalonHost) -> None:
+    await host.start()
+    await host.stop()
+
+
+def _channels(config: TalonConfig, *, enabled: bool) -> tuple[ChannelAdapter, ...]:
+    if not enabled and config.env.get("DEEPAGENTS_TALON_WHATSAPP_ENABLED", "").lower() not in {
+        "1",
+        "true",
+        "yes",
+    }:
+        return ()
+    return (WhatsAppChannel(WhatsAppChannelConfig.from_talon_config(config)),)
+
+
+def _runtime_env(config: TalonConfig) -> dict[str, str]:
+    values = dict(os.environ)
+    values.update(config.env)
+    return values
+
+
+async def _deliver_cron_result(
+    host: TalonHost,
+    channels: Sequence[ChannelAdapter],
+    job: CronJob,
+    text: str,
+) -> None:
+    for channel in channels:
+        if job.origin.channel is None or (await channel.status()).provider == job.origin.channel:
+            await host.deliver_scheduled_result(channel, job, text)
+            return
+
+
+if __name__ == "__main__":
+    main()

deepagents_talon/_version.py

@@ -0,0 +1,3 @@
+"""Version marker managed by release-please."""
+
+__version__ = "0.0.1"

deepagents_talon/channels/__init__.py

@@ -0,0 +1,22 @@
+"""Channel integrations for Talon.
+
+Talon is an experimental runtime and is subject to change or removal at any time.
+"""
+
+from deepagents_talon.channels.base import (
+    ChannelExposure,
+    ChannelMediaError,
+    ExposureMode,
+    chunk_text,
+    format_markdown_for_channel,
+    validate_media,
+)
+
+__all__ = [
+    "ChannelExposure",
+    "ChannelMediaError",
+    "ExposureMode",
+    "chunk_text",
+    "format_markdown_for_channel",
+    "validate_media",
+]

deepagents_talon/channels/base.py

@@ -0,0 +1,192 @@
+"""Reusable channel policy and formatting helpers.
+
+Talon is an experimental runtime and is subject to change or removal at any time.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import mimetypes
+import re
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from deepagents_talon.interfaces import ChannelMedia, ChannelMessage
+from deepagents_talon.media import resolve_bounded_media_path
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+MAX_TEXT_CHARS = 4096
+MAX_IMAGE_BYTES = 16 * 1024 * 1024
+MAX_VIDEO_BYTES = 64 * 1024 * 1024
+
+_LINK_PATTERN = re.compile(r"\[([^\]]+)]\(([^)]+)\)")
+_HEADING_PATTERN = re.compile(r"^#{1,6}\s+", flags=re.MULTILINE)
+_BOLD_PATTERN = re.compile(r"\*\*([^*]+)\*\*|__([^_]+)__")
+_ITALIC_PATTERN = re.compile(r"(?<!\*)\*([^*\n]+)\*(?!\*)|_([^_\n]+)_")
+
+
+class ExposureMode(StrEnum):
+    """Who may trigger a channel-backed agent."""
+
+    SELF = "self"
+    ALLOWLIST = "allowlist"
+    OPEN = "open"
+
+
+class ChannelMediaError(ValueError):
+    """Raised when outbound media cannot be sent safely."""
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelExposure:
+    """Inbound exposure policy shared by channel adapters.
+
+    Args:
+        mode: Trigger policy for inbound messages.
+        operator_id: Channel-specific id for the operator's own account.
+        conversations: Conversation ids allowed in allowlist mode.
+        mention_patterns: Glob-style patterns that may allow a message by text.
+    """
+
+    mode: ExposureMode = ExposureMode.SELF
+    operator_id: str | None = None
+    conversations: frozenset[str] = field(default_factory=frozenset)
+    mention_patterns: tuple[str, ...] = ()
+
+    def allows(self, message: ChannelMessage) -> bool:
+        """Return whether an inbound message may trigger the agent.
+
+        Args:
+            message: Inbound message from a channel adapter.
+
+        Returns:
+            `True` when the message passes this exposure policy.
+        """
+        if self.mode == ExposureMode.OPEN:
+            return True
+        if self.mode == ExposureMode.SELF:
+            return _is_self_message(message, self.operator_id)
+        return message.conversation_id in self.conversations or _matches_text(
+            message.text,
+            self.mention_patterns,
+        )
+
+
+def format_markdown_for_channel(text: str) -> str:
+    """Convert common Markdown into conservative WhatsApp-compatible text.
+
+    Args:
+        text: Markdown text returned by the agent.
+
+    Returns:
+        Text with common Markdown constructs mapped to WhatsApp formatting.
+    """
+    value = _HEADING_PATTERN.sub("", text)
+    value = _LINK_PATTERN.sub(r"\1 (\2)", value)
+    value = _ITALIC_PATTERN.sub(lambda match: f"_{match.group(1) or match.group(2)}_", value)
+    return _BOLD_PATTERN.sub(lambda match: f"*{match.group(1) or match.group(2)}*", value)
+
+
+def chunk_text(text: str, *, limit: int = MAX_TEXT_CHARS) -> list[str]:
+    """Split outbound text into channel-sized chunks.
+
+    Args:
+        text: Text to split.
+        limit: Maximum characters per returned chunk.
+
+    Returns:
+        Non-empty chunks no longer than `limit`.
+
+    Raises:
+        ValueError: If `limit` is not positive.
+    """
+    if limit < 1:
+        msg = "chunk limit must be positive"
+        raise ValueError(msg)
+
+    chunks: list[str] = []
+    remaining = text
+    while len(remaining) > limit:
+        split = _split_index(remaining, limit)
+        chunk = remaining[:split].rstrip()
+        chunks.append(chunk or remaining[:limit])
+        remaining = remaining[split:].lstrip()
+    if remaining:
+        chunks.append(remaining)
+    return chunks
+
+
+def validate_media(media: ChannelMedia, *, root: Path | None = None) -> ChannelMedia:
+    """Validate outbound media path, type, and size.
+
+    Args:
+        media: Media payload to validate.
+        root: Optional directory that must contain the media after symlink
+            resolution.
+
+    Returns:
+        The validated media payload.
+
+    Raises:
+        ChannelMediaError: If the file is missing, unsupported, or too large.
+    """
+    try:
+        path = (
+            resolve_bounded_media_path(media.path, root, require_relative=False)
+            if root is not None
+            else media.path.expanduser()
+        )
+    except ValueError as exc:
+        msg = str(exc)
+        raise ChannelMediaError(msg) from exc
+    if not path.is_file():
+        msg = f"media file does not exist: {path}"
+        raise ChannelMediaError(msg)
+
+    detected = _media_type(path)
+    if detected != media.media_type:
+        msg = f"media file type {detected!r} does not match requested type {media.media_type!r}"
+        raise ChannelMediaError(msg)
+
+    limit = MAX_IMAGE_BYTES if media.media_type == "image" else MAX_VIDEO_BYTES
+    size = path.stat().st_size
+    if size > limit:
+        msg = f"{media.media_type} media is too large: {size} bytes exceeds {limit}"
+        raise ChannelMediaError(msg)
+
+    return ChannelMedia(path=path, media_type=media.media_type, caption=media.caption)
+
+
+def _is_self_message(message: ChannelMessage, operator_id: str | None) -> bool:
+    if message.metadata.get("from_self") is True:
+        return True
+    return operator_id is not None and message.sender_id == operator_id
+
+
+def _matches_text(text: str, patterns: tuple[str, ...]) -> bool:
+    return any(fnmatch.fnmatchcase(text, pattern) for pattern in patterns)
+
+
+def _split_index(text: str, limit: int) -> int:
+    window = text[:limit]
+    for delimiter in ("\n\n", "\n", " "):
+        index = window.rfind(delimiter)
+        if index > 0:
+            return index + len(delimiter)
+    return limit
+
+
+def _media_type(path: Path) -> str:
+    mime, _ = mimetypes.guess_type(path)
+    if mime is None:
+        msg = f"unsupported media file type: {path}"
+        raise ChannelMediaError(msg)
+    if mime.startswith("image/"):
+        return "image"
+    if mime.startswith("video/"):
+        return "video"
+    msg = f"unsupported media mime type: {mime}"
+    raise ChannelMediaError(msg)