Merge pull request #29 from Not-Diamond/release-please--branches--main--changes--next

dragos199993 · web-flow · commit af9df92b8b56 · 2025-12-09T20:40:10.000+02:00
release: 1.0.1
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "1.0.0"
+  ".": "1.0.1"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.0.1 (2025-12-09)
+
+Full Changelog: [v1.0.0...v1.0.1](https://github.com/Not-Diamond/not-diamond-python/compare/v1.0.0...v1.0.1)
+
+### Bug Fixes
+
+* **types:** allow pyright to infer TypedDict types within SequenceNotStr ([5663881](https://github.com/Not-Diamond/not-diamond-python/commit/566388145d7d3fea2e52158963fc2ad8e8ee45c8))
+
+
+### Chores
+
+* add missing docstrings ([003db35](https://github.com/Not-Diamond/not-diamond-python/commit/003db35899fda442fd45bdcafe4aeaad09b1dd4d))
+
 ## 1.0.0 (2025-12-08)
 
 Full Changelog: [v1.0.0-rc18...v1.0.0](https://github.com/Not-Diamond/not-diamond-python/compare/v1.0.0-rc18...v1.0.0)
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "notdiamond"
-version = "1.0.0"
+version = "1.0.1"
 description = "The official Python library for the notdiamond API"
 dynamic = ["readme"]
 license = "Apache-2.0"
diff --git a/src/notdiamond/_types.py b/src/notdiamond/_types.py
@@ -243,6 +243,9 @@ class HttpxSendArgs(TypedDict, total=False):
 if TYPE_CHECKING:
     # This works because str.__contains__ does not accept object (either in typeshed or at runtime)
     # https://github.com/hauntsaninja/useful_types/blob/5e9710f3875107d068e7679fd7fec9cfab0eff3b/useful_types/__init__.py#L285
+    #
+    # Note: index() and count() methods are intentionally omitted to allow pyright to properly
+    # infer TypedDict types when dict literals are used in lists assigned to SequenceNotStr.
     class SequenceNotStr(Protocol[_T_co]):
         @overload
         def __getitem__(self, index: SupportsIndex, /) -> _T_co: ...
@@ -251,8 +254,6 @@ def __getitem__(self, index: slice, /) -> Sequence[_T_co]: ...
         def __contains__(self, value: object, /) -> bool: ...
         def __len__(self) -> int: ...
         def __iter__(self) -> Iterator[_T_co]: ...
-        def index(self, value: Any, start: int = 0, stop: int = ..., /) -> int: ...
-        def count(self, value: Any, /) -> int: ...
         def __reversed__(self) -> Iterator[_T_co]: ...
 else:
     # just point this to a normal `Sequence` at runtime to avoid having to special case
diff --git a/src/notdiamond/_version.py b/src/notdiamond/_version.py
@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "notdiamond"
-__version__ = "1.0.0"  # x-release-please-version
+__version__ = "1.0.1"  # x-release-please-version
diff --git a/src/notdiamond/types/custom_router_train_custom_router_response.py b/src/notdiamond/types/custom_router_train_custom_router_response.py
@@ -6,6 +6,24 @@
 
 
 class CustomRouterTrainCustomRouterResponse(BaseModel):
+    """Response model for POST /v2/pzn/trainCustomRouter endpoint.
+
+    Returned immediately after submitting a custom router training request. The training
+    process runs asynchronously (typically 5-15 minutes), so use the returned preference_id
+    to make routing calls once training completes.
+
+    **Next steps:**
+    1. Store the preference_id
+    2. Wait for training to complete (typically 5-15 minutes)
+    3. Use this preference_id in POST /v2/modelRouter/modelSelect requests
+    4. The router will use your custom-trained model to make routing decisions
+
+    **How to use the preference_id:**
+    - Include it in the 'preference_id' field of model_select() calls
+    - The system automatically uses your custom router once training is complete
+    - No need to poll status - you can start using it immediately (will use default until ready)
+    """
+
     preference_id: str
     """Unique identifier for the custom router.
 
diff --git a/src/notdiamond/types/golden_record_param.py b/src/notdiamond/types/golden_record_param.py
@@ -9,6 +9,8 @@
 
 
 class GoldenRecordParam(TypedDict, total=False):
+    """A training or test example for prompt adaptation."""
+
     fields: Required[Dict[str, str]]
     """Dictionary mapping field names to their values.
 
diff --git a/src/notdiamond/types/model.py b/src/notdiamond/types/model.py
@@ -8,6 +8,12 @@
 
 
 class Model(BaseModel):
+    """Response model for a single LLM model from GET /v2/models endpoint.
+
+    Contains metadata about a supported text generation model including pricing,
+    context limits, and availability information.
+    """
+
     context_length: int
     """Maximum context window size in tokens"""
 
diff --git a/src/notdiamond/types/model_list_response.py b/src/notdiamond/types/model_list_response.py
@@ -9,6 +9,12 @@
 
 
 class ModelListResponse(BaseModel):
+    """Response model for GET /v2/models endpoint.
+
+    Returns a list of all supported text generation models with their metadata,
+    separated into active and deprecated models.
+    """
+
     deprecated_models: List[Model]
     """List of deprecated models that are no longer recommended but may still work"""
 
diff --git a/src/notdiamond/types/model_router_select_model_params.py b/src/notdiamond/types/model_router_select_model_params.py
@@ -58,6 +58,19 @@ class ModelRouterSelectModelParams(TypedDict, total=False):
 
 
 class LlmProviderOpenRouterProvider(TypedDict, total=False):
+    """Model for specifying an LLM provider using OpenRouter format.
+
+    Used in model routing requests when you want to specify providers using the
+    OpenRouter naming convention (combined 'provider/model' format). This is an
+    alternative to the standard RequestProvider which uses separate provider and
+    model fields.
+
+    **When to use:**
+    - When working with OpenRouter-compatible systems
+    - When you prefer the unified 'provider/model' format
+    - For models accessed via OpenRouter proxy
+    """
+
     model: Required[str]
     """
     OpenRouter model identifier in 'provider/model' format (e.g., 'openai/gpt-4o',
diff --git a/src/notdiamond/types/model_router_select_model_response.py b/src/notdiamond/types/model_router_select_model_response.py
@@ -8,6 +8,13 @@
 
 
 class Provider(BaseModel):
+    """Selected LLM provider information from model selection endpoints.
+
+    Part of ModelSelectResponse. Contains the provider and model that Not Diamond's
+    routing algorithm selected as optimal for your query. Use these values to make
+    your LLM API call to the recommended model.
+    """
+
     model: str
     """
     Model identifier for the selected model (e.g., 'gpt-4o',
@@ -19,6 +26,8 @@ class Provider(BaseModel):
 
 
 class ModelRouterSelectModelResponse(BaseModel):
+    """Response from model selection endpoint."""
+
     providers: List[Provider]
     """List containing the selected provider"""
 
diff --git a/src/notdiamond/types/preference_create_response.py b/src/notdiamond/types/preference_create_response.py
@@ -6,6 +6,18 @@
 
 
 class PreferenceCreateResponse(BaseModel):
+    """Response model for POST /v2/preferences/userPreferenceCreate endpoint.
+
+    Returns the newly created preference ID which can be used to enable personalized
+    LLM routing. Store this ID and include it in subsequent model_select() calls to
+    activate personalized routing based on your feedback and usage patterns.
+
+    **Next steps after creation:**
+    1. Use the preference_id in POST /v2/modelRouter/modelSelect requests
+    2. Submit feedback on routing decisions to improve accuracy
+    3. Optionally train a custom router using your evaluation data
+    """
+
     preference_id: str
     """Unique identifier for the newly created preference.
 
diff --git a/src/notdiamond/types/prompt_adaptation_adapt_response.py b/src/notdiamond/types/prompt_adaptation_adapt_response.py
@@ -6,6 +6,19 @@
 
 
 class PromptAdaptationAdaptResponse(BaseModel):
+    """Response model for POST /v2/prompt/adapt endpoint.
+
+    Returned immediately after submitting a prompt adaptation request. The adaptation
+    process runs asynchronously, so use the returned adaptation_run_id to track progress
+    and retrieve results when complete.
+
+    **Next steps:**
+    1. Store the adaptation_run_id
+    2. Poll GET /v2/prompt/adaptStatus/{adaptation_run_id} to check progress
+    3. When status is 'completed', retrieve optimized prompts from GET /v2/prompt/adaptResults/{adaptation_run_id}
+    4. Use the optimized prompts with your target models
+    """
+
     adaptation_run_id: str
     """Unique identifier for this adaptation run.
 
diff --git a/src/notdiamond/types/prompt_adaptation_get_adapt_results_response.py b/src/notdiamond/types/prompt_adaptation_get_adapt_results_response.py
@@ -12,6 +12,25 @@
 
 
 class TargetModel(BaseModel):
+    """Optimized prompt results for a single target model in prompt adaptation.
+
+    Part of AdaptationRunResultsResponse. Contains the optimized system prompt and
+    user message template for a specific target model, along with performance scores
+    before and after optimization. Use these optimized prompts with the target model
+    to achieve better performance than the original prompt.
+
+    **Key metrics:**
+    - **pre_optimization_score**: Performance with original prompt on this target model
+    - **post_optimization_score**: Performance with optimized prompt on this target model
+    - **Score improvement**: post - pre shows how much optimization helped
+
+    **Usage:**
+    1. Extract the optimized system_prompt and user_message_template
+    2. Replace placeholders in user_message_template using fields from your data
+    3. Use these prompts when calling this target model
+    4. Compare pre/post scores to see improvement gained
+    """
+
     cost: Optional[float] = None
 
     api_model_name: str = FieldInfo(alias="model_name")
@@ -60,6 +79,19 @@ class TargetModel(BaseModel):
 
 
 class OriginModel(BaseModel):
+    """Baseline results for the origin model in prompt adaptation.
+
+    Part of AdaptationRunResultsResponse. Contains the performance metrics and prompt
+    configuration for your original prompt on the origin model. This serves as the
+    baseline to compare against optimized prompts for target models.
+
+    **Fields include:**
+    - Original system prompt and user message template
+    - Baseline performance score and evaluation metrics
+    - Cost of running the baseline evaluation
+    - Job status for the origin model evaluation
+    """
+
     cost: Optional[float] = None
 
     evals: Optional[Dict[str, object]] = None
@@ -90,6 +122,18 @@ class OriginModel(BaseModel):
 
 
 class PromptAdaptationGetAdaptResultsResponse(BaseModel):
+    """Response model for GET /v2/prompt/adaptResults/{adaptation_run_id} endpoint.
+
+    Contains the complete results of a prompt adaptation run, including optimized prompts
+    and evaluation metrics for all target models. Use this to retrieve your adapted prompts
+    after the adaptation status is 'completed'.
+
+    The response includes:
+    - Baseline performance of your original prompt on the origin model
+    - Optimized prompts for each target model with pre/post optimization scores
+    - Evaluation metrics and cost information for each model
+    """
+
     id: str
     """Unique ID for this adaptation run"""
 
diff --git a/src/notdiamond/types/prompt_adaptation_get_adapt_status_response.py b/src/notdiamond/types/prompt_adaptation_get_adapt_status_response.py
@@ -9,6 +9,25 @@
 
 
 class PromptAdaptationGetAdaptStatusResponse(BaseModel):
+    """Response model for GET /v2/prompt/adaptStatus/{adaptation_run_id} endpoint.
+
+    Returns the current status of an asynchronous prompt adaptation job. Poll this
+    endpoint periodically to track progress. When status is 'completed', you can
+    retrieve the optimized prompts using the /adaptResults endpoint.
+
+    **Status values:**
+    - **created**: Job has been initialized
+    - **queued**: Waiting in queue (check queue_position for your place in line)
+    - **processing**: Currently running optimization
+    - **completed**: Finished successfully, results available via /adaptResults
+    - **failed**: Encountered an error during processing
+
+    **Polling recommendations:**
+    - Poll every 30-60 seconds while status is incomplete
+    - Stop polling once status is 'completed' or 'failed'
+    - Adaptation typically takes 10-30 minutes total
+    """
+
     adaptation_run_id: str
     """Unique identifier for this adaptation run.
 
diff --git a/src/notdiamond/types/prompt_adaptation_get_cost_response.py b/src/notdiamond/types/prompt_adaptation_get_cost_response.py
@@ -8,6 +8,12 @@
 
 
 class UsageRecord(BaseModel):
+    """Individual LLM usage record with token counts and cost breakdown.
+
+    Returned by GET /llm-usage endpoint and included in AdaptationRunCostResponse.
+    Each record represents a single LLM API call with detailed usage metrics.
+    """
+
     id: str
     """Unique identifier for this usage record"""
 
@@ -52,6 +58,12 @@ class UsageRecord(BaseModel):
 
 
 class PromptAdaptationGetCostResponse(BaseModel):
+    """Response model for GET /v2/prompt/adapt/{adaptation_run_id}/costs endpoint.
+
+    Contains the total LLM costs and detailed usage records for a prompt adaptation run.
+    Use this to track costs associated with optimizing prompts for different target models.
+    """
+
     adaptation_run_id: str
     """Unique identifier for the adaptation run"""
 
diff --git a/src/notdiamond/types/request_provider_param.py b/src/notdiamond/types/request_provider_param.py
@@ -9,6 +9,8 @@
 
 
 class RequestProviderParam(TypedDict, total=False):
+    """Model for specifying an LLM provider in API requests."""
+
     model: Required[str]
     """Model name (e.g., 'gpt-4o', 'claude-sonnet-4-5-20250929')"""
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- ".": "1.0.0"`
	`2`	`+ ".": "1.0.1"`
`3`	`3`	`}`