mirascope 2.0.0a0__tar.gz → 2.0.0a2__tar.gz

{mirascope-2.0.0a0 → mirascope-2.0.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 2.0.0a0
+Version: 2.0.0a2
 Summary: LLM abstractions that aren't obstructions
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/docs/mirascope/v2
@@ -40,13 +40,23 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: File Formats :: JSON
 Classifier: Topic :: File Formats :: JSON :: JSON Schema
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
 Requires-Dist: docstring-parser>=0.17.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
 Requires-Dist: typing-extensions>=4.10.0
+Provides-Extra: all
+Requires-Dist: anthropic<1.0,>=0.72.0; extra == 'all'
+Requires-Dist: google-genai<2,>=1.48.0; extra == 'all'
+Requires-Dist: mcp<2,>=1.0.0; extra == 'all'
+Requires-Dist: openai<3,>=2.7.1; extra == 'all'
+Requires-Dist: pillow<11,>=10.4.0; extra == 'all'
+Requires-Dist: proto-plus>=1.24.0; extra == 'all'
 Provides-Extra: anthropic
 Requires-Dist: anthropic<1.0,>=0.72.0; extra == 'anthropic'
 Provides-Extra: google

mirascope-2.0.0a2/examples/intro/context/decorator.py

@@ -0,0 +1,40 @@
+from mirascope import llm
+
+
+class Library:
+    available_books: list[str]
+    detailed_book_info: dict[str, str]
+
+
+@llm.tool()
+# [!code highlight:2]
+def get_book_info(ctx: llm.Context[Library], book: str) -> str:
+    return ctx.deps.detailed_book_info.get(book, "Book not found")
+
+
+@llm.call(provider="openai", model_id="gpt-5", tools=[get_book_info])
+# [!code highlight:2]
+def librarian(ctx: llm.Context[Library], query: str):
+    book_list = "\n".join(ctx.deps.available_books)
+    return [
+        llm.messages.system(
+            f"You are a librarian, with access to these books: ${book_list}"
+        ),
+        query,
+    ]
+
+
+def main():
+    library = Library()
+    query = "Please recommend a mind-bending book from the library."
+    ctx = llm.Context(deps=library)  # [!code highlight]
+    response: llm.ContextResponse[Library] = librarian(ctx, query)  # [!code highlight]
+
+    while response.tool_calls:
+        tool_outputs = response.execute_tools(ctx)  # [!code highlight]
+        response = response.resume(ctx, tool_outputs)  # [!code highlight]
+
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/context/model.py

@@ -0,0 +1,41 @@
+from mirascope import llm
+
+
+class Library:
+    available_books: list[str]
+    detailed_book_info: dict[str, str]
+
+
+@llm.tool()
+# [!code highlight:2]
+def get_book_info(ctx: llm.Context[Library], book: str) -> str:
+    return ctx.deps.detailed_book_info.get(book, "Book not found")
+
+
+# [!code highlight:2]
+def librarian(ctx: llm.Context[Library], query: str):
+    model = llm.use_model(provider="openai", model_id="gpt-5")
+    book_list = "\n".join(ctx.deps.available_books)
+    messages = [
+        llm.messages.system(
+            f"You are a librarian, with access to these books: ${book_list}"
+        ),
+        query,
+    ]
+    # [!code highlight:2]
+    return model.context_call(ctx=ctx, messages=messages, tools=[get_book_info])
+
+
+def main():
+    query = "Please recommend a mind-bending book from the library."
+    ctx = llm.Context(deps=Library())  # [!code highlight]
+    response: llm.ContextResponse[Library] = librarian(ctx, query)  # [!code highlight]
+
+    while response.tool_calls:
+        tool_outputs = response.execute_tools(ctx)  # [!code highlight]
+        response = response.resume(ctx, tool_outputs)  # [!code highlight]
+
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/decorator/async.py

@@ -0,0 +1,17 @@
+import asyncio
+
+from mirascope import llm
+
+
+@llm.call(provider="openai", model_id="gpt-5")
+async def recommend_book(genre: str):
+    return f"Please recommend a book in {genre}."
+
+
+async def main():
+    response: llm.AsyncResponse = await recommend_book("fantasy")
+    print(response.pretty())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mirascope-2.0.0a2/examples/intro/decorator/async_stream.py

@@ -0,0 +1,18 @@
+import asyncio
+
+from mirascope import llm
+
+
+@llm.call(provider="openai", model_id="gpt-5")
+async def recommend_book(genre: str):
+    return f"Please recommend a book in {genre}."
+
+
+async def main():
+    response: llm.AsyncStreamResponse = await recommend_book.stream("fantasy")
+    async for chunk in response.pretty_stream():
+        print(chunk, flush=True, end="")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mirascope-2.0.0a2/examples/intro/decorator/stream.py

@@ -0,0 +1,15 @@
+from mirascope import llm
+
+
+@llm.call(provider="openai", model_id="gpt-5")
+def recommend_book(genre: str):
+    return f"Please recommend a book in {genre}."
+
+
+def main():
+    response: llm.StreamResponse = recommend_book.stream("fantasy")
+    for chunk in response.pretty_stream():
+        print(chunk, flush=True, end="")
+
+
+main()

mirascope-2.0.0a2/examples/intro/decorator/sync.py

@@ -0,0 +1,14 @@
+from mirascope import llm
+
+
+@llm.call(provider="openai", model_id="gpt-5")
+def recommend_book(genre: str):
+    return f"Please recommend a book in {genre}."
+
+
+def main():
+    response: llm.Response = recommend_book("fantasy")
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/format/decorator.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+
+from mirascope import llm
+
+
+class Book(BaseModel):
+    title: str
+    author: str
+
+
+@llm.call(provider="openai", model_id="gpt-5", format=Book)
+def recommend_book(genre: str):
+    return f"Please recommend a book in {genre}."
+
+
+def main():
+    response: llm.Response[Book] = recommend_book("fantasy")
+    book: Book = response.parse()
+    print(f"{book.title} by {book.author}")
+
+
+main()

mirascope-2.0.0a2/examples/intro/format/model.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel
+
+from mirascope import llm
+
+
+class Book(BaseModel):
+    title: str
+    author: str
+
+
+def recommend_book(genre: str) -> llm.Response[Book]:
+    model: llm.Model = llm.use_model(provider="openai", model_id="gpt-5")
+    message = llm.messages.user(f"Please recommend a book in {genre}.")
+    return model.call(
+        messages=[message],
+        format=Book,  # [!code highlight]
+    )
+
+
+def main():
+    response: llm.Response[Book] = recommend_book("fantasy")
+    book: Book = response.parse()
+    print(f"{book.title} by {book.author}")
+
+
+main()

mirascope-2.0.0a2/examples/intro/model/async.py

@@ -0,0 +1,18 @@
+import asyncio
+
+from mirascope import llm
+
+
+async def recommend_book(genre: str) -> llm.AsyncResponse:
+    model: llm.Model = llm.use_model(provider="openai", model_id="gpt-5")
+    message = llm.messages.user(f"Please recommend a book in {genre}.")
+    return await model.call_async(messages=[message])
+
+
+async def main():
+    response: llm.AsyncResponse = await recommend_book("fantasy")
+    print(response.pretty())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mirascope-2.0.0a2/examples/intro/model/async_stream.py

@@ -0,0 +1,19 @@
+import asyncio
+
+from mirascope import llm
+
+
+async def recommend_book(genre: str) -> llm.AsyncStreamResponse:
+    model: llm.Model = llm.use_model(provider="openai", model_id="gpt-5")
+    message = llm.messages.user(f"Please recommend a book in {genre}.")
+    return await model.stream_async(messages=[message])
+
+
+async def main():
+    response: llm.AsyncStreamResponse = await recommend_book("fantasy")
+    async for chunk in response.pretty_stream():
+        print(chunk, flush=True, end="")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mirascope-2.0.0a2/examples/intro/model/stream.py

@@ -0,0 +1,16 @@
+from mirascope import llm
+
+
+def recommend_book(genre: str) -> llm.StreamResponse:
+    model: llm.Model = llm.use_model(provider="openai", model_id="gpt-5")
+    message = llm.messages.user(f"Please recommend a book in {genre}.")
+    return model.stream(messages=[message])
+
+
+def main():
+    response: llm.StreamResponse = recommend_book("fantasy")
+    for chunk in response.pretty_stream():
+        print(chunk, flush=True, end="")
+
+
+main()

mirascope-2.0.0a2/examples/intro/model/sync.py

@@ -0,0 +1,15 @@
+from mirascope import llm
+
+
+def recommend_book(genre: str) -> llm.Response:
+    model: llm.Model = llm.use_model(provider="openai", model_id="gpt-5")
+    message = llm.messages.user(f"Please recommend a book in {genre}.")
+    return model.call(messages=[message])
+
+
+def main():
+    response: llm.Response = recommend_book("fantasy")
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/override/decorator.py

@@ -0,0 +1,16 @@
+from mirascope import llm
+
+
+@llm.call(provider="openai", model_id="gpt-5")
+def recommend_book(genre: str):
+    return f"Please recommend a book in {genre}."
+
+
+def main():
+    # [!code highlight:2]
+    with llm.model(provider="anthropic", model_id="claude-sonnet-4-0", temperature=1):
+        response: llm.Response = recommend_book("fantasy")
+        print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/override/model.py

@@ -0,0 +1,18 @@
+from mirascope import llm
+
+
+def recommend_book(genre: str) -> llm.Response:
+    # [!code highlight:2]
+    model = llm.use_model(provider="openai", model_id="gpt-4o-mini")
+    message = llm.messages.user(f"Please recommend a book in {genre}.")
+    return model.call(messages=[message])
+
+
+def main():
+    # [!code highlight:2]
+    with llm.model(provider="anthropic", model_id="claude-sonnet-4-0", temperature=1):
+        response: llm.Response = recommend_book("fantasy")
+        print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/parameters/decorator.py

@@ -0,0 +1,18 @@
+from mirascope import llm
+
+
+@llm.call(
+    provider="openai",
+    model_id="gpt-5",
+    temperature=1,  # [!code highlight]
+)
+def recommend_book(genre: str):
+    return f"Please recommend a book in {genre}."
+
+
+def main():
+    response: llm.Response = recommend_book("fantasy")
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/parameters/model.py

@@ -0,0 +1,19 @@
+from mirascope import llm
+
+
+def recommend_book(genre: str) -> llm.Response:
+    model = llm.use_model(
+        provider="openai",
+        model_id="gpt-5",
+        temperature=1,  # [!code highlight]
+    )
+    message = llm.messages.user(f"Please recommend a book in {genre}.")
+    return model.call(messages=[message])
+
+
+def main():
+    response: llm.Response = recommend_book("fantasy")
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/resume/decorator.py

@@ -0,0 +1,17 @@
+from mirascope import llm
+
+
+@llm.call(provider="openai", model_id="gpt-5")
+def recommend_book(genre: str):
+    return f"Please recommend a book in {genre}."
+
+
+def main():
+    response: llm.Response = recommend_book("fantasy")
+    print(response.pretty())
+    # [!code highlight:2]
+    continuation: llm.Response = response.resume("Please explain your choice.")
+    print(continuation.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/resume/model.py

@@ -0,0 +1,18 @@
+from mirascope import llm
+
+
+def recommend_book(genre: str) -> llm.Response:
+    model: llm.Model = llm.use_model(provider="openai", model_id="gpt-5")
+    message = llm.messages.user(f"Please recommend a book in {genre}.")
+    return model.call(messages=[message])
+
+
+def main():
+    response: llm.Response = recommend_book("fantasy")
+    print(response.pretty())
+    # [!code highlight:2]
+    continuation: llm.Response = response.resume("Please explain your choice.")
+    print(continuation.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/system_messages/decorator.py

@@ -0,0 +1,18 @@
+from mirascope import llm
+
+
+@llm.call(provider="openai", model_id="gpt-5")
+def recommend_book(genre: str):
+    return [
+        # [!code highlight]
+        llm.messages.system("Always recommend kid-friendly books."),
+        llm.messages.user(f"Please recommend a book in {genre}."),
+    ]
+
+
+def main():
+    response: llm.Response = recommend_book("fantasy")
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/system_messages/model.py

@@ -0,0 +1,20 @@
+from mirascope import llm
+
+
+def recommend_book(genre: str) -> llm.Response:
+    model = llm.use_model(provider="openai", model_id="gpt-5")
+    return model.call(
+        messages=[
+            # [!code highlight]
+            llm.messages.system("Always recommend kid-friendly books."),
+            llm.messages.user(f"Please recommend a book in {genre}."),
+        ]
+    )
+
+
+def main():
+    response: llm.Response = recommend_book("fantasy")
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/tool_call/decorator.py

@@ -0,0 +1,36 @@
+from mirascope import llm
+
+
+@llm.tool()  # [!code highlight]
+def available_library_books() -> list[str]:  # [!code highlight]
+    return [
+        "Mistborn by Brandon Sanderson",
+        "The Name of the Wind by Patrick Rothfuss",
+        "Too Like the Lightning by Ada Palmer",
+        "Wild Seed by Octavia Butler",
+    ]
+
+
+@llm.call(
+    provider="openai",
+    model_id="gpt-5",
+    tools=[available_library_books],
+)
+def librarian(query: str):
+    return query
+
+
+def main():
+    response: llm.Response = librarian(
+        "Please recommend a mind-bending book that's available in the library."
+    )
+
+    # [!code highlight:4]
+    while response.tool_calls:
+        tool_outputs = response.execute_tools()
+        response = response.resume(tool_outputs)
+
+    print(response.pretty())
+
+
+main()

mirascope-2.0.0a2/examples/intro/tool_call/model.py

@@ -0,0 +1,36 @@
+from mirascope import llm
+
+
+@llm.tool()  # [!code highlight]
+def available_library_books() -> list[str]:  # [!code highlight]
+    return [
+        "Mistborn by Brandon Sanderson",
+        "The Name of the Wind by Patrick Rothfuss",
+        "Too Like the Lightning by Ada Palmer",
+        "Wild Seed by Octavia Butler",
+    ]
+
+
+def librarian(query: str) -> llm.Response:
+    model = llm.use_model(provider="openai", model_id="gpt-5")
+    message = llm.messages.user(query)
+    return model.call(
+        messages=[message],
+        tools=[available_library_books],  # [!code highlight]
+    )
+
+
+def main():
+    response: llm.Response = librarian(
+        "Please recommend a mind-bending book that's available in the library."
+    )
+
+    # [!code highlight:4]
+    while response.tool_calls:
+        tool_outputs = response.execute_tools()
+        response = response.resume(tool_outputs)
+
+    print(response.pretty())
+
+
+main()

{mirascope-2.0.0a0 → mirascope-2.0.0a2}/lint-staged.ts

@@ -29,7 +29,7 @@ try {
   }
 
   // Run pyright on the whole project (doesn't work well with individual files)
-  await $`uv run pyright`.cwd("./python");
+  await $`uv run pyright .`.cwd("./python");
 
   await $`bun run codespell`;
 

{mirascope-2.0.0a0 → mirascope-2.0.0a2}/mirascope/llm/__init__.py

@@ -8,13 +8,14 @@ code that works with multiple LLM providers without changing your application lo
 # TODO: Across the API, audit docstrings to ensure they are compliant Google-style docstrings
 # (Write some tooling to ensure this happens consistently + in CI)
 
+from contextlib import suppress
+
 from . import (
     calls,
     clients,
     content,
     exceptions,
     formatting,
-    mcp,
     messages,
     models,
     prompts,
@@ -22,6 +23,9 @@ from . import (
     tools,
     types,
 )
+
+with suppress(ImportError):
+    from . import mcp
 from .calls import call
 from .clients import ModelId, Params, Provider, client, get_client
 from .content import (

mirascope-2.0.0a2/mirascope/llm/clients/_missing_import_stubs.py

@@ -0,0 +1,47 @@
+"""Utilities for handling optional provider dependencies."""
+
+from collections.abc import Callable
+
+
+def create_import_error_stub(
+    package_name: str, client_name: str
+) -> Callable:  # pragma: no cover
+    """Create a stub that raises ImportError when called.
+
+    Args:
+        package_name: The package/extra name (e.g., "anthropic", "openai", "google")
+        client_name: The client name for the error message (e.g., "AnthropicClient")
+
+    Returns:
+        A callable that raises `ImportError` with helpful message.
+    """
+
+    def _raise_not_installed() -> None:
+        raise ImportError(
+            f"The '{package_name}' package is required to use {client_name}. "
+            f"Install it with: `uv add 'mirascope[{package_name}]'`. "
+            "Or use `uv add 'mirascope[all]'` to support all providers."
+        )
+
+    return _raise_not_installed
+
+
+def create_client_stub(package_name: str, client_name: str) -> type:  # pragma: no cover
+    """Create a stub client class that raises ImportError when instantiated.
+
+    Args:
+        package_name: The package/extra name (e.g., "anthropic", "openai", "google")
+        client_name: The client name for the error message (e.g., "AnthropicClient")
+
+    Returns:
+        A stub class that raises `ImportError` on instantiation.
+    """
+    error_fn = create_import_error_stub(package_name, client_name)
+
+    class _ClientStub:
+        """Stub client that raises `ImportError` when instantiated."""
+
+        def __init__(self) -> None:
+            error_fn()
+
+    return _ClientStub

mirascope-2.0.0a2/mirascope/llm/clients/anthropic/__init__.py

@@ -0,0 +1,25 @@
+"""Anthropic client implementation."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .clients import AnthropicClient, client, get_client
+    from .model_ids import AnthropicModelId
+else:
+    try:
+        from .clients import AnthropicClient, client, get_client
+        from .model_ids import AnthropicModelId
+    except ImportError:  # pragma: no cover
+        from .._missing_import_stubs import create_client_stub, create_import_error_stub
+
+        AnthropicClient = create_client_stub("anthropic", "AnthropicClient")
+        AnthropicModelId = str
+        client = create_import_error_stub("anthropic", "AnthropicClient")
+        get_client = create_import_error_stub("anthropic", "AnthropicClient")
+
+__all__ = [
+    "AnthropicClient",
+    "AnthropicModelId",
+    "client",
+    "get_client",
+]

mirascope-2.0.0a2/mirascope/llm/clients/google/__init__.py

@@ -0,0 +1,20 @@
+"""Google client implementation."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .clients import GoogleClient, client, get_client
+    from .model_ids import GoogleModelId
+else:
+    try:
+        from .clients import GoogleClient, client, get_client
+        from .model_ids import GoogleModelId
+    except ImportError:  # pragma: no cover
+        from .._missing_import_stubs import create_client_stub, create_import_error_stub
+
+        GoogleClient = create_client_stub("google", "GoogleClient")
+        GoogleModelId = str
+        client = create_import_error_stub("google", "GoogleClient")
+        get_client = create_import_error_stub("google", "GoogleClient")
+
+__all__ = ["GoogleClient", "GoogleModelId", "client", "get_client"]