callable-ai 0.1.5__tar.gz

callable_ai-0.1.5/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.3
+Name: callable-ai
+Version: 0.1.5
+Summary: Callable-first AI response and tool harness
+Author: Mittal Analytics Pvt Ltd
+Requires-Dist: openai>=2.38,<3
+Requires-Dist: pydantic>=2.12,<3
+Requires-Python: >=3.12
+Project-URL: Source, https://github.com/Mittal-Analytics/mittal-ai
+Project-URL: Issues, https://github.com/Mittal-Analytics/mittal-ai/issues
+Project-URL: Changelog, https://github.com/Mittal-Analytics/mittal-ai/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# callable-ai
+
+A callable-first AI harness from Mittal Analytics. Install it as `callable-ai`
+and import it as `callable_ai`. It provides:
+
+- streaming, non-streaming and structured LLM responses;
+- tool-call handling, reusable tool helpers and message-history repair;
+- token-cost calculation;
+- OpenRouter routing and provider preferences;
+- compatibility fixes for Chinese models; and
+- `dj-evals` events for model requests and tool calls.
+
+The application keeps its API keys. The model declares which provider and base URL
+the harness should use:
+
+```python
+from callable_ai import AIModel, get_client, get_structured_response
+from pydantic import BaseModel
+
+
+class Summary(BaseModel):
+    text: str
+
+
+model = AIModel(
+    name="openai/gpt-5.4",
+    api_key="...",
+    provider="openrouter",
+    base_url="https://openrouter.ai/api/v1",
+    input_tokens_cost_usd=2.5,
+    input_tokens_cached_cost_usd=0.25,
+    output_tokens_cost_usd=15,
+    output_tokens_reasoning_cost_usd=15,
+)
+
+async with get_client(model) as client:
+    async for event in get_structured_response(
+        client=client,
+        ai_model=model,
+        input=[{"role": "user", "content": "Summarise this."}],
+        tools=[],
+        text_format=Summary,
+        reasoning_effort="low",
+    ):
+        print(event)
+```
+
+The main public entry points are `get_response`, `get_streaming_response` and
+`get_structured_response`.
+
+## Tool helpers
+
+Use `format_docstring` to customize a reusable tool description and
+`partial_with_doc` to bind arguments that should not be exposed to the model:
+
+```python
+from callable_ai import (
+    ToolCallResult,
+    format_docstring,
+    get_streaming_response,
+    partial_with_doc,
+)
+
+
+@format_docstring(entity="company")
+def answer_question(_company_id: int, question: str) -> ToolCallResult:
+    """Answer a question about a {entity}.
+
+    Args:
+        - question: Question asked by the user.
+    """
+    return {"content": f"{_company_id}: {question}"}
+
+
+company_tool = partial_with_doc(answer_question, _company_id=123)
+
+async for event in get_streaming_response(
+    user="user-123",
+    ai_model=model,
+    messages=[{"role": "user", "content": "What changed?"}],
+    tools=[company_tool],
+    reasoning_effort="low",
+):
+    print(event)
+```
+
+`company_tool` exposes only `question`; its bound company ID stays private. Tools
+return `ToolCallResult`; async generators may yield `EvalEvent` updates first.
+
+## Publishing a new version
+
+The [release workflow](.github/workflows/release.yml) publishes version tags to
+PyPI using trusted publishing. Configure `callable-ai` as a trusted publisher on
+PyPI before its first release. From a clean working tree, publish the next patch
+release with:
+
+```bash
+uv version --bump patch
+version=$(uv version --short)
+
+uv run pytest
+uv run pre-commit run --all-files
+
+git add pyproject.toml uv.lock
+git commit -m "Release version $version"
+git tag -a "v$version" -m "v$version"
+git push origin main "v$version"
+```
+
+The tag must match the version in `pyproject.toml`, with a `v` prefix. Use
+`--bump minor` or `--bump major` when appropriate. PyPI versions are immutable,
+so every release needs a new version.

callable_ai-0.1.5/README.md

@@ -0,0 +1,112 @@
+# callable-ai
+
+A callable-first AI harness from Mittal Analytics. Install it as `callable-ai`
+and import it as `callable_ai`. It provides:
+
+- streaming, non-streaming and structured LLM responses;
+- tool-call handling, reusable tool helpers and message-history repair;
+- token-cost calculation;
+- OpenRouter routing and provider preferences;
+- compatibility fixes for Chinese models; and
+- `dj-evals` events for model requests and tool calls.
+
+The application keeps its API keys. The model declares which provider and base URL
+the harness should use:
+
+```python
+from callable_ai import AIModel, get_client, get_structured_response
+from pydantic import BaseModel
+
+
+class Summary(BaseModel):
+    text: str
+
+
+model = AIModel(
+    name="openai/gpt-5.4",
+    api_key="...",
+    provider="openrouter",
+    base_url="https://openrouter.ai/api/v1",
+    input_tokens_cost_usd=2.5,
+    input_tokens_cached_cost_usd=0.25,
+    output_tokens_cost_usd=15,
+    output_tokens_reasoning_cost_usd=15,
+)
+
+async with get_client(model) as client:
+    async for event in get_structured_response(
+        client=client,
+        ai_model=model,
+        input=[{"role": "user", "content": "Summarise this."}],
+        tools=[],
+        text_format=Summary,
+        reasoning_effort="low",
+    ):
+        print(event)
+```
+
+The main public entry points are `get_response`, `get_streaming_response` and
+`get_structured_response`.
+
+## Tool helpers
+
+Use `format_docstring` to customize a reusable tool description and
+`partial_with_doc` to bind arguments that should not be exposed to the model:
+
+```python
+from callable_ai import (
+    ToolCallResult,
+    format_docstring,
+    get_streaming_response,
+    partial_with_doc,
+)
+
+
+@format_docstring(entity="company")
+def answer_question(_company_id: int, question: str) -> ToolCallResult:
+    """Answer a question about a {entity}.
+
+    Args:
+        - question: Question asked by the user.
+    """
+    return {"content": f"{_company_id}: {question}"}
+
+
+company_tool = partial_with_doc(answer_question, _company_id=123)
+
+async for event in get_streaming_response(
+    user="user-123",
+    ai_model=model,
+    messages=[{"role": "user", "content": "What changed?"}],
+    tools=[company_tool],
+    reasoning_effort="low",
+):
+    print(event)
+```
+
+`company_tool` exposes only `question`; its bound company ID stays private. Tools
+return `ToolCallResult`; async generators may yield `EvalEvent` updates first.
+
+## Publishing a new version
+
+The [release workflow](.github/workflows/release.yml) publishes version tags to
+PyPI using trusted publishing. Configure `callable-ai` as a trusted publisher on
+PyPI before its first release. From a clean working tree, publish the next patch
+release with:
+
+```bash
+uv version --bump patch
+version=$(uv version --short)
+
+uv run pytest
+uv run pre-commit run --all-files
+
+git add pyproject.toml uv.lock
+git commit -m "Release version $version"
+git tag -a "v$version" -m "v$version"
+git push origin main "v$version"
+```
+
+The tag must match the version in `pyproject.toml`, with a `v` prefix. Use
+`--bump minor` or `--bump major` when appropriate. PyPI versions are immutable,
+so every release needs a new version.

callable_ai-0.1.5/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "callable-ai"
+version = "0.1.5"
+description = "Callable-first AI response and tool harness"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "openai>=2.38,<3",
+    "pydantic>=2.12,<3",
+]
+
+[[project.authors]]
+name = "Mittal Analytics Pvt Ltd"
+
+[project.urls]
+Source = "https://github.com/Mittal-Analytics/mittal-ai"
+Issues = "https://github.com/Mittal-Analytics/mittal-ai/issues"
+Changelog = "https://github.com/Mittal-Analytics/mittal-ai/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "callable_ai"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+]
+ignore = ["E501"]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.2",
+    "pytest",
+    "pytest-asyncio",
+]

callable_ai-0.1.5/pyproject.toml.orig

@@ -0,0 +1,41 @@
+[project]
+name = "callable-ai"
+version = "0.1.5"
+description = "Callable-first AI response and tool harness"
+readme = "README.md"
+authors = [{ name = "Mittal Analytics Pvt Ltd" }]
+requires-python = ">=3.12"
+dependencies = [
+    "openai>=2.38,<3",
+    "pydantic>=2.12,<3",
+]
+
+[project.urls]
+Source = "https://github.com/Mittal-Analytics/mittal-ai"
+Issues = "https://github.com/Mittal-Analytics/mittal-ai/issues"
+Changelog = "https://github.com/Mittal-Analytics/mittal-ai/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "callable_ai"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.2",
+    "pytest",
+    "pytest-asyncio",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]

callable_ai-0.1.5/src/callable_ai/__init__.py

@@ -0,0 +1,41 @@
+from callable_ai.costing import get_abs_cost, parse_responses_usage
+from callable_ai.models import AIModel
+from callable_ai.responses import (
+    AnnotationToolCallURL,
+    EvalEvent,
+    Messages,
+    StreamingResponseChunk,
+    ToolCallResult,
+    ToolFunction,
+    UsageDetails,
+    gen_error,
+    get_client,
+    get_model_options,
+    get_response,
+    get_streaming_response,
+    get_structured_response,
+    repair_message_history,
+)
+from callable_ai.tools import format_docstring, partial_with_doc
+
+__all__ = [
+    "AIModel",
+    "AnnotationToolCallURL",
+    "EvalEvent",
+    "Messages",
+    "StreamingResponseChunk",
+    "ToolCallResult",
+    "ToolFunction",
+    "UsageDetails",
+    "format_docstring",
+    "gen_error",
+    "get_abs_cost",
+    "get_client",
+    "get_model_options",
+    "get_response",
+    "get_streaming_response",
+    "get_structured_response",
+    "parse_responses_usage",
+    "partial_with_doc",
+    "repair_message_history",
+]

callable_ai-0.1.5/src/callable_ai/compatibility.py

@@ -0,0 +1,86 @@
+import json
+from typing import TypeVar
+
+from openai.types.responses import ParsedResponse, Response, ResponseInputParam
+from openai.types.responses.parsed_response import (
+    ParsedResponseOutputMessage,
+    ParsedResponseOutputText,
+)
+from pydantic import BaseModel
+
+from callable_ai.models import AIModel
+
+# Keeps the parsed response type tied to the Pydantic schema passed in.
+PydanticModel = TypeVar("PydanticModel", bound=BaseModel)
+
+
+def supports_structured_output_with_tools(ai_model: AIModel) -> bool:
+    name = ai_model.name.lower()
+    if any(model in name for model in ["deepseek", "minimax"]):
+        return False
+    if "/" not in name:
+        return True
+    return any(model in name for model in ["gemini", "gpt", "grok"])
+
+
+def add_json_schema_to_input(input: ResponseInputParam, text_format: type[BaseModel]):
+    schema = json.dumps(text_format.model_json_schema(), indent=2)
+    input.append(
+        {
+            # User role is widely supported by OpenAI-compatible providers.
+            "role": "user",
+            "content": "Return only valid JSON matching this schema:"
+            f"\n```json\n{schema}\n```",
+        }
+    )
+
+
+def parse_response_text(
+    response: Response, text_format: type[PydanticModel]
+) -> ParsedResponse[PydanticModel]:
+    """Build ParsedResponse for providers that return JSON as plain text."""
+    parsed = text_format.model_validate_json(get_json_text(response.output_text))
+
+    # ParsedResponse.output_parsed reads this `parsed` field internally.
+    parsed_text = ParsedResponseOutputText[PydanticModel](
+        annotations=[],
+        text=response.output_text,
+        type="output_text",
+        parsed=parsed,
+    )
+
+    # Keep the same shape as OpenAI's parsed message response.
+    parsed_message = ParsedResponseOutputMessage[PydanticModel](
+        id=response.id,
+        content=[parsed_text],
+        role="assistant",
+        status="completed",
+        type="message",
+    )
+
+    # Reuse all original response fields but replace output with parsed output.
+    data = response.model_dump()
+    data["output"] = [parsed_message]
+    return ParsedResponse[PydanticModel].model_construct(**data)
+
+
+def get_json_text(text: str) -> str:
+    text = text.strip()
+    if "```" in text:
+        for block in text.split("```"):
+            block = block.strip()
+            if block.lower().startswith("json"):
+                return block[4:].strip()
+            if block.startswith(("{", "[")):
+                return block
+
+    object_start = text.find("{")
+    object_end = text.rfind("}")
+    if object_start >= 0 and object_end >= object_start:
+        return text[object_start : object_end + 1]
+
+    array_start = text.find("[")
+    array_end = text.rfind("]")
+    if array_start >= 0 and array_end >= array_start:
+        return text[array_start : array_end + 1]
+    return text

callable_ai-0.1.5/src/callable_ai/costing.py

@@ -0,0 +1,68 @@
+from openai.types.responses.response_usage import ResponseUsage
+
+from callable_ai.models import AIModel
+from callable_ai.openrouter import OpenRouterCompletionUsage
+
+
+def parse_responses_usage(responses_usage: ResponseUsage) -> OpenRouterCompletionUsage:
+    """
+    Convert OpenAI Responses API usage format to OpenRouter completion usage format.
+    """
+    openrouter_usage: OpenRouterCompletionUsage = {
+        "prompt_tokens": responses_usage.input_tokens,
+        "prompt_tokens_details": {
+            "cached_tokens": getattr(
+                responses_usage.input_tokens_details, "cached_tokens", 0
+            )
+            or 0
+        },
+        "completion_tokens": responses_usage.output_tokens,
+        "completion_tokens_details": {
+            "reasoning_tokens": getattr(
+                responses_usage.output_tokens_details, "reasoning_tokens", 0
+            )
+            or 0
+        },
+        "total_tokens": responses_usage.total_tokens,
+    }
+    return openrouter_usage
+
+
+def get_abs_cost(
+    usage: OpenRouterCompletionUsage,
+    ai_model: AIModel,
+    *,
+    number_of_web_searches=0,
+) -> float:
+    # https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat-streaming/streaming-usage
+    input_tokens = usage["prompt_tokens"]
+    prompt_details = usage.get("prompt_tokens_details") or {}
+    input_tokens_cached = prompt_details.get("cached_tokens") or 0
+    output_tokens = usage["completion_tokens"]
+    completion_details = usage.get("completion_tokens_details") or {}
+    output_tokens_reasoning = completion_details.get("reasoning_tokens") or 0
+
+    input_fresh_tokens = input_tokens - input_tokens_cached
+    output_answer_tokens = output_tokens - output_tokens_reasoning
+
+    if ai_model.lower_token_count_cost:
+        cutoff, lower_token_ai_model = ai_model.lower_token_count_cost
+        if input_tokens <= cutoff:
+            ai_model = lower_token_ai_model
+
+    if number_of_web_searches:
+        web_search_cost = number_of_web_searches * ai_model.web_search_cost_inr / 1000
+    else:
+        web_search_cost = 0
+
+    # Calculate cost in INR/per million tokens
+    cost = (
+        (
+            input_fresh_tokens * ai_model.input_tokens_cost_inr
+            + output_answer_tokens * ai_model.output_tokens_cost_inr
+            + input_tokens_cached * ai_model.input_tokens_cached_cost_inr
+            + output_tokens_reasoning * ai_model.output_tokens_reasoning_cost_inr
+        )
+        / 1_000_000
+    ) + web_search_cost
+    return abs(cost)

callable_ai-0.1.5/src/callable_ai/models.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass, field
+
+USD_TO_INR_RATE = 110
+
+
+@dataclass
+class AIModel:
+    name: str
+    api_key: str = field(repr=False, compare=False)
+
+    input_tokens_cost_usd: float
+    input_tokens_cached_cost_usd: float
+    output_tokens_cost_usd: float
+    output_tokens_reasoning_cost_usd: float
+
+    provider: str = "openai"
+    base_url: str | None = None
+    extra_headers: dict[str, str] | None = field(default=None, repr=False)
+    web_search_cost_usd: float | None = None
+    lower_token_count_cost: tuple[int, "AIModel"] | None = None
+    openrouter_providers: list[str] | None = None
+    usd_to_inr_rate: float = USD_TO_INR_RATE
+
+    @property
+    def web_search_cost_inr(self) -> float | None:
+        return (
+            self.usd_to_inr_rate * self.web_search_cost_usd
+            if self.web_search_cost_usd is not None
+            else None
+        )
+
+    @property
+    def input_tokens_cost_inr(self) -> float:
+        return self.usd_to_inr_rate * self.input_tokens_cost_usd
+
+    @property
+    def input_tokens_cached_cost_inr(self) -> float:
+        return self.usd_to_inr_rate * self.input_tokens_cached_cost_usd
+
+    @property
+    def output_tokens_cost_inr(self) -> float:
+        return self.usd_to_inr_rate * self.output_tokens_cost_usd
+
+    @property
+    def output_tokens_reasoning_cost_inr(self) -> float:
+        return self.usd_to_inr_rate * self.output_tokens_reasoning_cost_usd

callable_ai-0.1.5/src/callable_ai/openrouter.py

@@ -0,0 +1,94 @@
+from typing import List, Literal, NotRequired, Optional, TypeAlias, TypedDict, Union
+
+from openai.types.chat import ChatCompletionChunk
+from openai.types.chat.chat_completion import Choice
+from openai.types.chat.chat_completion_chunk import ChoiceDelta
+
+
+class ReasoningDetailBase(TypedDict):
+    id: Optional[str]
+    format: Literal["unknown", "openai-responses-v1", "anthropic-claude-v1"]
+    index: Optional[int]
+
+
+class ReasoningDetailSummaryType(ReasoningDetailBase):
+    type: Literal["reasoning.summary"]
+    summary: str
+
+
+class ReasoningDetailEncryptedType(ReasoningDetailBase):
+    type: Literal["reasoning.encrypted"]
+    data: str
+
+
+class ReasoningDetailTextType(ReasoningDetailBase):
+    type: Literal["reasoning.text"]
+    text: str
+    signature: NotRequired[Optional[str]]
+
+
+OpenRouterReasoningDetail: TypeAlias = Union[
+    ReasoningDetailSummaryType,
+    ReasoningDetailEncryptedType,
+    ReasoningDetailTextType,
+]
+
+
+class OpenRouterDelta(ChoiceDelta):
+    # ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None, reasoning='**Explain', reasoning_details=[{'type': 'reasoning.summary', 'summary': '**Explain', 'format': 'openai-responses-v1', 'index': 0}])
+    reasoning_details: Optional[List[OpenRouterReasoningDetail]]
+
+
+class OpenRouterChoice(Choice):
+    delta: OpenRouterDelta
+
+
+class OpenRouterChatCompletionChunk(ChatCompletionChunk):
+    choices: List[OpenRouterChoice]
+
+
+class OpenRouterCompletionTokensDetails(TypedDict, total=False):
+    accepted_prediction_tokens: Optional[int]
+    """
+    When using Predicted Outputs, the number of tokens in the prediction that
+    appeared in the completion.
+    """
+
+    audio_tokens: Optional[int]
+    """Audio input tokens generated by the model."""
+
+    reasoning_tokens: Optional[int]
+    """Tokens generated by the model for reasoning."""
+
+    rejected_prediction_tokens: Optional[int]
+    """
+    When using Predicted Outputs, the number of tokens in the prediction that did
+    not appear in the completion. However, like reasoning tokens, these tokens are
+    still counted in the total completion tokens for purposes of billing, output,
+    and context window limits.
+    """
+
+
+class OpenRouterPromptTokensDetails(TypedDict, total=False):
+    audio_tokens: Optional[int]
+    """Audio input tokens present in the prompt."""
+
+    cached_tokens: Optional[int]
+    """Cached tokens present in the prompt."""
+
+
+class OpenRouterCompletionUsage(TypedDict):
+    completion_tokens: int
+    """Number of tokens in the generated completion."""
+
+    prompt_tokens: int
+    """Number of tokens in the prompt."""
+
+    total_tokens: int
+    """Total number of tokens used in the request (prompt + completion)."""
+
+    completion_tokens_details: NotRequired[Optional[OpenRouterCompletionTokensDetails]]
+    """Breakdown of tokens used in a completion."""
+
+    prompt_tokens_details: NotRequired[Optional[OpenRouterPromptTokensDetails]]
+    """Breakdown of tokens used in the prompt."""