pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/conversations/__init__.py

@@ -0,0 +1,8 @@
+"""Conversation management for Pulse — multi-conversation SQLite store."""
+from pulse.conversations.manager import (
+    Conversation,
+    ConversationManager,
+    ConversationTurn,
+)
+
+__all__ = ["Conversation", "ConversationManager", "ConversationTurn"]

pulse/conversations/manager.py

@@ -0,0 +1,312 @@
+"""SQLite-backed Conversation Manager for Pulse.
+
+Supports multiple named conversations, turn storage, auto-titling,
+full-text search, export (Markdown / JSON), and active-conversation tracking.
+
+Database location: <workspace>/.agent/conversations.sqlite3
+"""
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from pulse.sandbox.secrets import SecretScrubber
+from pulse.storage import migrate_database
+
+CONVERSATION_SCHEMA_VERSION = 1
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ConversationTurn:
+    id: int
+    conv_id: str
+    role: str          # "user" | "assistant" | "system"
+    content: str
+    created_at: str
+
+
+@dataclass(frozen=True, slots=True)
+class Conversation:
+    id: str
+    title: str
+    created_at: str
+    updated_at: str
+    turn_count: int = 0
+
+
+# ---------------------------------------------------------------------------
+# ConversationManager
+# ---------------------------------------------------------------------------
+
+
+class ConversationManager:
+    """Thread-safe (single-threaded) façade over a local SQLite conversation store."""
+
+    def __init__(self, workspace: Path, database_path: Path | None = None) -> None:
+        self.workspace = workspace.resolve()
+        self.database_path = (
+            database_path or self.workspace / ".agent" / "conversations.sqlite3"
+        )
+        self._scrubber = SecretScrubber()
+        self._ensure_schema()
+
+    # ------------------------------------------------------------------
+    # Schema bootstrap
+    # ------------------------------------------------------------------
+
+    def _connect(self) -> sqlite3.Connection:
+        self.database_path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(self.database_path)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA foreign_keys=ON")
+        return conn
+
+    def _ensure_schema(self) -> None:
+        def migration(conn: sqlite3.Connection, _current: int) -> None:
+            conn.execute("""CREATE TABLE IF NOT EXISTS conversations (
+                    id         TEXT PRIMARY KEY,
+                    title      TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )""")
+            conn.execute("""CREATE TABLE IF NOT EXISTS turns (
+                    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+                    conv_id    TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+                    role       TEXT NOT NULL,
+                    content    TEXT NOT NULL,
+                    created_at TEXT NOT NULL
+                )""")
+            conn.execute("""CREATE TABLE IF NOT EXISTS meta (
+                    key   TEXT PRIMARY KEY,
+                    value TEXT NOT NULL
+                )""")
+            conn.execute("CREATE INDEX IF NOT EXISTS turns_conv_idx ON turns(conv_id)")
+
+        migrate_database(self.database_path, CONVERSATION_SCHEMA_VERSION, migration)
+
+    # ------------------------------------------------------------------
+    # Conversation CRUD
+    # ------------------------------------------------------------------
+
+    def create(self, title: str | None = None) -> Conversation:
+        """Create a new conversation and set it as the active one."""
+        conv_id = str(uuid.uuid4())
+        now = datetime.now(UTC).isoformat()
+        display_title = self._scrubber.redact(title or "New Conversation")
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO conversations(id, title, created_at, updated_at) VALUES (?, ?, ?, ?)",
+                (conv_id, display_title, now, now),
+            )
+        self.switch(conv_id)
+        return Conversation(id=conv_id, title=display_title, created_at=now, updated_at=now, turn_count=0)
+
+    def auto_title(self, conv_id: str, first_message: str) -> Conversation:
+        """Generate a tidy title from the first user message (≤ 60 chars)."""
+        # Strip punctuation/whitespace, take first 60 chars, capitalize
+        cleaned = re.sub(r"\s+", " ", self._scrubber.redact(first_message).strip())
+        title = cleaned[:60].rstrip(" ,.:;!?")
+        if len(cleaned) > 60:
+            title += "…"
+        return self.rename(conv_id, title or "Conversation")
+
+    def get(self, conv_id: str) -> Conversation | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT id, title, created_at, updated_at FROM conversations WHERE id = ?",
+                (conv_id,),
+            ).fetchone()
+            if row is None:
+                return None
+            count = conn.execute(
+                "SELECT COUNT(*) FROM turns WHERE conv_id = ?", (conv_id,)
+            ).fetchone()[0]
+        return Conversation(id=row[0], title=row[1], created_at=row[2], updated_at=row[3], turn_count=count)
+
+    def list_all(self) -> list[Conversation]:
+        """Return all conversations ordered by most recently updated."""
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT c.id, c.title, c.created_at, c.updated_at, COUNT(t.id) AS turn_count "
+                "FROM conversations c LEFT JOIN turns t ON t.conv_id = c.id "
+                "GROUP BY c.id ORDER BY c.updated_at DESC"
+            ).fetchall()
+        return [Conversation(id=r[0], title=r[1], created_at=r[2], updated_at=r[3], turn_count=r[4]) for r in rows]
+
+    def rename(self, conv_id: str, new_title: str) -> Conversation:
+        new_title = self._scrubber.redact(new_title).strip() or "Untitled"
+        now = datetime.now(UTC).isoformat()
+        with self._connect() as conn:
+            conn.execute(
+                "UPDATE conversations SET title = ?, updated_at = ? WHERE id = ?",
+                (new_title, now, conv_id),
+            )
+        conv = self.get(conv_id)
+        if conv is None:
+            raise ValueError(f"Conversation {conv_id!r} not found.")
+        return conv
+
+    def delete(self, conv_id: str) -> None:
+        """Delete a conversation and all its turns. Clears active if it was active."""
+        with self._connect() as conn:
+            conn.execute("DELETE FROM conversations WHERE id = ?", (conv_id,))
+        # If active conversation was the deleted one, clear it
+        if self._get_meta("active_conv_id") == conv_id:
+            self._set_meta("active_conv_id", "")
+
+    def switch(self, conv_id: str) -> Conversation:
+        """Mark a conversation as the active one. Returns the conversation."""
+        conv = self.get(conv_id)
+        if conv is None:
+            raise ValueError(f"Conversation {conv_id!r} not found.")
+        self._set_meta("active_conv_id", conv_id)
+        return conv
+
+    def get_active(self) -> Conversation | None:
+        """Return the currently active conversation, or None if unset/deleted."""
+        conv_id = self._get_meta("active_conv_id")
+        if not conv_id:
+            return None
+        return self.get(conv_id)
+
+    # ------------------------------------------------------------------
+    # Turn management
+    # ------------------------------------------------------------------
+
+    def add_turn(self, conv_id: str, role: str, content: str) -> ConversationTurn:
+        content = self._scrubber.redact(content)
+        now = datetime.now(UTC).isoformat()
+        with self._connect() as conn:
+            cursor = conn.execute(
+                "INSERT INTO turns(conv_id, role, content, created_at) VALUES (?, ?, ?, ?)",
+                (conv_id, role, content, now),
+            )
+            turn_id = cursor.lastrowid
+            # Bump updated_at on the conversation
+            conn.execute(
+                "UPDATE conversations SET updated_at = ? WHERE id = ?", (now, conv_id)
+            )
+        return ConversationTurn(id=turn_id, conv_id=conv_id, role=role, content=content, created_at=now)
+
+    def get_turns(self, conv_id: str) -> list[ConversationTurn]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT id, conv_id, role, content, created_at FROM turns WHERE conv_id = ? ORDER BY id ASC",
+                (conv_id,),
+            ).fetchall()
+        return [ConversationTurn(id=r[0], conv_id=r[1], role=r[2], content=r[3], created_at=r[4]) for r in rows]
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    def search(self, query: str) -> list[Conversation]:
+        """Full-text LIKE search on conversation titles and turn content."""
+        if not query.strip():
+            return self.list_all()
+        pattern = f"%{query.strip()}%"
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT DISTINCT c.id, c.title, c.created_at, c.updated_at,
+                       (SELECT COUNT(*) FROM turns t2 WHERE t2.conv_id = c.id) AS turn_count
+                FROM conversations c
+                LEFT JOIN turns t ON t.conv_id = c.id
+                WHERE c.title LIKE ? OR t.content LIKE ?
+                ORDER BY c.updated_at DESC
+                """,
+                (pattern, pattern),
+            ).fetchall()
+        return [Conversation(id=r[0], title=r[1], created_at=r[2], updated_at=r[3], turn_count=r[4]) for r in rows]
+
+    # ------------------------------------------------------------------
+    # Export
+    # ------------------------------------------------------------------
+
+    def export(
+        self,
+        conv_id: str,
+        output_path: Path | None = None,
+        fmt: str = "md",
+    ) -> Path:
+        """Export a conversation to Markdown or JSON.
+
+        Args:
+            conv_id: The conversation UUID to export.
+            output_path: Explicit file path, or auto-generated in workspace root.
+            fmt: "md" (default) or "json".
+        """
+        conv = self.get(conv_id)
+        if conv is None:
+            raise ValueError(f"Conversation {conv_id!r} not found.")
+        turns = self.get_turns(conv_id)
+
+        ext = "md" if fmt == "md" else "json"
+        if output_path is None:
+            safe_title = re.sub(r"[^\w\-]", "_", conv.title)[:40]
+            output_path = self.workspace / f"{safe_title}_{conv_id[:8]}.{ext}"
+        else:
+            output_path = Path(output_path)
+
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if fmt == "json":
+            data: dict[str, Any] = {
+                "id": conv.id,
+                "title": conv.title,
+                "created_at": conv.created_at,
+                "updated_at": conv.updated_at,
+                "turns": [
+                    {"role": t.role, "content": t.content, "timestamp": t.created_at}
+                    for t in turns
+                ],
+            }
+            output_path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        else:
+            lines: list[str] = [
+                f"# {conv.title}",
+                "",
+                f"> **Created:** {conv.created_at}  ",
+                f"> **Updated:** {conv.updated_at}",
+                "",
+                "---",
+                "",
+            ]
+            for turn in turns:
+                label = "**You**" if turn.role == "user" else "**Pulse**"
+                lines.append(f"### {label}  ")
+                lines.append(f"*{turn.created_at}*")
+                lines.append("")
+                lines.append(turn.content)
+                lines.append("")
+                lines.append("---")
+                lines.append("")
+            output_path.write_text("\n".join(lines), encoding="utf-8")
+
+        return output_path
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_meta(self, key: str) -> str:
+        with self._connect() as conn:
+            row = conn.execute("SELECT value FROM meta WHERE key = ?", (key,)).fetchone()
+        return str(row[0]) if row else ""
+
+    def _set_meta(self, key: str, value: str) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO meta(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+                (key, value),
+            )

pulse/core/agent.py

@@ -0,0 +1,188 @@
+"""CLI- and provider-independent orchestration for Pulse requests."""
+
+from __future__ import annotations
+
+import asyncio
+from collections import defaultdict
+from collections.abc import AsyncGenerator, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+from uuid import uuid4
+
+from pulse.core.planner import (
+    ExecutionPlan,
+    PlanAction,
+    PlanCondition,
+    PlanGenerator,
+    PlanningRequest,
+    RequestPlanner,
+)
+from pulse.core.protocols import LLMProvider, StreamChunk
+from pulse.tool_registry import ToolInvocation, ToolRegistry, ToolResult
+
+
+@dataclass(frozen=True, slots=True)
+class AgentRequest:
+    message: str
+    conversation_id: str = "default"
+    context: Sequence[str] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class AgentResponse:
+    content: str
+    conversation_id: str
+    request_id: str
+    tool_name: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class ConversationMessage:
+    role: str
+    content: str
+
+
+class ConversationStore(Protocol):
+    async def read(self, conversation_id: str) -> list[ConversationMessage]: ...
+
+    async def append(self, conversation_id: str, message: ConversationMessage) -> None: ...
+
+
+class ContextSource(Protocol):
+    async def context_for(self, request: AgentRequest) -> Sequence[str]: ...
+
+
+class InMemoryConversationStore:
+    """Safe default history store; replace it with persistent memory via DI."""
+
+    def __init__(self) -> None:
+        self._messages: defaultdict[str, list[ConversationMessage]] = defaultdict(list)
+        self._lock = asyncio.Lock()
+
+    async def read(self, conversation_id: str) -> list[ConversationMessage]:
+        async with self._lock:
+            return list(self._messages[conversation_id])
+
+    async def append(self, conversation_id: str, message: ConversationMessage) -> None:
+        async with self._lock:
+            self._messages[conversation_id].append(message)
+
+
+class Agent:
+    """Coordinates request analysis, optional tools, memory, and model streaming.
+
+    The Agent depends only on protocols. CLI adapters supply requests, providers
+    implement ``LLMProvider``, and future memory/planning/tool systems can be
+    injected without changing this public API.
+    """
+
+    def __init__(
+        self,
+        provider: LLMProvider,
+        *,
+        system_prompt: str,
+        conversation_store: ConversationStore | None = None,
+        context_source: ContextSource | None = None,
+        planner: PlanGenerator | None = None,
+        tool_registry: ToolRegistry | None = None,
+    ) -> None:
+        self._provider = provider
+        self._system_prompt = system_prompt
+        self._store = conversation_store or InMemoryConversationStore()
+        self._context_source = context_source
+        self._planner = planner or RequestPlanner()
+        self._tool_registry = tool_registry or ToolRegistry()
+
+    async def respond(self, request: AgentRequest) -> AgentResponse:
+        request_id = str(request.metadata.get("request_id") or uuid4())
+        request = AgentRequest(
+            message=request.message,
+            conversation_id=request.conversation_id,
+            context=request.context,
+            metadata={**request.metadata, "request_id": request_id},
+        )
+        chunks: list[str] = []
+        response_metadata: dict[str, Any] = {}
+        tool_name: str | None = None
+        async for chunk in self.stream(request):
+            chunks.append(chunk.content)
+            response_metadata.update(chunk.metadata)
+            tool_name = str(chunk.metadata.get("tool_name")) if chunk.metadata.get("tool_name") else tool_name
+        return AgentResponse(
+            content="".join(chunks),
+            conversation_id=request.conversation_id,
+            request_id=request_id,
+            tool_name=tool_name,
+            metadata=response_metadata,
+        )
+
+    async def stream(self, request: AgentRequest) -> AsyncGenerator[StreamChunk, None]:
+        """Analyze and execute one request, yielding the final answer incrementally."""
+        if not request.message.strip():
+            raise ValueError("Agent requests must include a message.")
+
+        request_id = str(request.metadata.get("request_id") or uuid4())
+        normalized_request = AgentRequest(
+            message=request.message,
+            conversation_id=request.conversation_id,
+            context=request.context,
+            metadata={**request.metadata, "request_id": request_id},
+        )
+        await self._store.append(normalized_request.conversation_id, ConversationMessage("user", normalized_request.message))
+        plan = await self._planner.plan(PlanningRequest(normalized_request.message, dict(normalized_request.metadata)))
+        context = list(normalized_request.context)
+        tool_result: ToolResult | None = None
+        tool = None
+
+        for step in plan.steps:
+            if step.action is PlanAction.CONTEXT:
+                if self._context_source:
+                    context.extend(await self._context_source.context_for(normalized_request))
+            elif step.action is PlanAction.TOOL:
+                invocation = ToolInvocation(
+                    name=normalized_request.metadata.get("tool_name"),
+                    message=normalized_request.message,
+                    metadata=normalized_request.metadata,
+                )
+                tool = self._tool_registry.match(invocation)
+                if tool and self._condition_allows(step.condition, tool_result, tool_available=True):
+                    tool_result = await self._tool_registry.execute(invocation)
+                    if tool_result and tool_result.terminal:
+                        await self._store.append(normalized_request.conversation_id, ConversationMessage("assistant", tool_result.content))
+                        yield StreamChunk(tool_result.content, {"request_id": request_id, "tool_name": tool.name, "plan": plan, **tool_result.metadata})
+                        return
+            elif step.action is PlanAction.LLM and self._condition_allows(step.condition, tool_result):
+                messages = await self._messages_for(normalized_request, context, tool_result, plan)
+                output: list[str] = []
+                async for chunk in self._provider.generate_stream(messages):
+                    output.append(chunk.content)
+                    yield StreamChunk(chunk.content, {"request_id": request_id, "tool_name": tool.name if tool else None, "plan": plan, **chunk.metadata})
+                await self._store.append(normalized_request.conversation_id, ConversationMessage("assistant", "".join(output)))
+                return
+
+        raise RuntimeError("Execution plan did not contain an executable response step.")
+
+    @staticmethod
+    def _condition_allows(
+        condition: PlanCondition, tool_result: ToolResult | None, *, tool_available: bool = False
+    ) -> bool:
+        if condition is PlanCondition.TOOL_AVAILABLE:
+            return tool_available
+        if condition is PlanCondition.NO_TERMINAL_TOOL_RESULT:
+            return not (tool_result and tool_result.terminal)
+        return True
+
+    async def _messages_for(self, request: AgentRequest, context: list[str], tool_result: ToolResult | None, plan: ExecutionPlan) -> list[dict[str, str]]:
+        history = await self._store.read(request.conversation_id)
+
+        messages = [{"role": "system", "content": self._system_prompt}]
+        messages.extend({"role": item.role, "content": item.content} for item in history)
+        if context:
+            messages.append({"role": "system", "content": "Approved context:\n" + "\n\n".join(context)})
+        if plan:
+            messages.append({"role": "system", "content": "Execution plan:\n" + "\n".join(plan.render())})
+        if tool_result:
+            messages.append({"role": "tool", "content": tool_result.content})
+        return messages

pulse/core/planner.py

@@ -0,0 +1,105 @@
+"""Provider- and tool-independent request planning primitives for Pulse."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, Protocol
+
+
+class PlanAction(StrEnum):
+    """Work the agent runtime can perform for a plan step."""
+
+    CONTEXT = "context"
+    TOOL = "tool"
+    LLM = "llm"
+
+
+class PlanCondition(StrEnum):
+    """Runtime conditions used to select a branch without coupling to tools."""
+
+    ALWAYS = "always"
+    TOOL_AVAILABLE = "tool_available"
+    NO_TERMINAL_TOOL_RESULT = "no_terminal_tool_result"
+
+
+@dataclass(frozen=True, slots=True)
+class PlanningRequest:
+    """The small request shape planners need; adapters keep richer request data."""
+
+    message: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class PlanStep:
+    """One declarative unit of work in an execution plan."""
+
+    id: str
+    action: PlanAction
+    description: str
+    condition: PlanCondition = PlanCondition.ALWAYS
+    depends_on: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionPlan:
+    """An immutable, validated plan suitable for audit and future persistence."""
+
+    goal: str
+    steps: tuple[PlanStep, ...]
+
+    def __post_init__(self) -> None:
+        if not self.goal.strip() or not self.steps:
+            raise ValueError("Plans require a goal and at least one step.")
+        completed: set[str] = set()
+        for step in self.steps:
+            if not step.id or step.id in completed:
+                raise ValueError("Plan step IDs must be unique and non-empty.")
+            if not step.description.strip() or not set(step.depends_on).issubset(completed):
+                raise ValueError("Plan steps may only depend on earlier steps.")
+            completed.add(step.id)
+
+    def render(self) -> tuple[str, ...]:
+        """Human-readable steps for model context and audit records."""
+        return tuple(f"{number}. {step.description}" for number, step in enumerate(self.steps, start=1))
+
+
+class PlanGenerator(Protocol):
+    """Extension point for policy, model, or workflow-specific planners."""
+
+    async def plan(self, request: PlanningRequest) -> ExecutionPlan: ...
+
+
+class RequestPlanner:
+    """Default deterministic planner for safe, inspectable request execution.
+
+    It intentionally knows nothing about providers or registered tools. The
+    runtime evaluates the two conditional branches when it executes the plan.
+    Custom planners can replace this class through dependency injection.
+    """
+
+    async def plan(self, request: PlanningRequest) -> ExecutionPlan:
+        goal = request.message.strip()
+        if not goal:
+            raise ValueError("Planning requests must include a message.")
+        requested_tool = request.metadata.get("tool_name")
+        tool_description = (
+            f"Run requested tool '{requested_tool}' if it is available."
+            if requested_tool
+            else "Run a matching local tool if one can handle this request."
+        )
+        return ExecutionPlan(
+            goal=goal,
+            steps=(
+                PlanStep("collect-context", PlanAction.CONTEXT, "Collect approved context required for the request."),
+                PlanStep("route-tool", PlanAction.TOOL, tool_description, PlanCondition.TOOL_AVAILABLE, ("collect-context",)),
+                PlanStep(
+                    "generate-response",
+                    PlanAction.LLM,
+                    "Generate the final response from the gathered context and tool results.",
+                    PlanCondition.NO_TERMINAL_TOOL_RESULT,
+                    ("route-tool",),
+                ),
+            ),
+        )

pulse/core/protocols.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from pulse.config import ModelConfig
+
+
+@dataclass(slots=True)
+class StreamChunk:
+    """A single streamed token or chunk emitted by an LLM provider."""
+
+    content: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class LLMProvider(Protocol):
+    """Unified structural contract for any AI engine plugged into Pulse."""
+
+    config: ModelConfig
+
+    @property
+    def is_configured(self) -> bool:
+        """Whether the provider has enough credentials to call the model."""
+        ...
+
+    async def generate_stream(
+        self,
+        messages: list[dict[str, Any]],
+        temperature: float = 0.2,
+    ) -> AsyncGenerator[StreamChunk, None]:
+        """Yield streamed response chunks for the provided conversation messages."""
+
+    def chat(self, messages: list[Any], temperature: float = 0.2) -> str:
+        """Return a complete response for the provided conversation messages."""
+        ...