mycode-sdk 0.8.10__tar.gz → 0.9.1__tar.gz

{mycode_sdk-0.8.10 → mycode_sdk-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycode-sdk
-Version: 0.8.10
+Version: 0.9.1
 Summary: Lightweight Python SDK for building AI agents.
 Project-URL: Homepage, https://github.com/legibet/mycode
 Project-URL: Repository, https://github.com/legibet/mycode
@@ -18,9 +18,11 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
-Requires-Dist: anthropic>=0.102.0
-Requires-Dist: google-genai>=2.3.0
-Requires-Dist: openai>=2.36.0
+Requires-Dist: anthropic>=0.106.0
+Requires-Dist: google-genai>=2.8.0
+Requires-Dist: griffelib>=2.0.0
+Requires-Dist: openai>=2.41.0
+Requires-Dist: pydantic>=2.13.0
 Description-Content-Type: text/markdown
 
 # mycode-sdk
@@ -78,6 +80,28 @@ agent.run("What is 2 + 2?")
 agent.run("Now multiply that by 10.")    # remembers the earlier answer
 ```
 
+## Attachments
+
+Pass `attachments` to `achat()` or `run()` to add files alongside the prompt:
+
+```python
+from mycode import Attachment
+
+agent.run("Describe these.", attachments=["diagram.png", "report.pdf", "notes.txt"])
+
+# Or build them explicitly — raw bytes and inline text never touch the disk:
+agent.run(
+    "Review.",
+    attachments=[
+        Attachment.path("diagram.png"),
+        Attachment.bytes(png_data, media_type="image/png"),
+        Attachment.text("TODO: ship it", name="note.md"),
+    ],
+)
+```
+
+Images support `image/png`, `image/jpeg`, `image/gif`, `image/webp`; documents support `application/pdf`. Sending an image or PDF to a model that lacks that capability yields an `error` event; a bad path or unsupported type raises `ValueError` before the model is called.
+
 ## Saving sessions
 
 Pass `session_dir` to persist the conversation to disk. Each session lives in a subdirectory named by `session_id`:
@@ -105,7 +129,7 @@ Four tools for reading, writing, editing files, and running shell commands. Opt
 
 ## Custom tools
 
-Decorate any function with `@tool`. Parameter type hints become the JSON schema sent to the provider; the docstring becomes the description:
+Decorate a typed function with `@tool`:
 
 ```python
 from mycode import Agent, tool
@@ -113,7 +137,11 @@ from mycode import Agent, tool
 
 @tool
 def greet(name: str) -> str:
-    """Return a friendly greeting."""
+    """Return a friendly greeting.
+
+    Args:
+        name: Person name.
+    """
 
     return f"hello, {name}"
 
@@ -125,7 +153,7 @@ agent = Agent(
 )
 ```
 
-To call a built-in tool from inside your own, type the first parameter as `ToolContext`:
+To call a built-in tool from inside your own tool, type the first parameter as `ToolContext`:
 
 ```python
 from mycode import ToolContext, tool

{mycode_sdk-0.8.10 → mycode_sdk-0.9.1}/README.md

@@ -53,6 +53,28 @@ agent.run("What is 2 + 2?")
 agent.run("Now multiply that by 10.")    # remembers the earlier answer
 ```
 
+## Attachments
+
+Pass `attachments` to `achat()` or `run()` to add files alongside the prompt:
+
+```python
+from mycode import Attachment
+
+agent.run("Describe these.", attachments=["diagram.png", "report.pdf", "notes.txt"])
+
+# Or build them explicitly — raw bytes and inline text never touch the disk:
+agent.run(
+    "Review.",
+    attachments=[
+        Attachment.path("diagram.png"),
+        Attachment.bytes(png_data, media_type="image/png"),
+        Attachment.text("TODO: ship it", name="note.md"),
+    ],
+)
+```
+
+Images support `image/png`, `image/jpeg`, `image/gif`, `image/webp`; documents support `application/pdf`. Sending an image or PDF to a model that lacks that capability yields an `error` event; a bad path or unsupported type raises `ValueError` before the model is called.
+
 ## Saving sessions
 
 Pass `session_dir` to persist the conversation to disk. Each session lives in a subdirectory named by `session_id`:
@@ -80,7 +102,7 @@ Four tools for reading, writing, editing files, and running shell commands. Opt
 
 ## Custom tools
 
-Decorate any function with `@tool`. Parameter type hints become the JSON schema sent to the provider; the docstring becomes the description:
+Decorate a typed function with `@tool`:
 
 ```python
 from mycode import Agent, tool
@@ -88,7 +110,11 @@ from mycode import Agent, tool
 
 @tool
 def greet(name: str) -> str:
-    """Return a friendly greeting."""
+    """Return a friendly greeting.
+
+    Args:
+        name: Person name.
+    """
 
     return f"hello, {name}"
 
@@ -100,7 +126,7 @@ agent = Agent(
 )
 ```
 
-To call a built-in tool from inside your own, type the first parameter as `ToolContext`:
+To call a built-in tool from inside your own tool, type the first parameter as `ToolContext`:
 
 ```python
 from mycode import ToolContext, tool

{mycode_sdk-0.8.10 → mycode_sdk-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mycode-sdk"
-version = "0.8.10"
+version = "0.9.1"
 description = "Lightweight Python SDK for building AI agents."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -23,9 +23,11 @@ classifiers = [
 ]
 keywords = ["agent", "llm", "anthropic", "openai", "gemini", "sdk"]
 dependencies = [
-    "anthropic>=0.102.0",
-    "google-genai>=2.3.0",
-    "openai>=2.36.0",
+    "anthropic>=0.106.0",
+    "google-genai>=2.8.0",
+    "griffelib>=2.0.0",
+    "openai>=2.41.0",
+    "pydantic>=2.13.0",
 ]
 
 [project.urls]

{mycode_sdk-0.8.10 → mycode_sdk-0.9.1}/src/mycode/__init__.py

@@ -1,15 +1,9 @@
-"""mycode — multi-turn tool-calling agent runtime.
-
-Public API for embedding the agent loop in other Python applications. The
-runtime ships four built-in coding tools (``read``, ``write``, ``edit``,
-``bash``) exposed as :data:`read_tool`, :data:`write_tool`, :data:`edit_tool`,
-:data:`bash_tool` — pick the ones you want via ``tools=[...]`` rather than
-silently exposing file system and shell access.
-"""
+"""mycode — multi-turn tool-calling agent runtime."""
 
 from importlib import metadata
 
 from mycode.agent import Agent, Event, PersistCallback, RunResult
+from mycode.attachments import Attachment
 from mycode.hooks import AfterToolHook, BeforeToolHook, HookResult, Hooks, ToolHookContext
 from mycode.messages import (
     ContentBlock,
@@ -27,25 +21,25 @@ from mycode.messages import (
 )
 from mycode.session import SessionStore
 from mycode.tools import (
-    DEFAULT_TOOL_SPECS,
     ToolContext,
     ToolExecutionResult,
     ToolExecutor,
     ToolSpec,
+    bash_tool,
     cancel_all_tools,
+    edit_tool,
+    read_tool,
     tool,
+    write_tool,
 )
 
-# The package metadata in mycode/pyproject.toml is the single version source.
 __version__ = metadata.version("mycode-sdk")
 
-read_tool, write_tool, edit_tool, bash_tool = DEFAULT_TOOL_SPECS
-
 __all__ = [
     "Agent",
+    "Attachment",
     "ContentBlock",
     "ConversationMessage",
-    "DEFAULT_TOOL_SPECS",
     "Event",
     "AfterToolHook",
     "BeforeToolHook",

{mycode_sdk-0.8.10 → mycode_sdk-0.9.1}/src/mycode/agent.py

@@ -13,15 +13,16 @@ import os
 import tempfile
 import time
 from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
+from contextlib import suppress
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, cast
 from uuid import uuid4
 
+from mycode.attachments import AttachmentLike, build_attachment_blocks
 from mycode.compact import (
     COMPACT_SUMMARY_PROMPT,
     DEFAULT_COMPACT_THRESHOLD,
-    apply_compact_replay,
     build_compact_event,
     should_compact,
 )
@@ -79,6 +80,7 @@ class Agent:
         messages: list[ConversationMessage] | None = None,
         max_turns: int | None = None,
         max_tokens: int | None = None,
+        temperature: float = 1.0,
         context_window: int | None = None,
         compact_threshold: float | None = None,
         reasoning_effort: str | None = None,
@@ -111,6 +113,16 @@ class Agent:
         self.api_key = api_key
         self.api_base = api_base
         self.max_turns = max_turns
+        if not 0 <= temperature <= 1:
+            raise ValueError("temperature must be between 0 and 1")
+        if (
+            provider in {"anthropic", "moonshotai", "minimax"}
+            and reasoning_effort
+            and reasoning_effort != "none"
+            and temperature != 1.0
+        ):
+            raise ValueError(f"{provider} does not support custom temperature when thinking is enabled")
+        self.temperature = float(temperature)
         self.compact_threshold = compact_threshold if compact_threshold is not None else DEFAULT_COMPACT_THRESHOLD
         self.reasoning_effort = reasoning_effort
 
@@ -221,18 +233,12 @@ class Agent:
         yield Event("tool_start", {"tool_call": {"id": tool_id, "name": name, "input": args}})
 
         if self._cancel_event.is_set():
-            yield self._tool_done_event(
-                tool_id,
-                ToolExecutionResult(output="error: cancelled", is_error=True),
-            )
+            yield self._error_done(tool_id, "error: cancelled")
             return
 
         spec = self.tools.get(name)
         if spec is None:
-            yield self._tool_done_event(
-                tool_id,
-                ToolExecutionResult(output=f"error: unknown tool: {name}", is_error=True),
-            )
+            yield self._error_done(tool_id, f"error: unknown tool: {name}")
             return
 
         hook_ctx = ToolHookContext(
@@ -248,10 +254,7 @@ class Agent:
         try:
             result = await self.hooks.run_before_tool(hook_ctx)
         except Exception as exc:
-            yield self._tool_done_event(
-                tool_id,
-                ToolExecutionResult(output=f"error: tool hook failed: {exc}", is_error=True),
-            )
+            yield self._error_done(tool_id, f"error: tool hook failed: {exc}")
             return
 
         if result is not None:
@@ -259,10 +262,7 @@ class Agent:
             return
 
         if self._cancel_event.is_set():
-            yield self._tool_done_event(
-                tool_id,
-                ToolExecutionResult(output="error: cancelled", is_error=True),
-            )
+            yield self._error_done(tool_id, "error: cancelled")
             return
 
         if spec.streams_output:
@@ -325,13 +325,10 @@ class Agent:
                 yield Event("tool_output", {"tool_use_id": tool_id, "output": output})
 
         if was_cancelled:
-            try:
+            with suppress(Exception):
                 await task
-            except Exception:
-                pass
             output = "\n".join([*output_parts, "error: cancelled"]) if output_parts else "error: cancelled"
-            result = ToolExecutionResult(output=output, is_error=True)
-            yield self._tool_done_event(tool_id, result)
+            yield self._error_done(tool_id, output)
             return
         else:
             try:
@@ -387,6 +384,11 @@ class Agent:
             data["content"] = result.content
         return Event("tool_done", data)
 
+    def _error_done(self, tool_id: str, message: str) -> Event:
+        """Build a tool_done event carrying an error result."""
+
+        return self._tool_done_event(tool_id, ToolExecutionResult(output=message, is_error=True))
+
     # ------------------------------------------------------------------
     # Provider streaming
     # ------------------------------------------------------------------
@@ -418,10 +420,52 @@ class Agent:
         finally:
             close = cast(Callable[[], Awaitable[None]] | None, getattr(provider_stream, "aclose", None))
             if close is not None:
-                try:
+                with suppress(Exception):
                     await close()
-                except Exception:
-                    pass
+
+    def _build_request(
+        self,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        max_tokens: int | None = None,
+        reasoning_effort: str | None = None,
+        append_messages: Sequence[ConversationMessage] = (),
+    ) -> ProviderRequest:
+        """Build a ProviderRequest from the agent's current state."""
+
+        return ProviderRequest(
+            provider=self.provider,
+            model=self.model,
+            session_id=self.session_id,
+            messages=self.messages,
+            system=self.system,
+            tools=self.tools.definitions if tools is None else tools,
+            max_tokens=self.max_tokens if max_tokens is None else max_tokens,
+            temperature=self.temperature,
+            api_key=self.api_key,
+            api_base=self.api_base,
+            reasoning_effort=reasoning_effort,
+            supports_image_input=self.supports_image_input,
+            supports_pdf_input=self.supports_pdf_input,
+            transcript_path=self.transcript_path,
+            append_messages=list(append_messages),
+        )
+
+    @staticmethod
+    def _elapsed_ms(start: float) -> int:
+        return max(0, int((time.monotonic() - start) * 1000))
+
+    @staticmethod
+    def _stamp_thinking_duration(content: list[Any], duration_ms: int) -> None:
+        """Merge duration_ms onto the last thinking block in content, if any."""
+
+        for block in reversed(content):
+            if not isinstance(block, dict) or block.get("type") != "thinking":
+                continue
+            raw_meta = block.get("meta")
+            meta = raw_meta if isinstance(raw_meta, dict) else {}
+            block["meta"] = {**meta, "duration_ms": duration_ms}
+            return
 
     # ------------------------------------------------------------------
     # Public entry points
@@ -431,6 +475,7 @@ class Agent:
         self,
         user_input: str | ConversationMessage,
         *,
+        attachments: Sequence[AttachmentLike] = (),
         on_persist: PersistCallback | None = None,
     ) -> AsyncIterator[Event]:
         """Run the full agent loop for one user message."""
@@ -448,8 +493,9 @@ class Agent:
 
         self._cancel_event.clear()
 
+        user_message: ConversationMessage
         if isinstance(user_input, str):
-            user_message: ConversationMessage = user_text_message(user_input)
+            user_message = user_text_message(user_input)
         else:
             if (user_input.get("role") or "user") != "user":
                 yield Event("error", {"message": "user input must be a user message"})
@@ -462,17 +508,20 @@ class Agent:
             if isinstance(raw_meta, dict):
                 user_message["meta"] = {str(k): v for k, v in raw_meta.items()}
 
+        if attachments:
+            blocks = await asyncio.to_thread(build_attachment_blocks, attachments, cwd=self.cwd)
+            user_message["content"] = list(user_message.get("content") or []) + blocks
+
         content_blocks = user_message.get("content") or []
-        if not self.supports_image_input and any(
-            isinstance(block, dict) and block.get("type") == "image" for block in content_blocks
+        for block_type, supported, label in (
+            ("image", self.supports_image_input, "image input"),
+            ("document", self.supports_pdf_input, "PDF input"),
         ):
-            yield Event("error", {"message": "current model does not support image input"})
-            return
-        if not self.supports_pdf_input and any(
-            isinstance(block, dict) and block.get("type") == "document" for block in content_blocks
-        ):
-            yield Event("error", {"message": "current model does not support PDF input"})
-            return
+            if not supported and any(
+                isinstance(block, dict) and block.get("type") == block_type for block in content_blocks
+            ):
+                yield Event("error", {"message": f"current model does not support {label}"})
+                return
 
         self.messages.append(user_message)
         await persist(user_message)
@@ -491,20 +540,7 @@ class Agent:
             thinking_started_at: float | None = None
             thinking_duration_ms: int | None = None
             provider_cancelled = False
-            request = ProviderRequest(
-                provider=self.provider,
-                model=self.model,
-                session_id=self.session_id,
-                messages=apply_compact_replay(self.messages, transcript_path=self.transcript_path),
-                system=self.system,
-                tools=self.tools.definitions,
-                max_tokens=self.max_tokens,
-                api_key=self.api_key,
-                api_base=self.api_base,
-                reasoning_effort=self.reasoning_effort,
-                supports_image_input=self.supports_image_input,
-                supports_pdf_input=self.supports_pdf_input,
-            )
+            request = self._build_request(reasoning_effort=self.reasoning_effort)
 
             try:
                 async for provider_event in self._stream_provider_turn(adapter, request):
@@ -528,7 +564,7 @@ class Agent:
                         delta_text = str(provider_event.data.get("text") or "")
                         if delta_text:
                             if thinking_started_at is not None and thinking_duration_ms is None:
-                                thinking_duration_ms = max(0, int((time.monotonic() - thinking_started_at) * 1000))
+                                thinking_duration_ms = self._elapsed_ms(thinking_started_at)
                                 yield Event("reasoning_done", {"duration_ms": thinking_duration_ms})
                             if partial_content and partial_content[-1].get("type") == "text":
                                 partial_content[-1]["text"] = f"{partial_content[-1].get('text') or ''}{delta_text}"
@@ -544,7 +580,7 @@ class Agent:
                         continue
 
                     if thinking_started_at is not None and thinking_duration_ms is None:
-                        thinking_duration_ms = max(0, int((time.monotonic() - thinking_started_at) * 1000))
+                        thinking_duration_ms = self._elapsed_ms(thinking_started_at)
                         yield Event("reasoning_done", {"duration_ms": thinking_duration_ms})
 
                     message = provider_event.data.get("message")
@@ -561,15 +597,9 @@ class Agent:
             if provider_cancelled:
                 if partial_content:
                     if thinking_started_at is not None and thinking_duration_ms is None:
-                        thinking_duration_ms = max(0, int((time.monotonic() - thinking_started_at) * 1000))
+                        thinking_duration_ms = self._elapsed_ms(thinking_started_at)
                     if thinking_duration_ms is not None:
-                        for block in reversed(partial_content):
-                            if block.get("type") != "thinking":
-                                continue
-                            raw_meta = block.get("meta")
-                            meta = cast(dict[str, Any], raw_meta) if isinstance(raw_meta, dict) else {}
-                            block["meta"] = {**meta, "duration_ms": thinking_duration_ms}
-                            break
+                        self._stamp_thinking_duration(partial_content, thinking_duration_ms)
                     cancelled_message = build_message(
                         "assistant",
                         [dict(block) for block in partial_content],
@@ -589,13 +619,7 @@ class Agent:
                 return
 
             if thinking_duration_ms is not None:
-                for block in reversed(assistant_message.get("content") or []):
-                    if not isinstance(block, dict) or block.get("type") != "thinking":
-                        continue
-                    raw_meta = block.get("meta")
-                    meta = cast(dict[str, Any], raw_meta) if isinstance(raw_meta, dict) else {}
-                    block["meta"] = {**meta, "duration_ms": thinking_duration_ms}
-                    break
+                self._stamp_thinking_duration(assistant_message.get("content") or [], thinking_duration_ms)
 
             # Stamp context_window onto the persisted assistant message so
             # rewinds and refreshed clients can render token-usage % without
@@ -631,16 +655,13 @@ class Agent:
                             continue
 
                         d = event.data
-                        output = str(d.get("output") or "")
-                        metadata = d.get("metadata") if isinstance(d.get("metadata"), dict) else None
-                        content = d.get("content")
                         tool_results.append(
                             tool_result_block(
-                                tool_use_id=str(d.get("tool_use_id") or ""),
-                                output=output,
-                                metadata=metadata,
-                                is_error=bool(d.get("is_error")),
-                                content=content if isinstance(content, list) else None,
+                                tool_use_id=d["tool_use_id"],
+                                output=d["output"],
+                                metadata=d.get("metadata"),
+                                is_error=d["is_error"],
+                                content=d.get("content"),
                             )
                         )
 
@@ -682,6 +703,7 @@ class Agent:
         self,
         user_input: str | ConversationMessage,
         *,
+        attachments: Sequence[AttachmentLike] = (),
         on_persist: PersistCallback | None = None,
     ) -> RunResult:
         """Run one user turn synchronously and collect the streamed result."""
@@ -695,7 +717,7 @@ class Agent:
 
         async def collect() -> RunResult:
             result = RunResult()
-            async for event in self.achat(user_input, on_persist=on_persist):
+            async for event in self.achat(user_input, attachments=attachments, on_persist=on_persist):
                 result.events.append(event)
                 if event.type == "text":
                     result.text += str(event.data.get("delta") or "")
@@ -716,21 +738,10 @@ class Agent:
     ) -> None:
         """Ask the provider for a summary, persist the compact event, append it."""
 
-        compact_messages = apply_compact_replay(self.messages, transcript_path=self.transcript_path) + [
-            user_text_message(COMPACT_SUMMARY_PROMPT)
-        ]
-        request = ProviderRequest(
-            provider=self.provider,
-            model=self.model,
-            session_id=self.session_id,
-            messages=compact_messages,
-            system=self.system,
+        request = self._build_request(
             tools=[],
             max_tokens=min(self.max_tokens, 8192),
-            api_key=self.api_key,
-            api_base=self.api_base,
-            supports_image_input=self.supports_image_input,
-            supports_pdf_input=self.supports_pdf_input,
+            append_messages=[user_text_message(COMPACT_SUMMARY_PROMPT)],
         )
 
         summary_message: ConversationMessage | None = None