mycode-sdk 0.11.2__tar.gz → 0.13.0__tar.gz

{mycode_sdk-0.11.2 → mycode_sdk-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mycode-sdk
-Version: 0.11.2
+Version: 0.13.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
@@ -21,13 +21,14 @@ Requires-Python: >=3.12
 Requires-Dist: anthropic>=0.116.0
 Requires-Dist: google-genai>=2.11.0
 Requires-Dist: griffelib>=2.1.0
+Requires-Dist: httpx>=0.28.0
 Requires-Dist: openai>=2.45.0
 Requires-Dist: pydantic>=2.13.4
 Description-Content-Type: text/markdown
 
 # mycode-sdk
 
-Lightweight Python SDK for building AI agents.
+Lightweight Python SDK for building AI agents. Multi-turn conversations, tool calling, session persistence, and streaming events. Provider adapters for Anthropic, OpenAI, Google, and more.
 
 ## Install
 
@@ -41,15 +42,27 @@ pip install mycode-sdk
 
 ```python
 import asyncio
+from pathlib import Path
+
+from mycode import Agent, tool
+
+
+@tool
+def read_file(path: str) -> str:
+    """Read a UTF-8 text file.
+
+    Args:
+        path: File path, relative to the working directory.
+    """
 
-from mycode import Agent, bash_tool, read_tool
+    return Path(path).read_text(encoding="utf-8")
 
 
 async def main() -> None:
     agent = Agent(
         model="claude-sonnet-4-6",
         api_key="YOUR_API_KEY",
-        tools=[read_tool, bash_tool],
+        tools=[read_file],
     )
 
     async for event in agent.achat("Read pyproject.toml and tell me the project name."):
@@ -62,16 +75,36 @@ asyncio.run(main())
 
 `Agent(...)` infers the provider from the model id. No tools are registered unless you pass `tools=[...]`.
 
-For a simple synchronous call, use `run()`:
+For a synchronous call, use `run()`:
 
 ```python
 result = agent.run("Read pyproject.toml and tell me the project name.")
 print(result.text)
 ```
 
+## Providers
+
+The SDK infers the provider from the model string (`claude-*` to Anthropic, `gpt-*` to OpenAI, etc.). API keys are auto-discovered from environment variables:
+
+| Provider | id | Env var |
+| --- | --- | --- |
+| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
+| OpenAI | `openai` | `OPENAI_API_KEY` |
+| Google Gemini | `google` | `GEMINI_API_KEY` |
+| Moonshot | `moonshotai` | `MOONSHOT_API_KEY` |
+| MiniMax | `minimax` | `MINIMAX_API_KEY` |
+| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
+| Z.AI | `zai` | `ZAI_API_KEY` |
+| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
+| Alibaba Cloud | `alibaba` | `DASHSCOPE_API_KEY` |
+| xAI | `xai` | `XAI_API_KEY` |
+| OpenAI-compatible | `openai_chat` | - |
+
+Pass `api_key=` to override the env var, `api_base=` for a custom endpoint. Model metadata is bundled from [models.dev](https://models.dev); pass `context_window`, `supports_reasoning`, `supports_image_input`, or `supports_pdf_input` to override.
+
 ## Multi-turn conversations
 
-Call `achat()` or `run()` again on the same `Agent` to continue the conversation:
+Call `achat()` or `run()` again on the same `Agent` to continue:
 
 ```python
 agent = Agent(model="claude-sonnet-4-6", api_key="...")
@@ -80,6 +113,8 @@ agent.run("What is 2 + 2?")
 agent.run("Now multiply that by 10.")    # remembers the earlier answer
 ```
 
+`agent.clear()` drops in-memory history. `agent.messages` accumulates across calls.
+
 ## Attachments
 
 Pass `attachments` to `achat()` or `run()` to add files alongside the prompt:
@@ -89,7 +124,7 @@ 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:
+# Or build them explicitly:
 agent.run(
     "Review.",
     attachments=[
@@ -100,7 +135,7 @@ agent.run(
 )
 ```
 
-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.
+Images support `image/png`, `image/jpeg`, `image/gif`, `image/webp`; documents support `application/pdf`. Sending an image or PDF to a model without that capability yields an `error` event. A bad path or unsupported type raises `ValueError` before the provider is called.
 
 ## Saving sessions
 
@@ -119,15 +154,7 @@ agent = Agent(
 
 Construct another `Agent` with the same `(session_dir, session_id)` to load the conversation history.
 
-## Built-in tools
-
-```python
-from mycode import read_tool, write_tool, edit_tool, bash_tool
-```
-
-Four tools for reading, writing, editing files, and running shell commands. Opt in by passing them to `tools=[...]`.
-
-## Custom tools
+## Tools
 
 Decorate a typed function with `@tool`:
 
@@ -153,36 +180,48 @@ agent = Agent(
 )
 ```
 
-To call a built-in tool from inside your own tool, type the first parameter as `ToolContext`:
+To call another registered tool from inside a tool, type the first parameter as `ToolContext` and dispatch by name:
 
 ```python
 from mycode import ToolContext, tool
 
 
 @tool
-def summarize_file(ctx: ToolContext, path: str) -> str:
-    """Return the first line of a text file."""
+def greet_team(ctx: ToolContext, names: list[str]) -> str:
+    """Greet several people at once."""
 
-    result = ctx.read(path)
-    return result.output.splitlines()[0] if result.output else ""
+    return "\n".join(ctx.call("greet", {"name": name}).output for name in names)
 ```
 
-Async tools use `await ctx.aread()`, `await ctx.awrite()`, `await ctx.aedit()`, and `await ctx.abash()`. Use `await ctx.acall(name, args)` to call another registered tool by name.
+Async tools use `await ctx.acall(name, args)` instead.
 
 ## Tool hooks
 
 Inspect or replace tool calls before they run. Return `None` from `before_tool` to let the tool execute, or a `ToolExecutionResult` to skip it:
 
 ```python
-from mycode import Agent, Hooks, ToolExecutionResult, bash_tool
+import os
+
+from mycode import Agent, Hooks, ToolExecutionResult, tool
 
 hooks = Hooks()
 
 
+@tool
+def delete_file(path: str) -> str:
+    """Delete a file.
+
+    Args:
+        path: Path of the file to delete.
+    """
+
+    os.remove(path)
+    return f"deleted {path}"
+
+
 @hooks.before_tool
-async def block_rm(ctx):
-    cmd = str(ctx.tool_input.get("command") or "")
-    if ctx.tool_name == "bash" and "rm -rf" in cmd:
+async def protect_dotfiles(ctx):
+    if ctx.tool_name == "delete_file" and str(ctx.tool_input.get("path") or "").startswith("."):
         return ToolExecutionResult(output="error: blocked", is_error=True)
     return None
 
@@ -190,11 +229,13 @@ async def block_rm(ctx):
 agent = Agent(
     model="claude-sonnet-4-6",
     api_key="...",
-    tools=[bash_tool],
+    tools=[delete_file],
     hooks=hooks,
 )
 ```
 
 `@hooks.after_tool` runs after the tool and can replace the result (audit, redact, etc.).
 
-See [docs/sdk.md](../docs/sdk.md) for the event stream, cancellation, sessions, and the full `Agent` / `@tool` reference.
+## Further reading
+
+See [docs/sdk.md](https://github.com/legibet/mycode/blob/main/docs/sdk.md) for the streaming event API, cancellation, retries, compaction, session internals, and the full `Agent` / `@tool` reference.

mycode_sdk-0.13.0/README.md

@@ -0,0 +1,213 @@
+# mycode-sdk
+
+Lightweight Python SDK for building AI agents. Multi-turn conversations, tool calling, session persistence, and streaming events. Provider adapters for Anthropic, OpenAI, Google, and more.
+
+## Install
+
+```bash
+uv add mycode-sdk
+# or
+pip install mycode-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from pathlib import Path
+
+from mycode import Agent, tool
+
+
+@tool
+def read_file(path: str) -> str:
+    """Read a UTF-8 text file.
+
+    Args:
+        path: File path, relative to the working directory.
+    """
+
+    return Path(path).read_text(encoding="utf-8")
+
+
+async def main() -> None:
+    agent = Agent(
+        model="claude-sonnet-4-6",
+        api_key="YOUR_API_KEY",
+        tools=[read_file],
+    )
+
+    async for event in agent.achat("Read pyproject.toml and tell me the project name."):
+        if event.type == "text":
+            print(event.data["delta"], end="", flush=True)
+
+
+asyncio.run(main())
+```
+
+`Agent(...)` infers the provider from the model id. No tools are registered unless you pass `tools=[...]`.
+
+For a synchronous call, use `run()`:
+
+```python
+result = agent.run("Read pyproject.toml and tell me the project name.")
+print(result.text)
+```
+
+## Providers
+
+The SDK infers the provider from the model string (`claude-*` to Anthropic, `gpt-*` to OpenAI, etc.). API keys are auto-discovered from environment variables:
+
+| Provider | id | Env var |
+| --- | --- | --- |
+| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
+| OpenAI | `openai` | `OPENAI_API_KEY` |
+| Google Gemini | `google` | `GEMINI_API_KEY` |
+| Moonshot | `moonshotai` | `MOONSHOT_API_KEY` |
+| MiniMax | `minimax` | `MINIMAX_API_KEY` |
+| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
+| Z.AI | `zai` | `ZAI_API_KEY` |
+| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
+| Alibaba Cloud | `alibaba` | `DASHSCOPE_API_KEY` |
+| xAI | `xai` | `XAI_API_KEY` |
+| OpenAI-compatible | `openai_chat` | - |
+
+Pass `api_key=` to override the env var, `api_base=` for a custom endpoint. Model metadata is bundled from [models.dev](https://models.dev); pass `context_window`, `supports_reasoning`, `supports_image_input`, or `supports_pdf_input` to override.
+
+## Multi-turn conversations
+
+Call `achat()` or `run()` again on the same `Agent` to continue:
+
+```python
+agent = Agent(model="claude-sonnet-4-6", api_key="...")
+
+agent.run("What is 2 + 2?")
+agent.run("Now multiply that by 10.")    # remembers the earlier answer
+```
+
+`agent.clear()` drops in-memory history. `agent.messages` accumulates across calls.
+
+## 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:
+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 without that capability yields an `error` event. A bad path or unsupported type raises `ValueError` before the provider is called.
+
+## Saving sessions
+
+Pass `session_dir` to persist the conversation to disk. Each session lives in a subdirectory named by `session_id`:
+
+```python
+from pathlib import Path
+
+agent = Agent(
+    model="claude-sonnet-4-6",
+    api_key="...",
+    session_dir=Path("./chats"),
+    session_id="my-chat",
+)
+```
+
+Construct another `Agent` with the same `(session_dir, session_id)` to load the conversation history.
+
+## Tools
+
+Decorate a typed function with `@tool`:
+
+```python
+from mycode import Agent, tool
+
+
+@tool
+def greet(name: str) -> str:
+    """Return a friendly greeting.
+
+    Args:
+        name: Person name.
+    """
+
+    return f"hello, {name}"
+
+
+agent = Agent(
+    model="claude-sonnet-4-6",
+    api_key="...",
+    tools=[greet],
+)
+```
+
+To call another registered tool from inside a tool, type the first parameter as `ToolContext` and dispatch by name:
+
+```python
+from mycode import ToolContext, tool
+
+
+@tool
+def greet_team(ctx: ToolContext, names: list[str]) -> str:
+    """Greet several people at once."""
+
+    return "\n".join(ctx.call("greet", {"name": name}).output for name in names)
+```
+
+Async tools use `await ctx.acall(name, args)` instead.
+
+## Tool hooks
+
+Inspect or replace tool calls before they run. Return `None` from `before_tool` to let the tool execute, or a `ToolExecutionResult` to skip it:
+
+```python
+import os
+
+from mycode import Agent, Hooks, ToolExecutionResult, tool
+
+hooks = Hooks()
+
+
+@tool
+def delete_file(path: str) -> str:
+    """Delete a file.
+
+    Args:
+        path: Path of the file to delete.
+    """
+
+    os.remove(path)
+    return f"deleted {path}"
+
+
+@hooks.before_tool
+async def protect_dotfiles(ctx):
+    if ctx.tool_name == "delete_file" and str(ctx.tool_input.get("path") or "").startswith("."):
+        return ToolExecutionResult(output="error: blocked", is_error=True)
+    return None
+
+
+agent = Agent(
+    model="claude-sonnet-4-6",
+    api_key="...",
+    tools=[delete_file],
+    hooks=hooks,
+)
+```
+
+`@hooks.after_tool` runs after the tool and can replace the result (audit, redact, etc.).
+
+## Further reading
+
+See [docs/sdk.md](https://github.com/legibet/mycode/blob/main/docs/sdk.md) for the streaming event API, cancellation, retries, compaction, session internals, and the full `Agent` / `@tool` reference.

{mycode_sdk-0.11.2 → mycode_sdk-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mycode-sdk"
-version = "0.11.2"
+version = "0.13.0"
 description = "Lightweight Python SDK for building AI agents."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -26,6 +26,7 @@ dependencies = [
     "anthropic>=0.116.0",
     "google-genai>=2.11.0",
     "griffelib>=2.1.0",
+    "httpx>=0.28.0",
     "openai>=2.45.0",
     "pydantic>=2.13.4",
 ]

{mycode_sdk-0.11.2 → mycode_sdk-0.13.0}/src/mycode/__init__.py

@@ -11,6 +11,7 @@ from mycode.messages import (
     ConversationMessage,
     assistant_message,
     build_message,
+    build_usage,
     document_block,
     flatten_message_text,
     image_block,
@@ -20,18 +21,15 @@ from mycode.messages import (
     tool_use_block,
     user_text_message,
 )
+from mycode.models import Cost, ModelMetadata, estimate_cost, resolve_model_metadata
+from mycode.providers.base import ProviderError, StreamStartTimeoutError
 from mycode.session import SessionStore
 from mycode.tools import (
     ToolContext,
     ToolExecutionResult,
     ToolExecutor,
     ToolSpec,
-    bash_tool,
-    cancel_all_tools,
-    edit_tool,
-    read_tool,
     tool,
-    write_tool,
 )
 
 __version__ = metadata.version("mycode-sdk")
@@ -41,15 +39,19 @@ __all__ = [
     "Attachment",
     "ContentBlock",
     "ConversationMessage",
+    "Cost",
     "Event",
     "AfterToolHook",
     "BeforeToolHook",
     "HookResult",
     "Hooks",
+    "ModelMetadata",
     "NothingToCompactError",
     "PersistCallback",
+    "ProviderError",
     "RunResult",
     "SessionStore",
+    "StreamStartTimeoutError",
     "ToolContext",
     "ToolExecutionResult",
     "ToolExecutor",
@@ -57,19 +59,17 @@ __all__ = [
     "ToolSpec",
     "__version__",
     "assistant_message",
-    "bash_tool",
     "build_message",
-    "cancel_all_tools",
+    "build_usage",
     "document_block",
-    "edit_tool",
+    "estimate_cost",
     "flatten_message_text",
     "image_block",
-    "read_tool",
+    "resolve_model_metadata",
     "text_block",
     "thinking_block",
     "tool",
     "tool_result_block",
     "tool_use_block",
     "user_text_message",
-    "write_tool",
 ]