mirascope 2.0.1__tar.gz → 2.1.0__tar.gz

mirascope-2.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: mirascope
+Version: 2.1.0
+Summary: Every frontier LLM. One unified interface.
+Project-URL: Homepage, https://mirascope.com
+Project-URL: Documentation, https://mirascope.com/docs/mirascope/v2
+Project-URL: Repository, https://github.com/Mirascope/mirascope/tree/v2
+Project-URL: Issues, https://github.com/Mirascope/mirascope/issues
+Project-URL: Changelog, https://github.com/Mirascope/mirascope/releases
+Author-email: William Bakst <william@mirascope.com>, Dandelion Mané <dandelion@mirascope.com>
+Maintainer-email: William Bakst <william@mirascope.com>, Dandelion Mané <dandelion@mirascope.com>
+License: MIT License
+        
+        Copyright (c) 2026 Mirascope, Inc.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,anthropic,artificial intelligence,context engineering,developer tools,gemini,llm,llm tools,openai,prompt engineering
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: jiter>=0.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.10.0
+Provides-Extra: all
+Requires-Dist: anthropic<1.0,>=0.76.0; extra == 'all'
+Requires-Dist: google-genai<2,>=1.58.0; extra == 'all'
+Requires-Dist: libcst>=1.8.6; extra == 'all'
+Requires-Dist: mcp<2,>=1.25.0; extra == 'all'
+Requires-Dist: mlx-lm<1,>=0.28.4; extra == 'all'
+Requires-Dist: openai<3,>=2.15.0; extra == 'all'
+Requires-Dist: opentelemetry-api<2,>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-anthropic<1,>=0.50.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-google-genai<1,>=0.3b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-openai-v2<3,>=2.0b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation<1,>=0.59b0; extra == 'all'
+Requires-Dist: opentelemetry-propagator-b3<2,>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-propagator-b3>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-propagator-jaeger>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk<2,>=1.38.0; extra == 'all'
+Requires-Dist: orjson>=3.11.4; extra == 'all'
+Requires-Dist: packaging>=25.0; extra == 'all'
+Requires-Dist: pillow<11,>=10.4.0; extra == 'all'
+Requires-Dist: proto-plus>=1.24.0; extra == 'all'
+Requires-Dist: pydantic-settings>=2.12.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1.0,>=0.76.0; extra == 'anthropic'
+Provides-Extra: api
+Requires-Dist: pydantic-settings>=2.12.0; extra == 'api'
+Provides-Extra: google
+Requires-Dist: google-genai<2,>=1.58.0; extra == 'google'
+Requires-Dist: pillow<11,>=10.4.0; extra == 'google'
+Requires-Dist: proto-plus>=1.24.0; extra == 'google'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.25.0; extra == 'mcp'
+Provides-Extra: mlx
+Requires-Dist: mlx-lm<1,>=0.28.4; extra == 'mlx'
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2.15.0; extra == 'openai'
+Provides-Extra: ops
+Requires-Dist: libcst>=1.8.6; extra == 'ops'
+Requires-Dist: opentelemetry-api<2,>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-anthropic<1,>=0.50.0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-google-genai<1,>=0.3b0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-openai-v2<3,>=2.0b0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation<1,>=0.59b0; extra == 'ops'
+Requires-Dist: opentelemetry-propagator-b3<2,>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-propagator-b3>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-propagator-jaeger>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-sdk<2,>=1.38.0; extra == 'ops'
+Requires-Dist: orjson>=3.11.4; extra == 'ops'
+Requires-Dist: packaging>=25.0; extra == 'ops'
+Description-Content-Type: text/markdown
+
+# Mirascope Python
+
+This directory contains the Python implementation of Mirascope: The LLM Anti-Framework. It's intended as a "Goldilocks API" that affords the fine-grained control you'd get from using raw provider APIs, as well as the type safety and easy ergonomics that are offered by higher-level agent frameworks. Think of Mirascope as the "React" of LLM development, where provider native APIs are HTML/CSS, and the agent frameworks are Angular.
+
+## Documentation 
+
+- [Why use Mirascope?](https://mirascope.com/docs/why)
+- [Mirascope Quickstart](https://mirascope.com/docs/quickstart)
+- [Mirascope Concepts](https://mirascope.com/docs/learn/llm)
+
+## Installation
+
+```bash
+# using uv, with all provider deps
+uv add "mirascope[all]"
+
+# using uv, with just Anthropic
+uv add "mirascope[anthropic]"
+
+# using pip, with all deps 
+pip install "mirascope[all]"
+
+# using pip, just OpenAI
+pip install "mirascope[openai]"
+```
+
+## Usage
+
+Here's an example of creating a simple agent, with tool-calling and streaming, using Mirascope. For many more examples, [read the docs](https://mirascope.com/docs).
+
+```python
+from mirascope import llm
+
+@llm.tool
+def exp(a: float, b: float) -> float:
+   """Compute an exponent"""
+   return a ** b
+
+@llm.tool
+def add(a: float, b: float) -> float:
+   """Add two numbers"""
+   return a + b
+
+model = llm.Model("anthropic/claude-haiku-4-5")
+response = model.stream("What is 42 ** 4 + 37 ** 3?", tools=[exp, add])
+
+while True:
+   for stream in response.streams():
+         if stream.content_type == "text":
+            for delta in stream:
+               print(delta, end="", flush=True)
+         elif stream.content_type == "tool_call":
+            stream.collect()  # consume the stream
+            print(f"\n> Calling {stream.tool_name}({stream.partial_args})")
+   print()
+   if response.tool_calls:
+         response = response.resume(response.execute_tools())
+   else:
+         break
+```
+
+## Development Setup
+
+1. **Environment Variables**: Copy `.env.example` to `.env` and fill in your API keys:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys
+   # Necessary for updating e2e snapshot tests
+   ```
+
+2. **Install Dependencies**:
+
+   ```bash
+   cd python
+   uv sync --all-extras --dev
+   ```
+
+## Helpful Commands:
+
+Here are helpful development commands. All must be run from within the `python` directory.
+
+- `uv run pyright .`
+
+Run typechecking.
+
+- `uv run ruff check --fix .`
+
+Check ruff linter (fixing issues where possible).
+
+- `uv run ruff format .`
+
+Run ruff formatter.
+
+- `uv run pytest`
+
+Run all Python unit tests.
+
+- `uv run pytest --cov --cov-config=.coverargc --cov-report=term-missing`
+
+Run all Python unit tests, and report code coverage. (We require 100% coverage in CI.)
+
+- `uv run pytest --fix`
+
+Run all Python unit tests, and update any changed snapshots.
+
+- `uvx codespell --config ../.codespellrc`
+
+Run codespell, identifying many common spelling mistakes.
+
+## Typechecking
+
+We prize type safety, both on the API surface and internally. You can run typechecking via `uv run pyright .` within this `python/` directory. (We're looking into supporting `ty` so as to speed up our typechecking.)
+
+## Testing
+
+This project makes extensive use of e2e tests, which replay real interactions with various LLM providers to ensure that Mirascope truly works on the providers' APIs. We use [VCR.py](https://vcrpy.readthedocs.io/) and [inline-snapshot](https://15r10nk.github.io/inline-snapshot/) to maintain these e2e tests. For more details, read [tests/e2e/README.md](./tests/e2e/README.md).
+
+If you make changes to Mirascope that require new snapshots, you should manually delete the outdated cassette files, and then run `uv run pytest python/tests/e2e --fix`. Note that doing so requires real API keys in your `.env` file.
+
+We require 100% code coverage in CI. You can get a code coverage report via:
+
+`uv run pytest --cov --cov-config=.coverargc --cov-report=term-missing`
+
+## Read More
+
+For more info on contributing, read [the contributing page in our docs](https://mirascope.com/docs/contributing).

mirascope-2.1.0/README.md

@@ -0,0 +1,126 @@
+# Mirascope Python
+
+This directory contains the Python implementation of Mirascope: The LLM Anti-Framework. It's intended as a "Goldilocks API" that affords the fine-grained control you'd get from using raw provider APIs, as well as the type safety and easy ergonomics that are offered by higher-level agent frameworks. Think of Mirascope as the "React" of LLM development, where provider native APIs are HTML/CSS, and the agent frameworks are Angular.
+
+## Documentation 
+
+- [Why use Mirascope?](https://mirascope.com/docs/why)
+- [Mirascope Quickstart](https://mirascope.com/docs/quickstart)
+- [Mirascope Concepts](https://mirascope.com/docs/learn/llm)
+
+## Installation
+
+```bash
+# using uv, with all provider deps
+uv add "mirascope[all]"
+
+# using uv, with just Anthropic
+uv add "mirascope[anthropic]"
+
+# using pip, with all deps 
+pip install "mirascope[all]"
+
+# using pip, just OpenAI
+pip install "mirascope[openai]"
+```
+
+## Usage
+
+Here's an example of creating a simple agent, with tool-calling and streaming, using Mirascope. For many more examples, [read the docs](https://mirascope.com/docs).
+
+```python
+from mirascope import llm
+
+@llm.tool
+def exp(a: float, b: float) -> float:
+   """Compute an exponent"""
+   return a ** b
+
+@llm.tool
+def add(a: float, b: float) -> float:
+   """Add two numbers"""
+   return a + b
+
+model = llm.Model("anthropic/claude-haiku-4-5")
+response = model.stream("What is 42 ** 4 + 37 ** 3?", tools=[exp, add])
+
+while True:
+   for stream in response.streams():
+         if stream.content_type == "text":
+            for delta in stream:
+               print(delta, end="", flush=True)
+         elif stream.content_type == "tool_call":
+            stream.collect()  # consume the stream
+            print(f"\n> Calling {stream.tool_name}({stream.partial_args})")
+   print()
+   if response.tool_calls:
+         response = response.resume(response.execute_tools())
+   else:
+         break
+```
+
+## Development Setup
+
+1. **Environment Variables**: Copy `.env.example` to `.env` and fill in your API keys:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys
+   # Necessary for updating e2e snapshot tests
+   ```
+
+2. **Install Dependencies**:
+
+   ```bash
+   cd python
+   uv sync --all-extras --dev
+   ```
+
+## Helpful Commands:
+
+Here are helpful development commands. All must be run from within the `python` directory.
+
+- `uv run pyright .`
+
+Run typechecking.
+
+- `uv run ruff check --fix .`
+
+Check ruff linter (fixing issues where possible).
+
+- `uv run ruff format .`
+
+Run ruff formatter.
+
+- `uv run pytest`
+
+Run all Python unit tests.
+
+- `uv run pytest --cov --cov-config=.coverargc --cov-report=term-missing`
+
+Run all Python unit tests, and report code coverage. (We require 100% coverage in CI.)
+
+- `uv run pytest --fix`
+
+Run all Python unit tests, and update any changed snapshots.
+
+- `uvx codespell --config ../.codespellrc`
+
+Run codespell, identifying many common spelling mistakes.
+
+## Typechecking
+
+We prize type safety, both on the API surface and internally. You can run typechecking via `uv run pyright .` within this `python/` directory. (We're looking into supporting `ty` so as to speed up our typechecking.)
+
+## Testing
+
+This project makes extensive use of e2e tests, which replay real interactions with various LLM providers to ensure that Mirascope truly works on the providers' APIs. We use [VCR.py](https://vcrpy.readthedocs.io/) and [inline-snapshot](https://15r10nk.github.io/inline-snapshot/) to maintain these e2e tests. For more details, read [tests/e2e/README.md](./tests/e2e/README.md).
+
+If you make changes to Mirascope that require new snapshots, you should manually delete the outdated cassette files, and then run `uv run pytest python/tests/e2e --fix`. Note that doing so requires real API keys in your `.env` file.
+
+We require 100% code coverage in CI. You can get a code coverage report via:
+
+`uv run pytest --cov --cov-config=.coverargc --cov-report=term-missing`
+
+## Read More
+
+For more info on contributing, read [the contributing page in our docs](https://mirascope.com/docs/contributing).

mirascope-2.1.0/examples/intro/welcome.py

@@ -0,0 +1,46 @@
+from typing import Literal
+
+from mirascope import llm, ops
+
+# Connect to Mirascope Cloud for tracing and analytics
+ops.configure()
+ops.instrument_llm()
+
+
+@llm.tool
+@ops.trace
+def calculate(
+    operation: Literal["add", "subtract", "multiply", "divide"],
+    a: float,
+    b: float,
+) -> str:
+    """Perform a mathematical operation on two numbers."""
+    match operation:
+        case "add":
+            return str(a + b)
+        case "subtract":
+            return str(a - b)
+        case "multiply":
+            return str(a * b)
+        case "divide":
+            return str(a / b) if b != 0 else "Cannot divide by zero"
+
+
+@ops.version  # Automatically versions `math_agent` and traces it's execution
+@llm.call("openai/gpt-4o-mini", tools=[calculate])
+def math_agent(query: str) -> str:
+    return f"Help the user with: {query}"
+
+
+@ops.trace
+def run_math_agent(query: str) -> str:
+    response = math_agent(query)
+
+    while response.tool_calls:
+        tool_outputs = response.execute_tools()
+        response = response.resume(tool_outputs)
+
+    return response.text()
+
+
+print(run_math_agent("What's 42 * 17?"))

mirascope-2.1.0/examples/tools/web_search.py

@@ -0,0 +1,15 @@
+from mirascope import llm
+
+
+@llm.call("anthropic/claude-sonnet-4-5", tools=[llm.WebSearchTool()])
+def weather_assistant(query: str):
+    return query
+
+
+response = weather_assistant("What's the current weather in San Francisco?")
+print(response.text())
+# Today features intervals of clouds and sunshine with a couple of showers, with a high of 62°F
+# Partly cloudy skies this morning will give way to occasional showers during the afternoon, with a high of 61°F and a 40% chance of rain
+
+# Tonight, expect light rain transitioning to a few showers by morning, with a low of 51°F and a 60% chance of rain
+# The air quality is poor and unhealthy for sensitive groups