feat(api): manual updates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 14
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/miru-ml%2Fmiru-server-1187ba20c7bd5d91919c6e65f71201c9997541aae5ea6b3068b2e8094b4b8d0c.yml
 openapi_spec_hash: fd892348c3cd6e7ec5bdce4d8134bf14
-config_hash: 1e4fdf81e8b8def15eae344d1f29e513
+config_hash: c47912de5d58c4db1a9ed9e3f82a24a0

README.md

@@ -11,7 +11,7 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 ## Documentation
 
-The full API of this library can be found in [api.md](api.md).
+The REST API documentation can be found on [docs.miruml.com](https://docs.miruml.com). The full API of this library can be found in [api.md](api.md).
 
 ## Installation
 
@@ -30,6 +30,8 @@ from miru_server_sdk import Miru
 
 client = Miru(
     api_key=os.environ.get("MIRU_SERVER_API_KEY"),  # This is the default and can be omitted
+    # or 'production' | 'local'; defaults to "production".
+    environment="staging",
 )
 
 config_instance = client.config_instances.retrieve(
@@ -54,6 +56,8 @@ from miru_server_sdk import AsyncMiru
 
 client = AsyncMiru(
     api_key=os.environ.get("MIRU_SERVER_API_KEY"),  # This is the default and can be omitted
+    # or 'production' | 'local'; defaults to "production".
+    environment="staging",
 )
 
 

SECURITY.md

@@ -18,6 +18,10 @@ before making any information public.
 If you encounter security issues that are not directly related to SDKs but pertain to the services
 or products provided by Miru, please follow the respective company's security reporting guidelines.
 
+### Miru Terms and Policies
+
+Please contact [email protected] for any questions or concerns regarding the security of our services.
+
 ---
 
 Thank you for helping us keep the SDKs and systems they interact with secure.

pyproject.toml

@@ -5,7 +5,7 @@ description = "The official Python library for the miru API"
 dynamic = ["readme"]
 license = "MIT"
 authors = [
-{ name = "Miru", email = "" },
+{ name = "Miru", email = "[email protected]" },
 ]
 dependencies = [
     "httpx>=0.23.0, <1",

src/miru_server_sdk/__init__.py

@@ -5,7 +5,18 @@
 from . import types
 from ._types import NOT_GIVEN, Omit, NoneType, NotGiven, Transport, ProxiesTypes, omit, not_given
 from ._utils import file_from_path
-from ._client import Miru, Client, Stream, Timeout, AsyncMiru, Transport, AsyncClient, AsyncStream, RequestOptions
+from ._client import (
+    ENVIRONMENTS,
+    Miru,
+    Client,
+    Stream,
+    Timeout,
+    AsyncMiru,
+    Transport,
+    AsyncClient,
+    AsyncStream,
+    RequestOptions,
+)
 from ._models import BaseModel
 from ._version import __title__, __version__
 from ._response import APIResponse as APIResponse, AsyncAPIResponse as AsyncAPIResponse
@@ -63,6 +74,7 @@
     "AsyncStream",
     "Miru",
     "AsyncMiru",
+    "ENVIRONMENTS",
     "file_from_path",
     "BaseModel",
     "DEFAULT_TIMEOUT",

src/miru_server_sdk/_client.py

@@ -3,8 +3,8 @@
 from __future__ import annotations
 
 import os
-from typing import Any, Mapping
-from typing_extensions import Self, override
+from typing import Any, Dict, Mapping, cast
+from typing_extensions import Self, Literal, override
 
 import httpx
 
@@ -30,7 +30,23 @@
     AsyncAPIClient,
 )
 
-__all__ = ["Timeout", "Transport", "ProxiesTypes", "RequestOptions", "Miru", "AsyncMiru", "Client", "AsyncClient"]
+__all__ = [
+    "ENVIRONMENTS",
+    "Timeout",
+    "Transport",
+    "ProxiesTypes",
+    "RequestOptions",
+    "Miru",
+    "AsyncMiru",
+    "Client",
+    "AsyncClient",
+]
+
+ENVIRONMENTS: Dict[str, str] = {
+    "production": "https://configs.api.miruml.com/v1",
+    "staging": "https://configs.dev.api.miruml.com/v1",
+    "local": "http://localhost:8080/v1",
+}
 
 
 class Miru(SyncAPIClient):
@@ -47,13 +63,16 @@ class Miru(SyncAPIClient):
     host: str
     version: str
 
+    _environment: Literal["production", "staging", "local"] | NotGiven
+
     def __init__(
         self,
         *,
         api_key: str | None = None,
         host: str | None = None,
         version: str | None = None,
-        base_url: str | httpx.URL | None = None,
+        environment: Literal["production", "staging", "local"] | NotGiven = not_given,
+        base_url: str | httpx.URL | None | NotGiven = not_given,
         timeout: float | Timeout | None | NotGiven = not_given,
         max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Mapping[str, str] | None = None,
@@ -95,10 +114,31 @@ def __init__(
             version = os.environ.get("MIRU_SERVER_VERSION") or "v1"
         self.version = version
 
-        if base_url is None:
-            base_url = os.environ.get("MIRU_BASE_URL")
-        if base_url is None:
-            base_url = f"https://{host}/{version}"
+        self._environment = environment
+
+        base_url_env = os.environ.get("MIRU_BASE_URL")
+        if is_given(base_url) and base_url is not None:
+            # cast required because mypy doesn't understand the type narrowing
+            base_url = cast("str | httpx.URL", base_url)  # pyright: ignore[reportUnnecessaryCast]
+        elif is_given(environment):
+            if base_url_env and base_url is not None:
+                raise ValueError(
+                    "Ambiguous URL; The `MIRU_BASE_URL` env var and the `environment` argument are given. If you want to use the environment, you must pass base_url=None",
+                )
+
+            try:
+                base_url = ENVIRONMENTS[environment]
+            except KeyError as exc:
+                raise ValueError(f"Unknown environment: {environment}") from exc
+        elif base_url_env is not None:
+            base_url = base_url_env
+        else:
+            self._environment = environment = "production"
+
+            try:
+                base_url = ENVIRONMENTS[environment]
+            except KeyError as exc:
+                raise ValueError(f"Unknown environment: {environment}") from exc
 
         super().__init__(
             version=__version__,
@@ -145,6 +185,7 @@ def copy(
         api_key: str | None = None,
         host: str | None = None,
         version: str | None = None,
+        environment: Literal["production", "staging", "local"] | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = not_given,
         http_client: httpx.Client | None = None,
@@ -182,6 +223,7 @@ def copy(
             host=host or self.host,
             version=version or self.version,
             base_url=base_url or self.base_url,
+            environment=environment or self._environment,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
             http_client=http_client,
             max_retries=max_retries if is_given(max_retries) else self.max_retries,
@@ -242,13 +284,16 @@ class AsyncMiru(AsyncAPIClient):
     host: str
     version: str
 
+    _environment: Literal["production", "staging", "local"] | NotGiven
+
     def __init__(
         self,
         *,
         api_key: str | None = None,
         host: str | None = None,
         version: str | None = None,
-        base_url: str | httpx.URL | None = None,
+        environment: Literal["production", "staging", "local"] | NotGiven = not_given,
+        base_url: str | httpx.URL | None | NotGiven = not_given,
         timeout: float | Timeout | None | NotGiven = not_given,
         max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Mapping[str, str] | None = None,
@@ -290,10 +335,31 @@ def __init__(
             version = os.environ.get("MIRU_SERVER_VERSION") or "v1"
         self.version = version
 
-        if base_url is None:
-            base_url = os.environ.get("MIRU_BASE_URL")
-        if base_url is None:
-            base_url = f"https://{host}/{version}"
+        self._environment = environment
+
+        base_url_env = os.environ.get("MIRU_BASE_URL")
+        if is_given(base_url) and base_url is not None:
+            # cast required because mypy doesn't understand the type narrowing
+            base_url = cast("str | httpx.URL", base_url)  # pyright: ignore[reportUnnecessaryCast]
+        elif is_given(environment):
+            if base_url_env and base_url is not None:
+                raise ValueError(
+                    "Ambiguous URL; The `MIRU_BASE_URL` env var and the `environment` argument are given. If you want to use the environment, you must pass base_url=None",
+                )
+
+            try:
+                base_url = ENVIRONMENTS[environment]
+            except KeyError as exc:
+                raise ValueError(f"Unknown environment: {environment}") from exc
+        elif base_url_env is not None:
+            base_url = base_url_env
+        else:
+            self._environment = environment = "production"
+
+            try:
+                base_url = ENVIRONMENTS[environment]
+            except KeyError as exc:
+                raise ValueError(f"Unknown environment: {environment}") from exc
 
         super().__init__(
             version=__version__,
@@ -340,6 +406,7 @@ def copy(
         api_key: str | None = None,
         host: str | None = None,
         version: str | None = None,
+        environment: Literal["production", "staging", "local"] | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = not_given,
         http_client: httpx.AsyncClient | None = None,
@@ -377,6 +444,7 @@ def copy(
             host=host or self.host,
             version=version or self.version,
             base_url=base_url or self.base_url,
+            environment=environment or self._environment,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
             http_client=http_client,
             max_retries=max_retries if is_given(max_retries) else self.max_retries,

tests/test_client.py

@@ -552,6 +552,14 @@ def test_base_url_env(self) -> None:
             client = Miru(api_key=api_key, _strict_response_validation=True)
             assert client.base_url == "http://localhost:5000/from/env/"
 
+        # explicit environment arg requires explicitness
+        with update_env(MIRU_BASE_URL="http://localhost:5000/from/env"):
+            with pytest.raises(ValueError, match=r"you must pass base_url=None"):
+                Miru(api_key=api_key, _strict_response_validation=True, environment="production")
+
+            client = Miru(base_url=None, api_key=api_key, _strict_response_validation=True, environment="production")
+            assert str(client.base_url).startswith("https://configs.api.miruml.com/v1")
+
     @pytest.mark.parametrize(
         "client",
         [
@@ -1355,6 +1363,16 @@ def test_base_url_env(self) -> None:
             client = AsyncMiru(api_key=api_key, _strict_response_validation=True)
             assert client.base_url == "http://localhost:5000/from/env/"
 
+        # explicit environment arg requires explicitness
+        with update_env(MIRU_BASE_URL="http://localhost:5000/from/env"):
+            with pytest.raises(ValueError, match=r"you must pass base_url=None"):
+                AsyncMiru(api_key=api_key, _strict_response_validation=True, environment="production")
+
+            client = AsyncMiru(
+                base_url=None, api_key=api_key, _strict_response_validation=True, environment="production"
+            )
+            assert str(client.base_url).startswith("https://configs.api.miruml.com/v1")
+
     @pytest.mark.parametrize(
         "client",
         [