4.0 KiB
Step 2 — Implementation Detail
Built ahead of step 1's answers, on the owner's instruction of 2026-10-07 that no evaluation be rerun until the Jev work is in. Nothing here has called the live service.
- The seam (
app/adk/runtime.py):Question(kind choice, score or noul, with instructions and options),Answer(value, confidence, probabilities) and theDeciderprotocol.decidereturns the answers, orNonewhen no decision could be made, and the caller then takes its fallback.NoDecideralways returnsNone. - The client (
app/tools/jev.py):JevDecidercalls Jev through TypeSafe AI's official Python SDK,typesafe-sdk0.7.2 (AsyncTypeSafeClient.system_one). The owner chose the SDK and its API endpoint on 2026-10-07. It is the only module that imports the SDK. - Wiring:
open_deciderinapp/agent.pyreturns the client whenTYPESAFE_API_KEYis set andNoDeciderotherwise; theAssemblycarries it. - A scripted decider for tests,
FakeDeciderinapp/adk/fake_runtime.py.
Which package: three names exist on the index. typesafe-sdk is the vendor's (author TypeSafe AI, repository typesafe-ai/typesafe-sdk-python). typesafe is an unrelated type-checking library, and typesafe-ai is a third party's redirect shim; neither is used.
What the SDK settled, read from the installed package and a stand-in transport:
- The request is
POST /v1/systemonewith a bearer key; default endpointhttps://api.typesafe.ai, default modeljev-latest. - Questions are
Noul(instructions),Choice(instructions, criteria={option: description})andScore(instructions, criteria=[levels]). - Answers are
noul(a probability, with no confidence of its own),choicewithconfidenceandprobabilities, andscorewithconfidence. Usage reportsinput_tokensonly: no cost and no remaining credit.
Limits kept, each with a test in tests/tools/test_jev.py:
| Practice | Built as |
|---|---|
| Size | Refused locally above 48,000 estimated tokens in all, or 24,000 for the state plus the longest question. Never truncated. |
| Batching | Every question about one state goes in one request. |
| Timeout | 5 seconds a request, 15 for a decision with its retries (the SDK's). |
| Retries | 2, by the SDK: on 408, 429, 5xx, connection and timeout errors, with jittered backoff, honouring Retry-After. |
| Rate | A token bucket, 5 a second with a burst of 10; the rate halves when a rate limit outlasts the retries. |
| Concurrency | At most 8 requests in flight. |
| Circuit breaker | Opens after 5 failures in 30 seconds for 60 seconds, then lets one probe through. |
| Cache | Answers kept by a hash of the state and questions, up to 1,024. |
| Budget | 500 calls or 1,000,000 input tokens per scope (the Execution), then fallbacks with one warning. |
| Records | Each decision's outcome, seconds, rate limiting, input tokens and confidence; summary() totals them. |
| Key | From TYPESAFE_API_KEY only; never logged. |
Settings: TYPESAFE_API_KEY, TYPESAFE_BASE_URL, TYPESAFE_DEFAULT_MODEL (the SDK's own names), and JEV_TIMEOUT_SECONDS, JEV_REQUESTS_PER_SECOND, JEV_MAX_IN_FLIGHT, JEV_BUDGET_CALLS, JEV_BUDGET_TOKENS.
Changed from the plan:
- The cache is per client, not per Execution. A decision depends only on its state and questions, so two Executions asking the same thing can share the answer.
- A reply that leaves any question unanswered, or picks a choice that was not offered, counts as no decision for the whole request.
- The budget is in calls and input tokens, not dollars, and there is no low-credit warning: the SDK reports neither cost nor balance.
- A yes-or-no answer's confidence is derived as its distance from an even probability, because Jev returns none.
- Retries and their backoff are the SDK's, configured here, not reimplemented.
Unverified: the client has run only against a stand-in transport, with the real SDK in the loop. The first call with a real key is still to be made, and the service's actual rate limits, latency and data retention are still unknown.