mycode-sdk 0.8.9__tar.gz → 0.9.0__tar.gz

{mycode_sdk-0.8.9 → mycode_sdk-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycode-sdk
-Version: 0.8.9
+Version: 0.9.0
 Summary: Lightweight Python SDK for building AI agents.
 Project-URL: Homepage, https://github.com/legibet/mycode
 Project-URL: Repository, https://github.com/legibet/mycode
@@ -20,7 +20,9 @@ Classifier: Topic :: Software Development
 Requires-Python: >=3.12
 Requires-Dist: anthropic>=0.102.0
 Requires-Dist: google-genai>=2.3.0
+Requires-Dist: griffelib>=2.0.2
 Requires-Dist: openai>=2.36.0
+Requires-Dist: pydantic>=2.13.4
 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.9 → mycode_sdk-0.9.0}/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.9 → mycode_sdk-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mycode-sdk"
-version = "0.8.9"
+version = "0.9.0"
 description = "Lightweight Python SDK for building AI agents."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,7 +25,9 @@ keywords = ["agent", "llm", "anthropic", "openai", "gemini", "sdk"]
 dependencies = [
     "anthropic>=0.102.0",
     "google-genai>=2.3.0",
+    "griffelib>=2.0.2",
     "openai>=2.36.0",
+    "pydantic>=2.13.4",
 ]
 
 [project.urls]

{mycode_sdk-0.8.9 → mycode_sdk-0.9.0}/src/mycode/__init__.py

@@ -10,6 +10,7 @@ silently exposing file system and shell access.
 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 +28,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.9 → mycode_sdk-0.9.0}/src/mycode/agent.py

@@ -18,10 +18,10 @@ 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 +79,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 +112,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
 
@@ -431,6 +442,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."""
@@ -462,6 +474,10 @@ 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
@@ -495,15 +511,17 @@ class Agent:
                 provider=self.provider,
                 model=self.model,
                 session_id=self.session_id,
-                messages=apply_compact_replay(self.messages, transcript_path=self.transcript_path),
+                messages=self.messages,
                 system=self.system,
                 tools=self.tools.definitions,
                 max_tokens=self.max_tokens,
+                temperature=self.temperature,
                 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,
+                transcript_path=self.transcript_path,
             )
 
             try:
@@ -682,6 +700,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 +714,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 +735,21 @@ 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,
+            messages=self.messages,
             system=self.system,
             tools=[],
             max_tokens=min(self.max_tokens, 8192),
+            temperature=self.temperature,
             api_key=self.api_key,
             api_base=self.api_base,
             supports_image_input=self.supports_image_input,
             supports_pdf_input=self.supports_pdf_input,
+            transcript_path=self.transcript_path,
+            append_messages=[user_text_message(COMPACT_SUMMARY_PROMPT)],
         )
 
         summary_message: ConversationMessage | None = None

mycode_sdk-0.9.0/src/mycode/attachments.py

@@ -0,0 +1,175 @@
+"""Attachment input for user messages.
+
+Conversion rules in one place so the SDK, CLI, and HTTP server all produce the
+same content blocks for the same input.
+"""
+
+from __future__ import annotations
+
+import html
+from base64 import b64encode
+from collections.abc import Sequence
+from dataclasses import dataclass
+from mimetypes import guess_type
+from pathlib import Path
+from typing import Self
+
+from mycode.messages import ContentBlock, document_block, image_block, text_block
+from mycode.utils import resolve_path
+
+SUPPORTED_IMAGE_MIME_TYPES = frozenset({"image/png", "image/jpeg", "image/gif", "image/webp"})
+SUPPORTED_DOCUMENT_MIME_TYPES = frozenset({"application/pdf"})
+
+
+@dataclass(frozen=True, kw_only=True)
+class Attachment:
+    """File path, raw bytes, or text snippet attached to a user message.
+
+    Construct via ``Attachment.path`` / ``.bytes`` / ``.text``; ``kw_only`` stops a
+    bare ``Attachment("notes.txt")`` from silently becoming text instead of a path.
+    """
+
+    source: Path | bytes | str
+    media_type: str | None = None
+    name: str | None = None
+
+    @classmethod
+    def path(cls, path: str | Path, *, name: str | None = None) -> Self:
+        """``name`` defaults to the file's basename when omitted."""
+
+        return cls(source=Path(path), name=name)
+
+    @classmethod
+    def bytes(cls, data: bytes, *, media_type: str, name: str | None = None) -> Self:
+        """``media_type`` must be a supported image type or ``application/pdf``."""
+
+        if not media_type:
+            raise ValueError("Attachment.bytes requires a non-empty media_type")
+        return cls(source=bytes(data), media_type=media_type, name=name)
+
+    @classmethod
+    def text(cls, data: str, *, name: str) -> Self:
+        """Wrapped as a named ``<file>`` snippet in the user message."""
+
+        if not name:
+            raise ValueError("Attachment.text requires a non-empty name")
+        return cls(source=data, name=name)
+
+
+AttachmentLike = str | Path | Attachment
+
+
+def build_attachment_blocks(
+    attachments: Sequence[AttachmentLike],
+    *,
+    cwd: str,
+) -> list[ContentBlock]:
+    """Return one content block per attachment, in input order.
+
+    ``str`` / ``Path`` items are treated as ``Attachment.path``. Raises
+    ``ValueError`` on a missing path, a directory, a binary file that is
+    neither image nor PDF, undecodable text, or an unsupported ``media_type``.
+    """
+
+    blocks: list[ContentBlock] = []
+    for item in attachments:
+        att = item if isinstance(item, Attachment) else Attachment.path(item)
+        match att.source:
+            case bytes() as data:
+                media_type = att.media_type or ""
+                if media_type in SUPPORTED_IMAGE_MIME_TYPES:
+                    blocks.append(image_block(b64encode(data).decode("ascii"), mime_type=media_type, name=att.name))
+                elif media_type in SUPPORTED_DOCUMENT_MIME_TYPES:
+                    blocks.append(document_block(b64encode(data).decode("ascii"), mime_type=media_type, name=att.name))
+                else:
+                    supported = sorted(SUPPORTED_IMAGE_MIME_TYPES | SUPPORTED_DOCUMENT_MIME_TYPES)
+                    raise ValueError(f"unsupported media_type {media_type!r}; want one of {supported}")
+            case Path() as raw:
+                path = Path(resolve_path(str(raw), cwd=cwd))
+                if not path.exists():
+                    raise ValueError(f"attachment not found: {raw}")
+                if path.is_dir():
+                    raise ValueError(f"attachment is a directory: {raw}")
+                display = att.name or path.name
+                if mime := detect_image_mime_type(path):
+                    blocks.append(
+                        image_block(b64encode(path.read_bytes()).decode("ascii"), mime_type=mime, name=display)
+                    )
+                elif mime := detect_document_mime_type(path):
+                    blocks.append(
+                        document_block(b64encode(path.read_bytes()).decode("ascii"), mime_type=mime, name=display)
+                    )
+                else:
+                    try:
+                        text = path.read_text(encoding="utf-8")
+                    except UnicodeDecodeError as exc:
+                        raise ValueError(f"unsupported attachment {raw}: not image, PDF, or UTF-8 text") from exc
+                    blocks.append(_wrap_file(text, display))
+            case str() as text:
+                blocks.append(_wrap_file(text, att.name or ""))
+    return blocks
+
+
+def unsupported_attachment_block(
+    *,
+    name: str,
+    mime_type: str,
+    kind: str,
+    path: str | None = None,
+) -> ContentBlock:
+    """Text-block stand-in for an image/PDF block a model can't ingest.
+
+    Pass ``path`` (e.g. the original ``@path`` typed by the user) to keep it on
+    ``meta.path`` for UI labels; omit it when replaying history where the
+    on-disk path is no longer authoritative.
+    """
+
+    label = "image input" if kind == "image" else "PDF input"
+    safe_name = html.escape(name, quote=True)
+    safe_mime = html.escape(mime_type, quote=True)
+    body = f"Current model does not support {label}."
+    meta: dict[str, object] = {"attachment": True}
+    if path is not None:
+        meta["path"] = path
+    return text_block(
+        f'<file name="{safe_name}" media_type="{safe_mime}" kind="{kind}">{body}</file>',
+        meta=meta,
+    )
+
+
+def detect_image_mime_type(path: Path) -> str | None:
+    """Sniff PNG/JPEG/GIF/WebP magic bytes; fall back to the filename extension."""
+
+    try:
+        with path.open("rb") as file:
+            header = file.read(16)
+    except OSError:
+        return None
+    if header.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if header.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if header.startswith((b"GIF87a", b"GIF89a")):
+        return "image/gif"
+    if header.startswith(b"RIFF") and header[8:12] == b"WEBP":
+        return "image/webp"
+    guessed, _ = guess_type(path.name)
+    return guessed if guessed in SUPPORTED_IMAGE_MIME_TYPES else None
+
+
+def detect_document_mime_type(path: Path) -> str | None:
+    """Return ``application/pdf`` if the file is a PDF (by magic bytes or extension)."""
+
+    try:
+        with path.open("rb") as file:
+            if file.read(5).startswith(b"%PDF-"):
+                return "application/pdf"
+    except OSError:
+        pass
+    guessed, _ = guess_type(path.name)
+    return "application/pdf" if guessed == "application/pdf" else None
+
+
+def _wrap_file(text: str, name: str) -> ContentBlock:
+    safe = html.escape(name, quote=True)
+    return text_block(f'<file name="{safe}">\n{text}\n</file>', meta={"attachment": True, "path": name})