Download the PHP package binnash/typesafe-sdk without Composer
On this page you can find all versions of the php package binnash/typesafe-sdk. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download binnash/typesafe-sdk
More information about binnash/typesafe-sdk
Files in binnash/typesafe-sdk
Package typesafe-sdk
Short Description PHP & Laravel SDK for TypeSafe AI's JEV Model series
License MIT
Informations about the package typesafe-sdk
TypeSafe PHP SDK
PHP SDK for TypeSafe AI — small units of AI intelligence you can use like programming primitives.
TypeSafe's System One models, including Jev, turn natural language and application state into typed judgments and probabilities that code can combine. A single request evaluates any number of typed questions about the same state, and your code owns the workflow: routing, thresholds, ranking, and side effects.
- Requirements
- Installation
- Quickstart
- Primitives
- Questions
- Reading answers
- Configuration
- Per-call options
- Retries
- Errors
- Logging
- Models
- Laravel
- Testing
Requirements
- PHP 8.2 or newer with
ext-json - A PSR-18 HTTP client and PSR-17 request/stream factories. The SDK discovers
whatever your project already has installed;
guzzlehttp/guzzleis a good default:
Installation
Create an API key in the TypeSafe console, then construct a client. The SDK never reads the environment; pass values explicitly so configuration stays in your application's control.
Quickstart
state is the content to evaluate: a string, or structured data such as a record
or chat log. questions is a map you name; answers come back under the same names.
Question names are keys in your code only — they are not sent to the model, so put
the full meaning in the question itself.
Primitives
Choose by what the answer means.
| Question | Use when | Answer |
|---|---|---|
Question::noul() |
A condition holds or not | Probability of yes, 0.0–1.0 |
Question::choice() |
One of a defined set | Winning label, distribution, confidence |
Question::score() |
Degree along an ordered rubric | Probability-weighted score, legend, confidence |
Use one Question::noul() per label when several labels may apply independently.
Use comparable Question::score() questions for graded ranking across items.
The SDK ships no global functions. Everything lives in the
Binnash\Typesafe namespace, so installing it never reserves identifiers such as
Question::choice() in your application's global scope — a collision risk with Laravel's
own global helpers, other packages, or your own code. One import covers all three
builders:
Questions
Noul — yes or no
A probability near 0.5 means yes and no are similarly likely — not medium
intensity. There is no separate confidence.
Choice — one of a set
Confidence summarizes how concentrated the distribution is. It is not a guarantee of correctness and not permission to act; validate thresholds on your own data and consequences.
Score — degree along a rubric
At least two levels are required, ordered from zero. Levels should describe concrete situations and stand on their own.
Instructions and criteria
Instructions may be text, or a JSON object or array when a question needs structure. Descriptions may also be objects, which helps define contrasts, exclusions, and examples:
Composing requests
Ask independent questions over the same state together; they run in parallel and cannot see one another's answers. Include speculative questions when useful — code consumes only the applicable answers. A second request is warranted only when an earlier answer determines what to fetch or ask next.
Reading answers
Answers are keyed by the names you chose and support property, array, and typed access:
Answers are immutable. SystemOneResult also carries model, usage, and
requestId, and json_encode($result) produces the response body plus
request_id.
Configuration
Use ClientConfig when you need anything beyond an API key:
ClientConfig::make() accepts an API key string or a map of the same arguments,
and TypeSafe::client('key', ['timeout' => 30.0]) is shorthand for it. The API
key is always redacted from var_dump() and json_encode() output.
Per-request headers are merged case-insensitively, and SDK-owned headers
(Authorization, Accept, User-Agent, X-TypeSafe-SDK, X-TypeSafe-Runtime,
Content-Type, X-TypeSafe-Retry-Count) cannot be overridden.
Per-call options
Every call accepts an options array and, for systemOne, extra top-level payload
fields:
Use systemOneWithResponse() when you also need the HTTP status, headers, or
request ID (the JavaScript SDK's withResponse()):
Retries
Failures are retried automatically with capped exponential backoff and jitter.
| Setting | Default | Meaning |
|---|---|---|
maxRetries |
2 |
Retries after the initial attempt; 0 disables |
backoffInitialMs |
500 |
First backoff delay |
backoffMaxMs |
5000 |
Maximum backoff delay |
backoffJitter |
0.25 |
Fraction of each delay randomly subtracted |
httpStatuses |
408, 429, 500–599 |
Status codes to retry |
respectRetryAfter |
true |
Honor retry-after-ms and Retry-After headers |
maxRetryAfterMs |
60000 |
Longest server delay to honor before using backoff |
retryConnectionErrors |
true |
Retry connection failures |
retryTimeoutErrors |
true |
Retry attempts that exceeded the timeout |
A per-call timeout is enforced per attempt: the SDK measures each attempt and
raises ApiTimeoutException when the budget is spent. Configure real transport
timeouts on your PSR-18 client as well (for example Guzzle's timeout option).
Errors
Every exception extends Binnash\Typesafe\Exceptions\TypeSafeException.
| Exception | Raised for |
|---|---|
ApiException |
Any other non-2xx response; exposes status, body, headers, requestId |
BadRequestException |
400 — the request is invalid |
AuthenticationException |
401 — the API key is missing or invalid |
PermissionDeniedException |
403 — access is denied |
NotFoundException |
404 |
UnprocessableEntityException |
422 — request validation failed |
RateLimitException |
429 — exposes retryAfterMs |
InternalServerException |
5xx |
ApiConnectionException |
The request or response delivery failed |
ApiTimeoutException |
The attempt exceeded the timeout; exposes timeoutMs |
Messages are derived from the response body, including FastAPI/Pydantic validation details:
Shapes the API would reject are caught before sending, so failures surface
locally: an empty questions map, Question::score() criteria that are not a list of
at least two levels, Question::choice() criteria that are a list or empty, and
unknown Question::noul() criteria keys.
Logging
Pass any PSR-3 logger. info logs request summaries; debug adds headers and
bodies. Credential headers are redacted before they reach the logger.
Redaction covers Authorization, Proxy-Authorization, X-API-Key (scheme and
last four characters preserved), and Cookie/Set-Cookie (replaced entirely).
Request bodies are not redacted — avoid logging debug when state contains
sensitive data.
Models
jev-latest tracks the most recent stable release and moves when a new one
ships, so answers can change without a change on your side. The response's
model field reports the versioned ID that answered — log it, and pin a version
in defaultModel when you have tuned thresholds against it.
Laravel
Laravel 11 and 12 are supported through package auto-discovery: install the package, set your key, and start calling it.
That is the whole setup. The bridge reads these variables for you:
| Variable | Default | Purpose |
|---|---|---|
TYPESAFE_API_KEY |
required | API key used as a bearer token |
TYPESAFE_BASE_URL |
https://api.typesafe.ai |
API root |
TYPESAFE_DEFAULT_MODEL |
jev-latest |
Model used when a call omits one |
TYPESAFE_TIMEOUT |
10.0 |
Timeout per attempt, in seconds |
TYPESAFE_LOG_LEVEL |
warn |
debug, info, warn, error, or off |
TYPESAFE_MAX_RETRIES |
2 |
Retries after the initial attempt |
TYPESAFE_BACKOFF_INITIAL_MS |
500 |
First backoff delay in milliseconds |
TYPESAFE_BACKOFF_MAX_MS |
5000 |
Maximum backoff delay in milliseconds |
TYPESAFE_BACKOFF_JITTER |
0.25 |
Fraction of each delay randomly subtracted |
TYPESAFE_RESPECT_RETRY_AFTER |
true |
Honor server retry delay headers |
Only the bridge reads the environment — the core SDK always receives explicit values, so its behavior is identical outside Laravel.
The facade
Dependency injection
The client and its configuration are shared singletons, so type-hinting either one resolves the same instance the facade uses — in controllers, jobs, commands, and listeners:
Publishing the config
This copies config/typesafe.php into your application, where the defaults above
can be changed and a custom PSR-18 client, PSR-17 factories, or logger can be
configured (http_client, request_factory, stream_factory, logger). Values
left as null fall back to whatever your container binds.
Logs go to Laravel's logger by default, filtered by TYPESAFE_LOG_LEVEL.
Testing your application
Bind your own PSR-18 client in a test to keep the network out of it:
The package's own bridge tests do exactly this; see
tests/Feature/Laravel/LaravelBridgeTest.php.
Testing
The live suite calls https://api.typesafe.ai for real. Set TYPESAFE_API_KEY
to run it, and optionally TYPESAFE_BASE_URL to point at another host. Tests are
skipped automatically when no key is present, and are excluded from
composer test.
All versions of typesafe-sdk with dependencies
ext-json Version *
php-http/discovery Version ^1.18
psr/http-client Version ^1.0
psr/http-factory Version ^1.0
psr/http-message Version ^1.1 || ^2.0
psr/log Version ^1.0 || ^2.0 || ^3.0