evidor 1.1.0__py3-none-any.whl

evidor/__init__.py

@@ -0,0 +1,26 @@
+"""Minimal, provider-agnostic LLM harness."""
+
+from .agent import Agent
+from .context import DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_MESSAGES
+from .models import GenerationRequest, GenerationResponse, Message, ToolCall
+from .providers import AnthropicProvider, GeminiProvider, ModelProvider, OpenAIProvider
+from .tools import Tool, calculator, filesystem_tools, get_current_time, tool
+
+__all__ = [
+    "Agent",
+    "AnthropicProvider",
+    "calculator",
+    "DEFAULT_CONTEXT_WINDOW",
+    "DEFAULT_MAX_MESSAGES",
+    "GeminiProvider",
+    "GenerationRequest",
+    "GenerationResponse",
+    "get_current_time",
+    "filesystem_tools",
+    "Message",
+    "ModelProvider",
+    "OpenAIProvider",
+    "Tool",
+    "ToolCall",
+    "tool",
+]

evidor/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Conversational-agent APIs and internal runtime components."""
+
+from .agent import Agent
+
+__all__ = ["Agent"]

evidor/agent/agent.py

@@ -0,0 +1,123 @@
+"""The public conversational agent facade."""
+
+import asyncio
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from ..context import DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_MESSAGES, ConversationContext
+from ..models import GenerationRequest, GenerationResponse, Message, ToolCall
+from ..providers.base import ModelProvider
+from ..tools import Tool
+from .history import ConversationHistory
+from .summarization import ConversationSummarizer, resolve_summary_provider
+from .tool_executor import ToolExecutor
+
+
+class Agent:
+    """A conversational session coordinating a provider, history, context, and tools."""
+
+    def __init__(
+        self,
+        provider: ModelProvider,
+        *,
+        tools: Sequence[Tool | Callable[..., Any]] | None = None,
+        max_tool_iterations: int = 10,
+        tool_timeout: float | None = None,
+        system_prompt: str | None = None,
+        context_window: int = DEFAULT_CONTEXT_WINDOW,
+        max_messages: int = DEFAULT_MAX_MESSAGES,
+        summarization_model: str | ModelProvider | None = None,
+    ) -> None:
+        self._provider = provider
+        self._summary_provider = resolve_summary_provider(provider, summarization_model)
+        self._summarizer = ConversationSummarizer(self._summary_provider)
+        self._context = ConversationContext(context_window, max_messages)
+        self._history = ConversationHistory(system_prompt)
+        # Retained for compatibility with callers that inspect or seed test history.
+        self._messages = self._history.messages
+        self._max_tool_iterations = max_tool_iterations
+        self._tool_timeout = tool_timeout
+        self._tool_executor = ToolExecutor(tools, tool_timeout)
+        self._tools = self._tool_executor.tools
+
+    @property
+    def messages(self) -> tuple[Message, ...]:
+        """The retained conversation, including any generated summary message."""
+        return tuple(self._messages)
+
+    @property
+    def tools(self) -> tuple[Tool, ...]:
+        """The tools configured on this agent."""
+        return self._tools
+
+    @property
+    def tool_timeout(self) -> float | None:
+        """Default per-tool execution timeout in seconds, if configured."""
+        return self._tool_timeout
+
+    @property
+    def summary_provider(self) -> ModelProvider:
+        """The provider used for compacting and summarizing conversations."""
+        return self._summary_provider
+
+    def send(self, message: str) -> GenerationResponse:
+        """Advance one user turn and execute any requested tool calls."""
+        self._history.add_user(message)
+        for _ in range(self._max_tool_iterations):
+            self._compact()
+            response = self._provider.generate(GenerationRequest(messages=self._messages, tools=self._tools))
+            self._history.add_assistant(response)
+            if not response.tool_calls:
+                return response
+            self._execute_tool_calls(response.tool_calls)
+        self._compact()
+        final_response = self._provider.generate(GenerationRequest(messages=self._messages, tools=()))
+        return self._finalize_loop_expiry(final_response, response)
+
+    async def send_async(self, message: str) -> GenerationResponse:
+        """Asynchronously advance one user turn and execute requested tool calls."""
+        self._history.add_user(message)
+        for _ in range(self._max_tool_iterations):
+            await self._compact_async()
+            response = await asyncio.to_thread(
+                self._provider.generate, GenerationRequest(messages=self._messages, tools=self._tools)
+            )
+            self._history.add_assistant(response)
+            if not response.tool_calls:
+                return response
+            await self._execute_tool_calls_async(response.tool_calls)
+        await self._compact_async()
+        final_response = await asyncio.to_thread(
+            self._provider.generate, GenerationRequest(messages=self._messages, tools=())
+        )
+        return self._finalize_loop_expiry(final_response, response)
+
+    def clear_history(self) -> None:
+        """Clear the conversation while retaining the optional system prompt."""
+        self._history.clear()
+
+    def _compact(self) -> None:
+        self._history.replace(self._context.compact(self._messages, self._summarizer.summarize))
+
+    async def _compact_async(self) -> None:
+        compacted = await asyncio.to_thread(self._context.compact, self._messages, self._summarizer.summarize)
+        self._history.replace(compacted)
+
+    def _execute_tool_calls(self, calls: Sequence[ToolCall]) -> None:
+        for call in calls:
+            self._history.add_tool_result(call, self._tool_executor.execute(call))
+
+    async def _execute_tool_calls_async(self, calls: Sequence[ToolCall]) -> None:
+        for call in calls:
+            result = await self._tool_executor.execute_async(call)
+            self._history.add_tool_result(call, result)
+
+    def _finalize_loop_expiry(
+        self, final_response: GenerationResponse, last_response: GenerationResponse
+    ) -> GenerationResponse:
+        final_text = (final_response.text or "").strip() or (last_response.text or "").strip()
+        if not final_text:
+            final_text = f"Reached maximum tool iterations ({self._max_tool_iterations}) without a final response."
+        self._messages.append(Message(role="assistant", content=final_text))
+        return GenerationResponse(text=final_text, model=final_response.model or last_response.model)
+

evidor/agent/history.py

@@ -0,0 +1,33 @@
+"""Conversation message storage and recording helpers."""
+
+from collections.abc import Sequence
+
+from ..models import GenerationResponse, Message, ToolCall
+
+
+class ConversationHistory:
+    """Owns the mutable transcript for a single agent session."""
+
+    def __init__(self, system_prompt: str | None = None) -> None:
+        self.messages: list[Message] = []
+        if system_prompt:
+            self.messages.append(Message(role="system", content=system_prompt))
+
+    def add_user(self, content: str) -> None:
+        self.messages.append(Message(role="user", content=content))
+
+    def add_assistant(self, response: GenerationResponse) -> None:
+        self.messages.append(Message(role="assistant", content=response.text, tool_calls=response.tool_calls))
+
+    def add_tool_result(self, call: ToolCall, result: str) -> None:
+        self.messages.append(Message(role="tool", content=result, tool_call_id=call.id, name=call.name))
+
+    def replace(self, messages: Sequence[Message]) -> None:
+        """Replace history in place so existing list references remain valid."""
+        self.messages[:] = messages
+
+    def clear(self) -> None:
+        """Remove conversation turns while retaining the original system prompt."""
+        self.messages[:] = [
+            message for message in self.messages if message.role == "system" and not message.is_summary
+        ]

evidor/agent/summarization.py

@@ -0,0 +1,69 @@
+"""Conversation summarization and summary-provider configuration."""
+
+from collections.abc import Sequence
+
+from ..models import GenerationRequest, Message
+from ..providers.base import ModelProvider
+
+
+SUMMARY_INSTRUCTION = (
+    "Summarize the conversation below for a future assistant turn. Preserve user goals, "
+    "decisions, constraints, factual details, and unresolved questions. Be concise."
+)
+
+
+class ConversationSummarizer:
+    """Formats a transcript and asks a dedicated provider to summarize it."""
+
+    def __init__(self, provider: ModelProvider) -> None:
+        self.provider = provider
+
+    def summarize(self, messages: Sequence[Message]) -> str:
+        transcript_lines: list[str] = []
+        for message in messages:
+            if message.role == "tool":
+                transcript_lines.append(f"TOOL ({message.name or 'unknown'}): {message.content}")
+            elif message.tool_calls:
+                call_names = ", ".join(call.name for call in message.tool_calls)
+                prefix = f"ASSISTANT (called tools: {call_names}):"
+                transcript_lines.append(f"{prefix} {message.content}" if message.content else prefix)
+            else:
+                transcript_lines.append(f"{message.role.upper()}: {message.content}")
+        request = GenerationRequest(
+            messages=(
+                Message(role="system", content=SUMMARY_INSTRUCTION),
+                Message(role="user", content="\n".join(transcript_lines)),
+            )
+        )
+        return self.provider.generate(request).text
+
+
+def resolve_summary_provider(
+    provider: ModelProvider, summarization_model: str | ModelProvider | None
+) -> ModelProvider:
+    """Select a summary provider from a provider instance or model-name override."""
+    if summarization_model is None:
+        return provider
+    if isinstance(summarization_model, ModelProvider):
+        return summarization_model
+    if isinstance(summarization_model, str):
+        if not summarization_model.strip():
+            raise ValueError("summarization_model must not be empty")
+        with_model = getattr(provider, "with_model", None)
+        if callable(with_model):
+            return with_model(summarization_model)
+        provider_type = type(provider)
+        api_key = getattr(provider, "_api_key", None)
+        try:
+            return provider_type(model=summarization_model, api_key=api_key)  # type: ignore[call-arg]
+        except TypeError:
+            try:
+                return provider_type(model=summarization_model)  # type: ignore[call-arg]
+            except TypeError as err:
+                raise ValueError(
+                    f"Cannot configure summarization_model string '{summarization_model}' for provider {provider_type.__name__}. "
+                    "Pass a ModelProvider instance or implement with_model(model)."
+                ) from err
+    raise TypeError(
+        f"summarization_model must be a model name string or ModelProvider, got {type(summarization_model).__name__}"
+    )

evidor/agent/tool_executor.py

@@ -0,0 +1,48 @@
+"""Tool registration and provider-requested tool execution."""
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from ..models import ToolCall
+from ..tools import Tool, tool
+from .utils import format_tool_error, serialize_tool_result
+
+
+class ToolExecutor:
+    """Normalizes configured tools and executes calls requested by a provider."""
+
+    def __init__(self, tools: Sequence[Tool | Callable[..., Any]] | None, default_timeout: float | None) -> None:
+        configured_tools: list[Tool] = []
+        for candidate in tools or ():
+            configured = candidate if isinstance(candidate, Tool) else tool(candidate)
+            if default_timeout is not None and configured.timeout is None:
+                configured = configured.with_timeout(default_timeout)
+            configured_tools.append(configured)
+        self.tools = tuple(configured_tools)
+        self._by_name = {configured.name: configured for configured in self.tools}
+
+    def execute(self, call: ToolCall) -> str:
+        target = self._resolve(call)
+        if isinstance(target, str):
+            return target
+        try:
+            return serialize_tool_result(target.execute(**call.arguments))
+        except Exception as err:
+            return format_tool_error(call.name, err)
+
+    async def execute_async(self, call: ToolCall) -> str:
+        target = self._resolve(call)
+        if isinstance(target, str):
+            return target
+        try:
+            return serialize_tool_result(await target.execute_async(**call.arguments))
+        except Exception as err:
+            return format_tool_error(call.name, err)
+
+    def _resolve(self, call: ToolCall) -> Tool | str:
+        if "__decode_error__" in call.arguments:
+            decode_error = call.arguments["__decode_error__"]
+            raw_input = call.arguments.get("__raw_args__", "")
+            return f"Error: Malformed JSON arguments for tool '{call.name}': {decode_error}. Received input: {raw_input}"
+        target = self._by_name.get(call.name)
+        return target if target is not None else f"Error: Tool '{call.name}' not found."

evidor/agent/utils.py

@@ -0,0 +1,18 @@
+"""Utilities used exclusively by agent-runtime components."""
+
+import json
+from typing import Any
+
+
+def serialize_tool_result(result: Any) -> str:
+    """Serialize a tool execution result into a string suitable for LLM consumption."""
+    if isinstance(result, str):
+        return result
+    if isinstance(result, (dict, list, int, float, bool)):
+        return json.dumps(result)
+    return str(result)
+
+
+def format_tool_error(name: str, err: Any) -> str:
+    """Format a standardized error string when tool execution fails."""
+    return f"Error executing tool '{name}': {err}"

evidor/context.py

@@ -0,0 +1,66 @@
+"""Conversation-window management and summarization."""
+
+from collections.abc import Callable, Sequence
+
+from .models import Message
+
+DEFAULT_CONTEXT_WINDOW = 16_000
+DEFAULT_MAX_MESSAGES = 50
+_CHARS_PER_TOKEN = 4
+
+
+class ConversationContext:
+    """Keeps recent messages and replaces older messages with a bounded summary."""
+
+    def __init__(self, context_window: int, max_messages: int) -> None:
+        if context_window < 128:
+            raise ValueError("context_window must be at least 128 tokens")
+        if max_messages < 3:
+            raise ValueError("max_messages must be at least 3")
+        self._context_window = context_window
+        self._max_messages = max_messages
+
+    def compact(
+        self,
+        messages: Sequence[Message],
+        summarize: Callable[[Sequence[Message]], str],
+    ) -> list[Message]:
+        """Return messages that fit the configured input budget."""
+        if not self._requires_compaction(messages):
+            return list(messages)
+
+        permanent = [message for message in messages if message.role == "system" and not message.is_summary]
+        existing_summaries = [message for message in messages if message.is_summary]
+        conversation = [message for message in messages if message.role != "system"]
+        recent: list[Message] = list(conversation)
+        summarized: list[Message] = list(existing_summaries)
+
+        recent_limit = max(1, self._max_messages - len(permanent) - 1)
+        while len(recent) > recent_limit or self._estimated_tokens(permanent + recent) > self._input_budget:
+            if len(recent) == 1:
+                break
+            summarized.append(recent.pop(0))
+
+        if not summarized:
+            return permanent + recent
+
+        summary = summarize(summarized).strip()
+        if not summary:
+            summary = "Earlier conversation was omitted because no summary was returned."
+        summary = summary[: self._summary_token_limit * _CHARS_PER_TOKEN]
+        return permanent + [Message(role="system", content=f"Conversation summary:\n{summary}", is_summary=True)] + recent
+
+    @property
+    def _input_budget(self) -> int:
+        return self._context_window - min(1_024, self._context_window // 4)
+
+    @property
+    def _summary_token_limit(self) -> int:
+        return min(1_024, max(32, self._context_window // 4))
+
+    def _requires_compaction(self, messages: Sequence[Message]) -> bool:
+        return len(messages) > self._max_messages or self._estimated_tokens(messages) > self._input_budget
+
+    @staticmethod
+    def _estimated_tokens(messages: Sequence[Message]) -> int:
+        return sum((len(message.content) + _CHARS_PER_TOKEN - 1) // _CHARS_PER_TOKEN + 4 for message in messages)

evidor/models.py

@@ -0,0 +1,87 @@
+"""Provider-neutral data structures."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .tools import Tool
+
+
+MessageRole = Literal["system", "user", "assistant", "tool"]
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCall:
+    """A tool invocation requested by a model."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+    def __post_init__(self) -> None:
+        if not self.id:
+            raise ValueError("tool call id must not be empty")
+        if not self.name:
+            raise ValueError("tool call name must not be empty")
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    """A single text message or tool call/response in a conversation."""
+
+    role: MessageRole
+    content: str = ""
+    tool_calls: tuple[ToolCall, ...] = ()
+    tool_call_id: str | None = None
+    name: str | None = None
+    is_summary: bool = False
+
+    def __post_init__(self) -> None:
+        if isinstance(self.tool_calls, (list, tuple)):
+            object.__setattr__(self, "tool_calls", tuple(self.tool_calls))
+        if (not self.content or not self.content.strip()) and not self.tool_calls and self.role != "tool":
+            raise ValueError("message content must not be empty")
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class GenerationRequest:
+    """The complete provider-neutral input for one model generation."""
+
+    messages: tuple[Message, ...]
+    tools: tuple[Tool, ...]
+
+    def __init__(
+        self,
+        prompt: str | None = None,
+        *,
+        messages: Sequence[Message] | None = None,
+        tools: Sequence[Tool] | None = None,
+    ) -> None:
+        if prompt is not None and messages is not None:
+            raise ValueError("provide either prompt or messages, not both")
+        if messages is None:
+            if prompt is None or not prompt.strip():
+                raise ValueError("prompt must not be empty")
+            messages = (Message(role="user", content=prompt),)
+        if not messages:
+            raise ValueError("messages must not be empty")
+        object.__setattr__(self, "messages", tuple(messages))
+        object.__setattr__(self, "tools", tuple(tools or ()))
+
+    @property
+    def prompt(self) -> str:
+        """Compatibility alias for the newest message content."""
+        return self.messages[-1].content
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationResponse:
+    """The normalized output returned by a model provider."""
+
+    text: str
+    model: str
+    tool_calls: tuple[ToolCall, ...] = ()
+
+    def __post_init__(self) -> None:
+        if isinstance(self.tool_calls, (list, tuple)):
+            object.__setattr__(self, "tool_calls", tuple(self.tool_calls))

evidor/providers/__init__.py

@@ -0,0 +1,8 @@
+"""Concrete provider adapters and their shared abstraction."""
+
+from .anthropic import AnthropicProvider
+from .base import ModelProvider
+from .gemini import GeminiProvider
+from .openai import OpenAIProvider
+
+__all__ = ["AnthropicProvider", "GeminiProvider", "ModelProvider", "OpenAIProvider"]

evidor/providers/anthropic.py

@@ -0,0 +1,99 @@
+"""Anthropic adapter."""
+
+from typing import Any
+
+from evidor.models import GenerationRequest, GenerationResponse, ToolCall
+
+
+class AnthropicProvider:
+    def __init__(self, model: str, api_key: str | None = None, max_tokens: int = 1024) -> None:
+        self._model = model
+        self._api_key = api_key
+        self._max_tokens = max_tokens
+
+    @property
+    def model(self) -> str:
+        return self._model
+
+    def with_model(self, model: str) -> "AnthropicProvider":
+        return AnthropicProvider(model=model, api_key=self._api_key, max_tokens=self._max_tokens)
+
+    def generate(self, request: GenerationRequest) -> GenerationResponse:
+        try:
+            from anthropic import Anthropic
+        except ImportError as error:
+            raise ImportError("Install Anthropic support with: pip install 'evidor[anthropic]'") from error
+
+        client = Anthropic(api_key=self._api_key)
+        system_prompt = "\n\n".join(message.content for message in request.messages if message.role == "system")
+
+        formatted_messages: list[dict[str, Any]] = []
+        for message in request.messages:
+            if message.role == "system":
+                continue
+            if message.role == "tool":
+                formatted_messages.append({
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": message.tool_call_id,
+                            "content": message.content,
+                        }
+                    ],
+                })
+            elif message.role == "assistant" and message.tool_calls:
+                content_blocks: list[dict[str, Any]] = []
+                if message.content:
+                    content_blocks.append({"type": "text", "text": message.content})
+                for tc in message.tool_calls:
+                    content_blocks.append({
+                        "type": "tool_use",
+                        "id": tc.id,
+                        "name": tc.name,
+                        "input": tc.arguments,
+                    })
+                formatted_messages.append({"role": "assistant", "content": content_blocks})
+            else:
+                formatted_messages.append({"role": message.role, "content": message.content})
+
+        kwargs: dict[str, Any] = {
+            "model": self._model,
+            "max_tokens": self._max_tokens,
+            "system": system_prompt or None,
+            "messages": formatted_messages,
+        }
+
+        if request.tools:
+            kwargs["tools"] = [
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "input_schema": t.parameters,
+                }
+                for t in request.tools
+            ]
+
+        response_msg = client.messages.create(**kwargs)
+
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+
+        for block in getattr(response_msg, "content", []):
+            block_type = getattr(block, "type", None)
+            if block_type == "text":
+                text_parts.append(getattr(block, "text", ""))
+            elif block_type == "tool_use":
+                tool_calls.append(
+                    ToolCall(
+                        id=getattr(block, "id", f"call_{len(tool_calls)+1}"),
+                        name=getattr(block, "name", ""),
+                        arguments=getattr(block, "input", {}),
+                    )
+                )
+
+        return GenerationResponse(
+            text="".join(text_parts),
+            model=self._model,
+            tool_calls=tuple(tool_calls),
+        )

evidor/providers/base.py

@@ -0,0 +1,18 @@
+"""The port implemented by every model-provider adapter."""
+
+from typing import Protocol, runtime_checkable
+
+from evidor.models import GenerationRequest, GenerationResponse
+
+
+@runtime_checkable
+class ModelProvider(Protocol):
+    """Produces one normalized response from one normalized request."""
+
+    def generate(self, request: GenerationRequest) -> GenerationResponse:
+        """Generate a response for the request."""
+        ...
+
+    def with_model(self, model: str) -> "ModelProvider":
+        """Return a copy of this provider configured with a different model."""
+        ...