Skip to main content

kedi-typesafe

Framework-native integrations for using TypeSafe AI's Jev models with Kedi's supported agent frameworks. Core Jev schema translation and the Pydantic AI and LangChain integrations ship as one kedi-typesafe package.

This package now lives in the kedi-decisions monorepo. The public kedi_typesafe imports and Jev SDK behavior remain supported. Shared schema interpretation lives in kedi-decisions; local Laya inference lives in the separate kedi-laya package, not here. Version 0.3.0 is a local development version until published.

Pydantic AI

Install the package and provide TYPESAFE_API_KEY in your environment:

pip install kedi-typesafe
export TYPESAFE_API_KEY="your-key"
from typing import Literal

from pydantic import BaseModel, Field
from pydantic_ai import Agent

from kedi_typesafe.integrations.pydantic import TypeSafeModel


class Triage(BaseModel):
    urgent: bool = Field(description="The request needs action today")
    route: Literal["billing", "support", "other"] = Field(
        description="Which team should handle the request?"
    )


model = TypeSafeModel("jev-latest")
agent = Agent(model, output_type=Triage)
result = agent.run_sync("I was charged twice. Please fix this today.")
print(result.output)

The surface supports booleans, finite string Literal/Enum values, constrained text extraction, and nested Pydantic models composed of supported fields. Pydantic's native EmailStr and pydantic-extra-types PhoneNumber schemas are recognized automatically. A JSON Schema pattern is treated as a regex candidate extractor; other string fields can provide an explicit field extractor:

Install kedi-typesafe[email], kedi-typesafe[phone], or kedi-typesafe[all] when those optional Pydantic field types are used.

from kedi_typesafe import RegexExtractor
from kedi_typesafe.integrations.pydantic import TypeSafeModel

model = TypeSafeModel(
    text_extractors={"ticket_id": RegexExtractor(pattern=r"CASE-\d+")},
)

Candidate extraction is deterministic and Jev only selects among values found in state, following TypeSafe's pre-parsed extraction pattern. Jev is not a free-form text-generation model, so unconstrained strings, arbitrary numeric extraction, recursive schemas, media, and omitted/defaulted fields are rejected before a provider request is made. Nullable choices and extraction are supported: no-match is an explicit option, not a confidence cutoff. Missing candidates resolve locally to None only for nullable extraction. Provider failures remain exceptions.

Boolean answers use Jev's Noul probability and a configurable threshold. The default decision is strictly probability > 0.85; equality is false. Pass threshold=... to either model constructor, or typesafe_threshold per request to override it without mutating the model. This is a decision policy, not a guarantee of 85% empirical accuracy. Version 0.2 changes the legacy default of 0.5.

agent = Agent(TypeSafeModel(threshold=0.9), output_type=Triage)
result = agent.run_sync("Please refund the duplicate charge", model_settings={"typesafe_threshold": 0.95})

Custom Endpoints

Both TypeSafeModel and TypeSafeChatModel accept base_url=. Alternatively, set TYPESAFE_BASE_URL; an explicit constructor value takes precedence. Use the HTTPS server origin, not /v1/systemone: the SDK adds that route. Leave the setting unset to use the public TypeSafe service.

import os

from kedi_typesafe import TypeSafeModel

model = TypeSafeModel(
    "jev-latest",
    api_key=os.environ["TYPESAFE_API_KEY"],
    base_url=os.environ["TYPESAFE_BASE_URL"],
)

Custom-endpoint errors never trigger a fallback to the public endpoint. Keep keys in the environment, not in source files or benchmark assets. The SDK integrations target TypeSafe SDK 0.7.2 and Pydantic AI 2.57.0. LangChain uses the classifier's per-invocation questions contract.

Typed Questions

from typing import Annotated, Literal
from pydantic import BaseModel, Field
from kedi_typesafe import BooleanCriteria, ChoiceCriteria, Rubric

class Review(BaseModel):
    probability: Annotated[
        float,
        Field(ge=0, le=1, description="Is a refund requested?"),
    ]
    quality: Annotated[
        float,
        Rubric(["Incorrect", "Partially correct", "Correct"]),
    ]
    urgent: Annotated[
        bool,
        BooleanCriteria(
            true="Immediate harm",
            false="No established immediate harm",
        ),
    ]
    route: Annotated[
        Literal["billing", "support"],
        ChoiceCriteria({"billing": "Payments", "support": "Product help"}),
    ]
    labels: list[Literal["refund", "bug"]]

All independent fields share one provider request. Raw bounded probabilities are not thresholded. Rubric floats retain fractional positions; integer rubric fields round to the nearest level, with ties rounded upward. The original score remains in metadata. Each multi-label option gets an independent Noul question and is included only above the configured threshold, in declaration order. Questions that depend on another answer belong in subsequent calls.

Rubric requires 2-10 described levels. ChoiceCriteria keys must match the declared options. Criteria may contain JSON objects or arrays; they are not flattened into strings. Unsupported or conflicting metadata is rejected. List/numeric constraints are validated, never silently repaired.

For both a probability and its boolean decision, request the probability once and compare it in Python. A second model call is unnecessary.

Evidence and Lifecycle

Pydantic responses expose provider_details["typesafe"] and metadata["typesafe"]. LangChain messages expose response_metadata["typesafe"]; use include_raw=True with with_structured_output to retain them. Evidence includes raw probabilities, Choice/Score distributions and confidence, rubric legends, thresholds, and reported usage. Noul has no separate provider confidence. The versioned payload also includes each answer's output path and request, state, question, and decision-configuration fingerprints. The combined request fingerprint changes when the effective model or boolean threshold changes. Unknown usage remains None in evidence even when framework counters need zero.

When this package is used through Kedi, kedi.decision_info(name) attaches that final-response evidence to the corresponding output binding. The helper belongs to Kedi, not this standalone package; kedi-typesafe remains usable without importing Kedi or storing a global last response.

Reuse the model for warm connections. async with TypeSafeModel() and async with TypeSafeChatModel() close owned connections; borrowed SDK clients remain caller-owned. Async clients are event-loop-local. Pydantic AI streaming emits the complete answer rather than pretending Jev generates incremental tokens. No evidence is stored in a global last-result slot.

LangChain

Install kedi-typesafe[langchain] and use the native structured-output surface:

from typing import Literal

from langchain.agents import create_agent
from pydantic import BaseModel, Field

from kedi_typesafe.integrations.langchain import TypeSafeChatModel


class Triage(BaseModel):
    urgent: bool = Field(description="The request needs action today")
    route: Literal["billing", "support", "other"] = Field(
        description="Which team should handle the request?"
    )


agent = create_agent(TypeSafeChatModel("jev-latest"), response_format=Triage)
result = agent.invoke(
    {"messages": [{"role": "user", "content": "I was charged twice. Fix this today."}]}
)
print(result["structured_response"])

TypeSafeChatModel.with_structured_output(...) is also supported for direct LangChain model use. The same Jev schema restrictions described above apply. Free-form invocation, media, stop sequences, and unsupported model settings fail before a provider request. Tool and retry history are retained. Set typesafe_threshold in .bind(...) or a request-local model copy.

Explicit Tool Routing

Attach tools only when the application intends routing. Jev can select a zero-argument tool; the framework executes it through its normal hooks and approval policy. Jev does not fabricate arguments. An argument-requiring tool raises ToolCallProposed, with its name and probability. Use an explicit downstream handler or Pydantic AI FallbackModel if desired; this package does not silently call another model. LangChain exports its proposal from kedi_typesafe.integrations.langchain.

typesafe_tool_call_threshold controls routing independently (default 0.6, upstream semantics). Provide a meaningful output model docstring or agent instructions for Pydantic routing. The routing decision is another question in the same batch, not another provider request. Routing is not authorization: never treat a positive Jev assessment as permission to bypass deterministic tool approval or workspace policy.

Integration Boundaries

The Pydantic model extends the official implementation in Pydantic AI 2.45.0. The LangChain chat model delegates provider transport to langchain-typesafe==0.0.1a2; a narrow pinned private transport bridge avoids nesting a second LLM trace under the chat-model trace. Shared schema lowering and decoding provide the additional thresholds, criteria, and extraction. The beta dependency and private upstream bridges are covered by contract tests.

Sampling settings do not apply. Configure connection timeout in the constructor. Client-level retry behavior belongs to the chosen transport; the wrappers do not add a second retry loop. Install kedi-typesafe[all] and run examples/capabilities.py for both standalone integrations. The seven programs under examples/kedi/ require Kedi; examples/validate_kedi.py runs them on both adapters. Their semantic outputs are model judgments, not guaranteed expected answers.

Email and Phone Extraction

Install the field validators:

pip install 'kedi-typesafe[email,phone]'
from pydantic import BaseModel, EmailStr, Field
from pydantic_ai import Agent
from pydantic_extra_types.phone_numbers import PhoneNumber

from kedi_typesafe.integrations.pydantic import TypeSafeModel


class Contact(BaseModel):
    email: EmailStr = Field(description="The current support email, not the archived address")
    phone: PhoneNumber = Field(description="The current support phone number")


agent = Agent(TypeSafeModel(), output_type=Contact)
result = agent.run_sync(
    "Archived contact: old@example.com. Current support: help@example.com, +1 202-555-0100."
)
print(result.output)

Email and phone candidates are extracted from the supplied text automatically. Jev selects the candidate matching the field description; Pydantic then validates the result. Phone numbers use Pydantic's normalized format, for example tel:+1-202-555-0100. Provide international numbers with a country code. Missing candidates or a no-match answer raise an extraction error rather than inventing a value, unless the declared type is nullable. Fields must be required; a required nullable field may contain None but may not be omitted.

For LangChain, use the same Contact schema with create_agent(TypeSafeChatModel(), response_format=Contact) and install kedi-typesafe[langchain,email,phone].

Runnable Examples

From this package directory, run uv sync --package kedi-typesafe --all-extras and set TYPESAFE_API_KEY. The workspace resolves the shared package locally.

Example Command
Pydantic classification uv run examples/pydantic_agent.py
LangChain classification uv run examples/langchain_agent.py
Pydantic email and phone uv run examples/pydantic_contacts.py
LangChain email and phone uv run examples/langchain_contacts.py

These examples call the real TypeSafe API. An async context manager closes owned connections after use; it is optional for constructing the model. Reusing a model within the same event loop allows its HTTP connection to be reused.

The Kedi reply-review example combines generative drafting with Jev decisions and an optional revision step. It includes the actual live output and decision controls, and requires a Kedi checkout with the decision-metadata API plus an OpenRouter API key.

Probability and Rubric Bounds

Probability is a reusable finite float annotation in [0, 1]:

from typing import Annotated
from pydantic import BaseModel
from kedi_typesafe import Probability, Rubric

class Assessment(BaseModel):
    supported_probability: Probability
    quality: Annotated[
        float,
        Rubric(["Incorrect", "Partly correct", "Correct"]),
    ]

The rubric contributes and validates [0, N-1] bounds automatically. Fractional float scores are retained. You do not need another Field(ge=..., le=...) for those same bounds. General constraints remain Pydantic-compatible. When using Kedi, from kedi import Constraints offers a validation-only helper and from kedi.decisions import Probability, Rubric exposes the shared decision primitives. The standalone package does not depend on Kedi.

See release validation for reproducible synthetic batching checks and their limitations. Version 0.2 changes the default boolean threshold from 0.5 to 0.85 while retaining the strict > comparator; explicitly set the old threshold if an application requires that policy.

Development

cd ../..
uv sync --group dev
make prod

Normal tests use deterministic typed fakes and never call TypeSafe. Live API validation is kept separate so CI and local quality gates do not consume credentials or incur cost.

Metadata

Release files for kedi-typesafe 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kedi-typesafe 0.3.1
File Size Uploaded Provenance Actions
kedi_typesafe-0.3.1.tar.gz 48.5 kB Without provenance Details for kedi_typesafe-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kedi-typesafe 0.3.1
File Interpreter ABI Platform Actions
kedi_typesafe-0.3.1-py3-none-any.whl Python 3 none any Details for kedi_typesafe-0.3.1-py3-none-any.whl

Total release size: 70.1 kB

Release files / kedi_typesafe-0.3.1.tar.gz

Download URL kedi_typesafe-0.3.1.tar.gz
Size 48.5 kB
Tags Source
SHA-256 checksum
How to use checksums
3e651d0e883c89a03d150f2cac42c4be0241eaefae7ea97d8bb20af64e4ece20
BLAKE2b-256 checksum
How to use checksums
e58412d9b67495509d7afb72f2e7fefe02669b3d397a49a555d8ab42a4001f28
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / kedi_typesafe-0.3.1-py3-none-any.whl

Download URL kedi_typesafe-0.3.1-py3-none-any.whl
Size 21.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c0b47559988c0893f39760c3e45ffcd554359716aba6671aaa7ed83a7ff6028e
BLAKE2b-256 checksum
How to use checksums
ade742ec89439de216317c9d0c76921c5e7bc0942263b922113e0605ccc7b0b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for kedi-typesafe 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page