cortexflow-ai 2.0.0__py3-none-any.whl

cortexflow_ai/agent/session.py

@@ -0,0 +1,168 @@
+"""Per-channel session state management.
+
+Each active channel connection gets one Session. Sessions hold:
+- Short conversation history (last N turns, kept in memory)
+- The channel ID and sender ID that owns the session
+- Metadata: created_at, last_active, turn count
+
+Sessions are intentionally lightweight — heavy memory is offloaded to the
+3-tier MemoryRetrievalPipeline. The in-process history is only the rolling
+window of the current conversation needed for immediate context continuity.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Literal
+
+Role = Literal["user", "assistant", "system"]
+
+
+@dataclass
+class Turn:
+    """One exchange in a conversation."""
+
+    role: Role
+    content: str
+    timestamp: float = field(default_factory=time.time)
+    model: str | None = None  # model that generated this turn (assistant only)
+
+    def to_dict(self) -> dict:
+        return {
+            "role": self.role,
+            "content": self.content,
+            "timestamp": self.timestamp,
+            "model": self.model,
+        }
+
+
+class Session:
+    """Conversation state for one user on one channel.
+
+    Args:
+        channel:    Channel ID ("telegram", "discord", etc.)
+        sender_id:  Platform-specific user identifier.
+        max_turns:  Rolling window size — older turns are dropped.
+                    Default 20 keeps ~10 back-and-forth exchanges in memory.
+    """
+
+    def __init__(
+        self,
+        channel: str,
+        sender_id: str,
+        *,
+        max_turns: int = 20,
+    ) -> None:
+        self.session_id: str = str(uuid.uuid4())
+        self.channel = channel
+        self.sender_id = sender_id
+        self.max_turns = max_turns
+        self.created_at: float = time.time()
+        self.last_active: float = self.created_at
+        self.turn_count: int = 0
+        self._history: list[Turn] = []
+
+    # ------------------------------------------------------------------
+    # History management
+    # ------------------------------------------------------------------
+
+    def add_turn(self, role: Role, content: str, *, model: str | None = None) -> Turn:
+        """Append a turn and enforce the rolling window."""
+        turn = Turn(role=role, content=content, model=model)
+        self._history.append(turn)
+        if len(self._history) > self.max_turns:
+            self._history = self._history[-self.max_turns:]
+        self.last_active = time.time()
+        self.turn_count += 1
+        return turn
+
+    def history(self) -> list[Turn]:
+        """Return a copy of the current history window."""
+        return list(self._history)
+
+    def history_as_dicts(self) -> list[dict]:
+        """Return history as a list of dicts, compatible with LLM message arrays."""
+        return [t.to_dict() for t in self._history]
+
+    def clear(self) -> None:
+        """Reset conversation history (e.g., on /reset command)."""
+        self._history.clear()
+        self.turn_count = 0
+
+    # ------------------------------------------------------------------
+    # Prompt assembly
+    # ------------------------------------------------------------------
+
+    def build_prompt(self, *, include_turns: int | None = None) -> str:
+        """Build a plain-text conversation transcript for LLM prompt injection.
+
+        Args:
+            include_turns: Limit to the last N turns. None = all in window.
+        """
+        turns = self._history[-include_turns:] if include_turns else self._history
+        lines: list[str] = []
+        for t in turns:
+            prefix = "User" if t.role == "user" else "Assistant"
+            lines.append(f"{prefix}: {t.content}")
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def is_fresh(self) -> bool:
+        """True if no user turns have been recorded yet."""
+        return not any(t.role == "user" for t in self._history)
+
+    @property
+    def idle_seconds(self) -> float:
+        return time.time() - self.last_active
+
+    def __repr__(self) -> str:
+        return (
+            f"Session(id={self.session_id[:8]}, channel={self.channel!r}, "
+            f"sender={self.sender_id!r}, turns={self.turn_count})"
+        )
+
+
+class SessionManager:
+    """Registry of active sessions, keyed by (channel, sender_id).
+
+    Sessions expire after ``idle_timeout`` seconds to free memory.
+    Call ``gc()`` periodically or rely on the runtime to do so.
+    """
+
+    def __init__(self, idle_timeout: float = 1800.0, max_turns: int = 20) -> None:
+        self._idle_timeout = idle_timeout
+        self._max_turns = max_turns
+        self._sessions: dict[tuple[str, str], Session] = {}
+
+    def get_or_create(self, channel: str, sender_id: str) -> Session:
+        """Return existing session or create a new one."""
+        key = (channel, sender_id)
+        if key not in self._sessions:
+            self._sessions[key] = Session(channel, sender_id, max_turns=self._max_turns)
+        return self._sessions[key]
+
+    def get(self, channel: str, sender_id: str) -> Session | None:
+        return self._sessions.get((channel, sender_id))
+
+    def remove(self, channel: str, sender_id: str) -> None:
+        self._sessions.pop((channel, sender_id), None)
+
+    def gc(self) -> int:
+        """Remove sessions idle longer than ``idle_timeout``. Returns count removed."""
+        expired = [
+            key for key, s in self._sessions.items()
+            if s.idle_seconds > self._idle_timeout
+        ]
+        for key in expired:
+            del self._sessions[key]
+        return len(expired)
+
+    @property
+    def active_count(self) -> int:
+        return len(self._sessions)

cortexflow_ai/channels/__init__.py

@@ -0,0 +1 @@
+"""Channel adapters — bridges between messaging platforms and the CortexFlow gateway."""

cortexflow_ai/channels/base.py

@@ -0,0 +1,99 @@
+"""Channel adapter abstract base class and shared data types."""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+
+
+@dataclass
+class Attachment:
+    """A file or media attachment from a channel message."""
+
+    type: str  # "image" | "audio" | "video" | "document"
+    url: str | None = None
+    data: bytes | None = None
+    filename: str | None = None
+    mime_type: str | None = None
+
+
+@dataclass
+class InboundMessage:
+    """Normalised inbound message from any channel adapter."""
+
+    channel: str
+    sender_id: str
+    sender_name: str
+    text: str | None
+    attachments: list[Attachment] = field(default_factory=list)
+    thread_id: str | None = None
+    reply_to_id: str | None = None
+    timestamp: float = field(default_factory=time.time)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+#: A coroutine function that handles an inbound message.
+MessageHandler = Callable[[InboundMessage], Awaitable[None]]
+
+
+class ChannelAdapter(ABC):
+    """Abstract base for all platform channel adapters.
+
+    Subclasses must set ``channel_id`` as a class attribute and implement
+    ``connect``, ``disconnect``, and ``send``.
+    """
+
+    channel_id: str  # e.g. "telegram" | "discord" | "slack"
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+        self._handler: MessageHandler | None = None
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish connection to the platform. Raises on failure."""
+        ...
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Gracefully disconnect from the platform."""
+        ...
+
+    @abstractmethod
+    async def send(
+        self,
+        target: str,
+        text: str,
+        *,
+        reply_to: str | None = None,
+        attachments: list[Attachment] | None = None,
+    ) -> str | None:
+        """Send a message to *target* (platform-specific ID).
+
+        Returns the sent message ID if the platform provides one.
+        """
+        ...
+
+    def on_message(self, handler: MessageHandler) -> None:
+        """Register the handler that receives all inbound messages."""
+        self._handler = handler
+
+    async def _dispatch(self, message: InboundMessage) -> None:
+        """Forward *message* to the registered handler (if any)."""
+        if self._handler is not None:
+            await self._handler(message)
+
+    def get_config_schema(self) -> dict[str, Any]:
+        """Return a JSON Schema describing this adapter's config options."""
+        return {
+            "type": "object",
+            "properties": {
+                "enabled": {"type": "boolean", "default": False},
+            },
+            "required": [],
+        }
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(channel_id={self.channel_id!r})"

cortexflow_ai/channels/discord_.py

@@ -0,0 +1,145 @@
+"""Discord channel adapter using discord.py v2."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Any
+
+from cortexflow_ai.channels.base import Attachment, ChannelAdapter, InboundMessage
+
+logger = logging.getLogger(__name__)
+
+
+class DiscordAdapter(ChannelAdapter):
+    """Discord Bot adapter.
+
+    Requires ``discord.py>=2.0`` (``pip install discord.py``).
+
+    Config keys:
+        bot_token (str): Discord bot token. Use ``ENV:DISCORD_BOT_TOKEN``.
+        prefix (str): Command prefix for text commands. Default: ``!``.
+    """
+
+    channel_id = "discord"
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        super().__init__(config)
+        self._client: Any | None = None
+        self._task: asyncio.Task[None] | None = None
+
+    async def connect(self) -> None:
+        try:
+            import discord
+        except ImportError:
+            raise RuntimeError(
+                "Discord adapter requires: pip install 'discord.py>=2.0'"
+            )
+
+        token = self._resolve(self.config.get("bot_token", ""))
+        if not token:
+            raise ValueError("channels.discord.bot_token is required (or set DISCORD_BOT_TOKEN)")
+
+        intents = discord.Intents.default()
+        intents.message_content = True
+        intents.dm_messages = True
+
+        class _BotClient(discord.Client):
+            def __init__(self_inner, adapter: DiscordAdapter, **kwargs: Any) -> None:
+                super().__init__(**kwargs)
+                self_inner._adapter = adapter
+
+            async def on_ready(self_inner) -> None:
+                logger.info("Discord adapter logged in as %s", self_inner.user)
+
+            async def on_message(self_inner, message: discord.Message) -> None:
+                if message.author == self_inner.user:
+                    return
+                attachments = [
+                    Attachment(
+                        type=_guess_type(a.content_type or ""),
+                        url=a.url,
+                        filename=a.filename,
+                        mime_type=a.content_type,
+                    )
+                    for a in message.attachments
+                ]
+                inbound = InboundMessage(
+                    channel=self_inner._adapter.channel_id,
+                    sender_id=str(message.author.id),
+                    sender_name=str(message.author.display_name),
+                    text=message.content or None,
+                    attachments=attachments,
+                    thread_id=str(message.channel.id),
+                    reply_to_id=(
+                        str(message.reference.message_id)
+                        if message.reference
+                        else None
+                    ),
+                    raw={"guild_id": str(message.guild.id) if message.guild else None},
+                )
+                await self_inner._adapter._dispatch(inbound)
+
+        self._client = _BotClient(adapter=self, intents=intents)
+        self._task = asyncio.create_task(self._client.start(token))
+        logger.info("Discord adapter connecting...")
+
+    async def disconnect(self) -> None:
+        if self._client is not None:
+            await self._client.close()
+            self._client = None
+        if self._task is not None:
+            self._task.cancel()
+            self._task = None
+        logger.info("Discord adapter disconnected")
+
+    async def send(
+        self,
+        target: str,
+        text: str,
+        *,
+        reply_to: str | None = None,
+        attachments: list[Attachment] | None = None,
+    ) -> str | None:
+        if self._client is None:
+            raise RuntimeError("DiscordAdapter.connect() has not been called")
+        try:
+            channel = self._client.get_channel(int(target))
+            if channel is None:
+                channel = await self._client.fetch_channel(int(target))
+            msg = await channel.send(content=text)
+            return str(msg.id)
+        except Exception as exc:
+            logger.error("Discord send failed target=%s: %s", target, exc)
+            return None
+
+    @staticmethod
+    def _resolve(value: str) -> str:
+        if value.startswith("ENV:"):
+            return os.getenv(value[4:], "")
+        return value
+
+    def get_config_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "enabled": {"type": "boolean", "default": False},
+                "bot_token": {
+                    "type": "string",
+                    "description": "Bot token from Discord Developer Portal. Use ENV:DISCORD_BOT_TOKEN.",
+                },
+                "prefix": {"type": "string", "default": "!"},
+            },
+            "required": ["bot_token"],
+        }
+
+
+def _guess_type(content_type: str) -> str:
+    if content_type.startswith("image/"):
+        return "image"
+    if content_type.startswith("audio/"):
+        return "audio"
+    if content_type.startswith("video/"):
+        return "video"
+    return "document"

cortexflow_ai/channels/email_.py

@@ -0,0 +1,256 @@
+"""Email channel adapter — IMAP polling (inbound) + SMTP send (outbound).
+
+Works with Gmail, Outlook, Fastmail, or any IMAP/SMTP provider.
+
+Setup (Gmail example):
+    Enable "App Passwords" (requires 2FA):
+    https://myaccount.google.com/apppasswords
+
+    Required config:
+        channels.email.imap_host = "imap.gmail.com"
+        channels.email.smtp_host = "smtp.gmail.com"
+        channels.email.username  = "ENV:EMAIL_USER"
+        channels.email.password  = "ENV:EMAIL_PASSWORD"
+
+Optional config:
+    poll_interval  = 60      # seconds between IMAP checks (default 60)
+    imap_port      = 993     # default SSL port
+    smtp_port      = 587     # default STARTTLS port
+    mailbox        = "INBOX" # folder to watch
+
+Requires:
+    pip install aiosmtplib aioimaplib
+"""
+
+from __future__ import annotations
+
+import asyncio
+import email
+import email.policy
+import logging
+import os
+from email.message import EmailMessage
+from typing import Any
+
+from cortexflow_ai.channels.base import Attachment, ChannelAdapter, InboundMessage
+
+logger = logging.getLogger(__name__)
+
+
+class EmailAdapter(ChannelAdapter):
+    """IMAP+SMTP email channel adapter.
+
+    Polls IMAP on a configurable interval and dispatches new messages.
+    Sends replies via SMTP with proper threading headers (In-Reply-To).
+    """
+
+    channel_id = "email"
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        super().__init__(config)
+        self._imap_host: str = config.get("imap_host", "imap.gmail.com")
+        self._imap_port: int = int(config.get("imap_port", 993))
+        self._smtp_host: str = config.get("smtp_host", "smtp.gmail.com")
+        self._smtp_port: int = int(config.get("smtp_port", 587))
+        self._username: str = self._resolve(config.get("username", ""))
+        self._password: str = self._resolve(config.get("password", ""))
+        self._mailbox: str = config.get("mailbox", "INBOX")
+        self._poll_interval: int = int(config.get("poll_interval", 60))
+        self._task: asyncio.Task | None = None  # type: ignore[type-arg]
+        self._seen_uids: set[str] = set()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> None:
+        if not self._username or not self._password:
+            raise RuntimeError("Email username/password not configured")
+        # Quick connectivity check
+        await self._imap_check()
+        logger.info(
+            "EmailAdapter connected user=%s host=%s poll_interval=%ds",
+            self._username, self._imap_host, self._poll_interval,
+        )
+        self._task = asyncio.create_task(self._poll_loop())
+
+    async def disconnect(self) -> None:
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        logger.info("EmailAdapter disconnected")
+
+    # ------------------------------------------------------------------
+    # Send
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        target: str,
+        text: str,
+        *,
+        reply_to: str | None = None,
+        attachments: list[Attachment] | None = None,
+    ) -> str | None:
+        try:
+            import aiosmtplib  # type: ignore[import]
+        except ImportError:
+            raise RuntimeError("pip install aiosmtplib")
+
+        msg = EmailMessage()
+        msg["From"] = self._username
+        msg["To"] = target
+        msg["Subject"] = "Re: CortexFlow" if reply_to else "CortexFlow"
+        msg.set_content(text)
+
+        if reply_to:
+            msg["In-Reply-To"] = reply_to
+            msg["References"] = reply_to
+
+        await aiosmtplib.send(
+            msg,
+            hostname=self._smtp_host,
+            port=self._smtp_port,
+            username=self._username,
+            password=self._password,
+            start_tls=True,
+        )
+        logger.debug("EmailAdapter sent to=%s", target)
+        return None  # SMTP doesn't return a message ID easily
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    async def _poll_loop(self) -> None:
+        while True:
+            try:
+                await self._imap_check()
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                logger.warning("EmailAdapter poll error: %s", exc)
+            await asyncio.sleep(self._poll_interval)
+
+    async def _imap_check(self) -> None:
+        try:
+            import aioimaplib  # type: ignore[import]
+        except ImportError:
+            raise RuntimeError("pip install aioimaplib")
+
+        client = aioimaplib.IMAP4_SSL(host=self._imap_host, port=self._imap_port)
+        await client.wait_hello_from_server()
+        await client.login(self._username, self._password)
+        await client.select(self._mailbox)
+
+        # Fetch unseen messages
+        _, data = await client.search("UNSEEN")
+        if not data or not data[0]:
+            await client.logout()
+            return
+
+        uids = data[0].decode().split()
+        new_uids = [u for u in uids if u not in self._seen_uids]
+
+        for uid in new_uids:
+            self._seen_uids.add(uid)
+            try:
+                _, msg_data = await client.fetch(uid, "(RFC822)")
+                raw = msg_data[1]
+                if isinstance(raw, bytes):
+                    parsed = email.message_from_bytes(raw, policy=email.policy.default)
+                    await self._dispatch_email(parsed)
+            except Exception as exc:
+                logger.warning("EmailAdapter fetch uid=%s error: %s", uid, exc)
+
+        await client.logout()
+
+    async def _dispatch_email(self, msg: Any) -> None:
+        sender = str(msg.get("From", ""))
+        sender_id = _extract_address(sender)
+        subject = str(msg.get("Subject", ""))
+        message_id = str(msg.get("Message-ID", ""))
+        in_reply_to = str(msg.get("In-Reply-To", "")) or None
+
+        # Extract plain text body
+        body: str | None = None
+        attachments: list[Attachment] = []
+
+        if msg.is_multipart():
+            for part in msg.walk():
+                ct = part.get_content_type()
+                if ct == "text/plain" and body is None:
+                    body = part.get_content()
+                elif ct not in ("text/plain", "text/html", "multipart/mixed", "multipart/alternative"):
+                    filename = part.get_filename()
+                    data = part.get_payload(decode=True)
+                    if data:
+                        attachments.append(
+                            Attachment(
+                                type=_mime_to_type(ct),
+                                data=data,
+                                filename=filename,
+                                mime_type=ct,
+                            )
+                        )
+        else:
+            body = msg.get_content()
+
+        if body:
+            body = body.strip()
+
+        inbound = InboundMessage(
+            channel=self.channel_id,
+            sender_id=sender_id,
+            sender_name=sender_id,
+            text=f"Subject: {subject}\n\n{body}" if subject and body else (body or subject or None),
+            attachments=attachments,
+            thread_id=in_reply_to or message_id,
+            reply_to_id=in_reply_to,
+            raw={"from": sender, "subject": subject, "message_id": message_id},
+        )
+        await self._dispatch(inbound)
+
+    @staticmethod
+    def _resolve(value: str) -> str:
+        if isinstance(value, str) and value.startswith("ENV:"):
+            return os.getenv(value[4:], "")
+        return value
+
+    def get_config_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "enabled": {"type": "boolean", "default": False},
+                "imap_host": {"type": "string", "default": "imap.gmail.com"},
+                "smtp_host": {"type": "string", "default": "smtp.gmail.com"},
+                "imap_port": {"type": "integer", "default": 993},
+                "smtp_port": {"type": "integer", "default": 587},
+                "username": {"type": "string"},
+                "password": {"type": "string"},
+                "mailbox": {"type": "string", "default": "INBOX"},
+                "poll_interval": {"type": "integer", "default": 60},
+            },
+            "required": ["username", "password"],
+        }
+
+
+def _extract_address(header: str) -> str:
+    """Extract raw email address from 'Name <addr>' format."""
+    if "<" in header and ">" in header:
+        return header.split("<")[1].split(">")[0].strip()
+    return header.strip()
+
+
+def _mime_to_type(mime: str) -> str:
+    if mime.startswith("image/"):
+        return "image"
+    if mime.startswith("audio/"):
+        return "audio"
+    if mime.startswith("video/"):
+        return "video"
+    return "document"