rossum-agent 1.0.0rc0__py3-none-any.whl

rossum_agent/agent/memory.py

@@ -0,0 +1,176 @@
+"""Memory management for the agent.
+
+This module implements the memory storage system following the smolagents pattern:
+- Store structured MemoryStep objects (not raw messages)
+- Rebuild messages fresh each call via write_to_messages()
+- Apply summary_mode for old steps to reduce token usage
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from anthropic.types import MessageParam, TextBlockParam, ThinkingBlockParam, ToolResultBlockParam, ToolUseBlockParam
+
+from rossum_agent.agent.models import ThinkingBlockData, ToolCall, ToolResult
+
+if TYPE_CHECKING:
+    from rossum_agent.agent.types import UserContent
+
+
+@dataclass
+class MemoryStep:
+    """A single step stored in agent memory.
+
+    This is the structured storage format. Steps are converted to messages
+    on-the-fly via to_messages(), allowing summary_mode to compress old steps.
+
+    Attributes:
+        text: Model's text output (reasoning before tool calls, or final answer).
+    """
+
+    step_number: int
+    text: str | None = None
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_results: list[ToolResult] = field(default_factory=list)
+    thinking_blocks: list[ThinkingBlockData] = field(default_factory=list)
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+    def to_messages(self) -> list[MessageParam]:
+        """Convert this step to Anthropic message format.
+
+        For tool-use steps: Includes text block followed by tool_use blocks.
+        For final answer steps: Includes text as assistant content.
+
+        Returns:
+            List of message dicts for the Anthropic API.
+        """
+        messages: list[MessageParam] = []
+
+        if self.tool_calls:
+            assistant_content: list[TextBlockParam | ToolUseBlockParam | ThinkingBlockParam] = [
+                tb.to_dict() for tb in self.thinking_blocks
+            ]
+
+            if self.text:
+                assistant_content.append(TextBlockParam(type="text", text=self.text))
+
+            assistant_content.extend(
+                ToolUseBlockParam(type="tool_use", id=tc.id, name=tc.name, input=tc.arguments)
+                for tc in self.tool_calls
+            )
+
+            messages.append(MessageParam(role="assistant", content=assistant_content))
+
+            if self.tool_results:
+                tool_result_blocks = [
+                    ToolResultBlockParam(
+                        type="tool_result",
+                        tool_use_id=tr.tool_call_id,
+                        content=tr.content,
+                        is_error=tr.is_error,
+                    )
+                    for tr in self.tool_results
+                ]
+                messages.append(MessageParam(role="user", content=tool_result_blocks))
+
+        elif self.text:
+            messages.append(MessageParam(role="assistant", content=self.text))
+
+        return messages
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary for storage."""
+        return {
+            "type": "memory_step",
+            "step_number": self.step_number,
+            "text": self.text,
+            "tool_calls": [tc.to_dict() for tc in self.tool_calls],
+            "tool_results": [tr.to_dict() for tr in self.tool_results],
+            "thinking_blocks": [tb.to_dict() for tb in self.thinking_blocks],
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> MemoryStep:
+        """Deserialize from dictionary."""
+        return cls(
+            step_number=data.get("step_number", 0),
+            text=data.get("text"),
+            tool_calls=[ToolCall.from_dict(tc) for tc in data.get("tool_calls", [])],
+            tool_results=[ToolResult.from_dict(tr) for tr in data.get("tool_results", [])],
+            thinking_blocks=[ThinkingBlockData.from_dict(tb) for tb in data.get("thinking_blocks", [])],
+            input_tokens=data.get("input_tokens", 0),
+            output_tokens=data.get("output_tokens", 0),
+        )
+
+
+@dataclass
+class TaskStep:
+    """Represents the initial user task/prompt.
+
+    Supports both text-only and multimodal content (with images).
+    """
+
+    task: UserContent
+
+    def to_messages(self) -> list[MessageParam]:
+        return [MessageParam(role="user", content=self.task)]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary for storage."""
+        return {"type": "task_step", "task": self.task}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TaskStep:
+        """Deserialize from dictionary."""
+        return cls(task=data["task"])
+
+
+@dataclass
+class AgentMemory:
+    """Memory storage for agent steps.
+
+    Stores structured step objects and rebuilds messages on demand.
+    """
+
+    steps: list[TaskStep | MemoryStep] = field(default_factory=list)
+
+    def reset(self) -> None:
+        """Clear all steps."""
+        self.steps = []
+
+    def add_task(self, task: UserContent) -> None:
+        """Add initial user task (text or multimodal content)."""
+        self.steps.append(TaskStep(task=task))
+
+    def add_step(self, step: MemoryStep) -> None:
+        """Add a completed agent step."""
+        self.steps.append(step)
+
+    def write_to_messages(self) -> list[MessageParam]:
+        """Convert all steps to messages.
+
+        Returns:
+            List of message dicts ready for Anthropic API.
+        """
+        return [msg for step in self.steps for msg in step.to_messages()]
+
+    def to_dict(self) -> list[dict[str, Any]]:
+        """Serialize all steps to a list of dictionaries for storage."""
+        return [step.to_dict() for step in self.steps]
+
+    @classmethod
+    def from_dict(cls, data: list[dict[str, Any]]) -> AgentMemory:
+        """Deserialize from a list of step dictionaries."""
+        memory = cls()
+        for step_data in data:
+            step_type = step_data.get("type")
+            if step_type == "task_step":
+                memory.steps.append(TaskStep.from_dict(step_data))
+            elif step_type == "memory_step":
+                memory.steps.append(MemoryStep.from_dict(step_data))
+        return memory

rossum_agent/agent/models.py

@@ -0,0 +1,160 @@
+"""Data models for the agent module.
+
+This module contains the core data classes used throughout the agent system
+for representing tool calls, results, and agent steps.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Literal
+
+from anthropic.types import ThinkingBlockParam
+
+
+class StepType(Enum):
+    """Type of streaming step for distinguishing UI rendering."""
+
+    THINKING = "thinking"
+    INTERMEDIATE = "intermediate"
+    FINAL_ANSWER = "final_answer"
+
+
+if TYPE_CHECKING:
+    from rossum_agent.tools import SubAgentProgress
+
+
+@dataclass
+class ToolCall:
+    """Represents a single tool call made by the agent."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary for storage."""
+        return {"id": self.id, "name": self.name, "arguments": self.arguments}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolCall:
+        """Deserialize from dictionary."""
+        return cls(id=data["id"], name=data["name"], arguments=data.get("arguments", {}))
+
+
+@dataclass
+class ToolResult:
+    """Represents the result of a tool call."""
+
+    tool_call_id: str
+    name: str
+    content: str
+    is_error: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary for storage."""
+        return {
+            "tool_call_id": self.tool_call_id,
+            "name": self.name,
+            "content": self.content,
+            "is_error": self.is_error,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolResult:
+        """Deserialize from dictionary."""
+        return cls(
+            tool_call_id=data["tool_call_id"],
+            name=data["name"],
+            content=data.get("content", ""),
+            is_error=data.get("is_error", False),
+        )
+
+
+@dataclass
+class StreamDelta:
+    """A tagged delta from stream processing - either thinking or text."""
+
+    kind: Literal["thinking", "text"]
+    content: str
+
+
+@dataclass
+class ThinkingBlockData:
+    """Represents a thinking block from extended thinking.
+
+    Must be preserved and passed back to the API when continuing tool use conversations.
+    """
+
+    thinking: str
+    signature: str
+
+    def to_dict(self) -> ThinkingBlockParam:
+        """Serialize to dictionary for storage and API message format."""
+        return ThinkingBlockParam(type="thinking", thinking=self.thinking, signature=self.signature)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ThinkingBlockData:
+        """Deserialize from dictionary."""
+        return cls(thinking=data["thinking"], signature=data["signature"])
+
+
+@dataclass
+class AgentStep:
+    """Represents a single step in the agent's execution (for yielding to caller).
+
+    This is the public-facing step object yielded during agent.run().
+    Different from MemoryStep which is for internal storage.
+    """
+
+    step_number: int
+    thinking: str | None = None
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_results: list[ToolResult] = field(default_factory=list)
+    final_answer: str | None = None
+    is_final: bool = False
+    error: str | None = None
+    is_streaming: bool = False
+    input_tokens: int = 0
+    output_tokens: int = 0
+    current_tool: str | None = None
+    tool_progress: tuple[int, int] | None = None
+    sub_agent_progress: SubAgentProgress | None = None
+    text_delta: str | None = None
+    accumulated_text: str | None = None
+    step_type: StepType | None = None
+
+    def has_tool_calls(self) -> bool:
+        """Check if this step contains tool calls."""
+        return bool(self.tool_calls)
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for the RossumAgent."""
+
+    max_output_tokens: int = 64000  # Opus 4.5 limit
+    max_steps: int = 50
+    temperature: float = 1.0  # Required for extended thinking
+    request_delay: float = 3.0  # Delay in seconds between API calls to avoid rate limiting
+    thinking_budget_tokens: int = 10000  # Budget for extended thinking (min 1024)
+
+    def __post_init__(self) -> None:
+        if self.temperature != 1.0:
+            msg = "temperature must be 1.0 when extended thinking is enabled"
+            raise ValueError(msg)
+        if self.thinking_budget_tokens < 1024:
+            msg = "thinking_budget_tokens must be at least 1024"
+            raise ValueError(msg)
+
+
+MAX_TOOL_OUTPUT_LENGTH = 20000
+
+
+def truncate_content(content: str, max_length: int = MAX_TOOL_OUTPUT_LENGTH) -> str:
+    """Truncate content preserving head and tail."""
+    if len(content) <= max_length:
+        return content
+    half = max_length // 2
+    return content[:half] + f"\n..._Content truncated to stay below {max_length} characters_...\n" + content[-half:]

rossum_agent/agent/request_classifier.py

@@ -0,0 +1,152 @@
+"""Lightweight request classifier for filtering out-of-scope requests.
+
+This module provides a fast pre-filter that checks if a user request is within
+the scope of the Rossum platform assistant before engaging the full agent.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from rossum_agent.bedrock_client import get_small_model_id
+
+if TYPE_CHECKING:
+    from anthropic import AnthropicBedrock
+
+logger = logging.getLogger(__name__)
+
+CLASSIFIER_PROMPT = """You are a scope classifier for a Rossum document processing platform assistant.
+
+The assistant can help with:
+- Queue, hook, schema, and extension analysis/configuration
+- Debugging document processing issues and errors
+- Investigating hook logs and extension behavior
+- Explaining workflows and automation
+- Writing analysis reports about Rossum configuration issues
+
+IN_SCOPE: Request relates to Rossum PLATFORM operations
+- setting up new organization
+- analyzing/configuring queues, hooks, schemas, extensions
+- debugging errors, investigating logs
+- explaining workflows, analysis
+- generating structured report of customer use-cases on the platform
+- generating formula fields suggestions
+- Also: user asks what the assistant can do, greets assistant
+
+OUT_OF_SCOPE: Request is for DATA analytics - aggregating extracted data, generating charts/plots from document data, summarizing line items/amounts across documents, creating files unrelated to Rossum debugging. Even if it mentions Rossum annotations, if the goal is data aggregation/visualization, it's OUT_OF_SCOPE.
+
+Examples:
+- "Investigate errors with document splitting on queue X" → IN_SCOPE (debugging)
+- "Aggregate line item amounts and generate a bar chart" → OUT_OF_SCOPE (data analytics)
+- "Create a markdown saying hello" → OUT_OF_SCOPE (generic file creation)
+
+Respond with exactly one word: IN_SCOPE or OUT_OF_SCOPE
+
+User request: {message}"""
+
+CLASSIFIER_MAX_TOKENS = 10
+
+
+class RequestScope(Enum):
+    """Classification result for a user request."""
+
+    IN_SCOPE = "IN_SCOPE"
+    OUT_OF_SCOPE = "OUT_OF_SCOPE"
+
+
+@dataclass
+class ClassificationResult:
+    """Result of request classification."""
+
+    scope: RequestScope
+    raw_response: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+@dataclass
+class RejectionResult:
+    """Result of rejection response generation."""
+
+    response: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+REJECTION_PROMPT = """You are an expert Rossum platform specialist. The user made a request that is outside your scope.
+
+I can help with:
+- Analyzing and debugging hooks, extensions, and workflows
+- Documenting queue configurations
+- Investigating processing errors
+- Configuring automation
+
+The user asked: {message}
+
+Write a brief, helpful response that:
+1. Politely explains this is outside your Rossum platform expertise
+2. Briefly mentions 2-3 relevant things you CAN help with from the capabilities above
+3. Asks if they have any Rossum-related questions
+
+Keep it concise (3-4 sentences max). Be friendly, not robotic."""
+
+REJECTION_MAX_TOKENS = 300
+
+
+def generate_rejection_response(client: AnthropicBedrock, message: str) -> RejectionResult:
+    """Generate a contextual rejection response for out-of-scope requests."""
+    prompt = REJECTION_PROMPT.format(message=message)
+    try:
+        response = client.messages.create(
+            model=get_small_model_id(), max_tokens=REJECTION_MAX_TOKENS, messages=[{"role": "user", "content": prompt}]
+        )
+        text = response.content[0].text.strip() if response.content else _fallback_response()
+        return RejectionResult(
+            response=text, input_tokens=response.usage.input_tokens, output_tokens=response.usage.output_tokens
+        )
+    except Exception as e:
+        logger.warning(f"Rejection response generation failed: {e}")
+        return RejectionResult(response=_fallback_response())
+
+
+def _fallback_response() -> str:
+    return (
+        "I'm an expert Rossum platform specialist focused on document processing workflows. "
+        "Your request appears to be outside my area of expertise. "
+        "I can help with analyzing hooks, debugging extensions, documenting queue configurations, "
+        "and configuring automation workflows. Do you have any Rossum-related questions?"
+    )
+
+
+def classify_request(client: AnthropicBedrock, message: str) -> ClassificationResult:
+    """Classify whether a user request is within scope.
+
+    Uses a fast, cheap model (Haiku) with minimal tokens to quickly determine if the request should be processed by the main agent.
+    """
+    prompt = CLASSIFIER_PROMPT.format(message=message)
+
+    try:
+        response = client.messages.create(
+            model=get_small_model_id(),
+            max_tokens=CLASSIFIER_MAX_TOKENS,
+            messages=[{"role": "user", "content": prompt}],
+        )
+
+        raw_response = response.content[0].text.strip().upper() if response.content else ""
+
+        scope = RequestScope.OUT_OF_SCOPE if "OUT_OF_SCOPE" in raw_response else RequestScope.IN_SCOPE
+
+        logger.debug(f"Request classified as {scope.value}: {message[:50]}...")
+        return ClassificationResult(
+            scope=scope,
+            raw_response=raw_response,
+            input_tokens=response.usage.input_tokens,
+            output_tokens=response.usage.output_tokens,
+        )
+
+    except Exception as e:
+        logger.warning(f"Classification failed, defaulting to IN_SCOPE: {e}")
+        return ClassificationResult(scope=RequestScope.IN_SCOPE, raw_response=f"error: {e}")

rossum_agent/agent/skills.py

@@ -0,0 +1,132 @@
+"""Skills module for loading and managing agent skills.
+
+Skills are markdown files that provide domain-specific instructions and workflow to the agent. They are loaded
+from the skills directory and injected into the agent's system prompt.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Default skills directory path relative to rossum_agent package
+_SKILLS_DIR = Path(__file__).parent.parent / "skills"
+
+
+@dataclass
+class Skill:
+    """Represents a loaded skill with its content and metadata."""
+
+    name: str
+    content: str
+    file_path: Path
+
+    @property
+    def slug(self) -> str:
+        """Get the skill slug (filename without extension)."""
+        return self.file_path.stem
+
+
+class SkillRegistry:
+    """Registry for loading and managing agent skills.
+
+    Skills are markdown files in the skills directory that provide domain-specific instructions for the agent.
+    """
+
+    def __init__(self, skills_dir: Path | None = None) -> None:
+        self.skills_dir = skills_dir or _SKILLS_DIR
+        self._skills: dict[str, Skill] = {}
+        self._loaded = False
+
+    def _load_skills(self) -> None:
+        """Load all skills from the skills directory."""
+        if self._loaded:
+            return
+
+        if not self.skills_dir.exists():
+            logger.warning(f"Skills directory not found: {self.skills_dir}")
+            self._loaded = True
+            return
+
+        for skill_file in self.skills_dir.glob("*.md"):
+            try:
+                content = skill_file.read_text(encoding="utf-8")
+                skill = Skill(
+                    name=skill_file.stem.replace("-", " ").replace("_", " ").title(),
+                    content=content,
+                    file_path=skill_file,
+                )
+                self._skills[skill.slug] = skill
+                logger.debug(f"Loaded skill: {skill.name} from {skill_file}")
+            except Exception as e:
+                logger.error(f"Failed to load skill from {skill_file}: {e}")
+
+        self._loaded = True
+        logger.info(f"Loaded {len(self._skills)} skills from {self.skills_dir}")
+
+    def get_skill(self, slug: str) -> Skill | None:
+        """Get a skill by its slug (filename without extension).
+
+        Args:
+            slug: The skill slug (e.g., "rossum-deployment").
+
+        Returns:
+            The Skill object if found, None otherwise.
+        """
+        self._load_skills()
+        return self._skills.get(slug)
+
+    def get_all_skills(self) -> list[Skill]:
+        self._load_skills()
+        return list(self._skills.values())
+
+    def get_skill_names(self) -> list[str]:
+        self._load_skills()
+        return list(self._skills.keys())
+
+    def reload(self) -> None:
+        """Force reload all skills from disk."""
+        self._skills.clear()
+        self._loaded = False
+        self._load_skills()
+
+
+# Module-level default registry instance
+_default_registry: SkillRegistry | None = None
+
+
+def get_skill_registry(skills_dir: Path | None = None) -> SkillRegistry:
+    global _default_registry
+    if _default_registry is None or skills_dir is not None:
+        _default_registry = SkillRegistry(skills_dir)
+    return _default_registry
+
+
+def get_skill(slug: str) -> Skill | None:
+    return get_skill_registry().get_skill(slug)
+
+
+def get_all_skills() -> list[Skill]:
+    return get_skill_registry().get_all_skills()
+
+
+def format_skills_for_prompt(skills: list[Skill] | None = None) -> str:
+    if skills is None:
+        skills = get_all_skills()
+
+    if not skills:
+        return ""
+
+    sections = []
+    for skill in skills:
+        sections.append(f"\n{'=' * 60}\n{skill.content}\n{'=' * 60}")
+
+    return "\n\n## Available Skills\n" + "\n".join(sections)
+
+
+def get_skill_content(slug: str) -> str | None:
+    skill = get_skill(slug)
+    return skill.content if skill else None

rossum_agent/agent/types.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from anthropic.types import ImageBlockParam, TextBlockParam
+
+UserContent = str | list[TextBlockParam | ImageBlockParam]

rossum_agent/agent_logging.py

@@ -0,0 +1,56 @@
+"""Agent logging wrapper for tracking all agent calls and tool usage."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rossum_agent.agent import AgentStep
+
+logger = logging.getLogger(__name__)
+
+
+def log_agent_result(
+    result: AgentStep, prompt: str = "", duration: float = 0, total_input_tokens: int = 0, total_output_tokens: int = 0
+) -> None:
+    """Log agent execution result.
+
+    Args:
+        result: The AgentStep to log.
+        prompt: The original user prompt.
+        duration: Time taken for the step in seconds.
+        total_input_tokens: Total input tokens across all steps.
+        total_output_tokens: Total output tokens across all steps.
+    """
+    extra_fields: dict[str, object] = {
+        "event_type": "agent_call_complete",
+        "prompt": prompt,
+        "duration_seconds": duration,
+        "step_number": result.step_number,
+        "is_final": result.is_final,
+        "input_tokens": total_input_tokens if total_input_tokens else result.input_tokens,
+        "output_tokens": total_output_tokens if total_output_tokens else result.output_tokens,
+    }
+
+    if result.thinking:
+        extra_fields["thinking"] = result.thinking[:500]
+
+    if result.tool_calls:
+        extra_fields["tool_calls"] = json.dumps(
+            [{"name": tc.name, "arguments": tc.arguments} for tc in result.tool_calls], default=str
+        )
+
+    if result.tool_results:
+        extra_fields["tool_results"] = json.dumps(
+            [{"name": tr.name, "is_error": tr.is_error} for tr in result.tool_results], default=str
+        )
+
+    if result.final_answer:
+        extra_fields["final_answer"] = result.final_answer[:500]
+
+    if result.error:
+        extra_fields["error"] = result.error
+
+    logger.info("Agent step completed", extra=extra_fields)

rossum_agent/api/__init__.py

@@ -0,0 +1 @@
+"""FastAPI-based REST API for Rossum Agent."""