Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 34 additions & 8 deletions ai_http.py
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,26 @@ def collect(value, depth=0):
return 'Provider detail: ' + ' | '.join(messages)[:340] if messages else 'The provider returned no readable error message.'


def pumas_error_detail(data, payload=None, headers=None):
"""Pumas' OpenAI-compatible errors carry its (redacted) reason in `error.message`.

Returns '' for any body that is not a bounded `pumas_error`; that reason is
still passed through the same redaction as other provider diagnostics.
"""
if not data or len(data) > MAX_ERROR_BODY:
return ''
try:
value = json.loads(data)
except (ValueError, UnicodeError):
return ''
error = value.get('error') if isinstance(value, dict) else None
if (not isinstance(error, dict) or error.get('type') != 'pumas_error'
or not isinstance(error.get('message'), str) or not error['message'].strip()):
return ''
detail = provider_error_detail(json.dumps({'message': error['message']}).encode(), payload, headers)
return 'Pumas reported: ' + detail.removeprefix('Provider detail: ') if detail.startswith('Provider detail: ') else ''


def request_error_hint(data):
"""Classify bounded provider errors without exposing arbitrary response text."""
try:
Expand Down Expand Up @@ -184,18 +204,24 @@ def watch_cancel():
403: 'Check account permissions and provider restrictions.',
429: 'Rate limit reached; wait before trying again.'}.get(response.status,
'Check the selected model and structured-output support.')
if response.status == 400 or response.status >= 500:
try:
transport.settimeout(max(.001, min(2, deadline - time.monotonic())))
error_data = response.read(MAX_ERROR_BODY + 1)
specific = request_error_hint(error_data) if len(error_data) <= MAX_ERROR_BODY else ''
try:
transport.settimeout(max(.001, min(2, deadline - time.monotonic())))
error_data = response.read(MAX_ERROR_BODY + 1)
except (OSError, http.client.HTTPException):
error_data = None
if label == 'OpenRouter' and (response.status == 400 or response.status >= 500):
hint = 'Could not read the provider error body within the diagnostic limit.'
if error_data is not None:
specific = request_error_hint(error_data) if len(error_data) <= MAX_ERROR_BODY else ''
pumas_detail = pumas_error_detail(error_data, payload, headers)
if pumas_detail:
# Pumas' own (redacted) reason is shown for every refusal status.
hint = (specific + ' ' if specific else '') + pumas_detail
elif response.status == 400 or response.status >= 500:
if label == 'OpenRouter' or response.status >= 500:
hint = provider_error_detail(error_data, payload, headers)
elif specific:
hint = specific
except (OSError, http.client.HTTPException):
if label == 'OpenRouter':
hint = 'Could not read the provider error body within the diagnostic limit.'
raise CodexError(f'{label} returned HTTP {response.status}. {hint}',
retryable=response.status in (502, 503, 504))
yield response, transport, deadline
Expand Down
108 changes: 75 additions & 33 deletions docs/contracts/pumas-image-to-text-consumer.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,52 @@
# Pumas Image→Text consumer

This opt-in caption path consumes the contract at Pumas Library merged PR68,
source `36c2aab2c885b8416fd4e39cf8c37c510596d6e4`:
[Image→Text contract](https://github.com/MrScripty/Pumas-Library/blob/36c2aab2c885b8416fd4e39cf8c37c510596d6e4/docs/contracts/image-to-text-v0.8.md).
It is based on Tuldok main `d99e23d2b0d2783a7a9863232a7453cd9f2db7aa`.
The legacy compatible caption path and the previous typed text/image operations
remain available. Their existing producer receipt is not silently repinned.
This opt-in caption path, and the typed text and image operations that share
`pumas_operations`, consume the Pumas Library v0.8 typed HTTP contract on branch
`feat/v080-consumer-api`, source `4c79cd8e35db566b70caaa13d8d8f92265f5976e`:
[model operations, contract version 1](https://github.com/MrScripty/Pumas-Library/blob/4c79cd8e35db566b70caaa13d8d8f92265f5976e/docs/contracts/model-operations-v1.md).
It supersedes the merged PR68 pin `36c2aab2c885b8416fd4e39cf8c37c510596d6e4`,
which `source.json` keeps as `previous_producer`. The legacy compatible caption
path remains available. The PR54 typed text/image capture receipt in
`tests/fixtures/pumas-typed-v1` is historical and is not repinned.

`pumas_operations.validate_manifest` accepts all seven closed capability variants,
the three additional image input formats and image byte/pixel/count option names.
The existing unavailable reasons remain unchanged. Availability is a live
observation, not a model qualification receipt. Audio's existing
`max_output_tokens` descriptor option is accepted as declared in the inspected DTO.
### Additive compatibility

Pumas responses grow additively within contract version 1. Tuldok validates
only what it uses and selects capabilities and option bounds by name, never by
position or count:

- `GET /v1/capabilities` requires `supported_contract_versions` containing 1,
`model`, an exact `profile`, positive `max_request_bytes`/`max_response_bytes`
and a `capabilities` list. Other fields (`context_tokens`,
`max_stream_event_bytes`, future fields) are retained but not required.
- Only `chat_generation`, `image_generation` and `image_to_text` descriptors are
validated: fixed semantic task, string format lists, an availability `state`
with an optional string reason, and finite, ordered bounds for the options
Tuldok compares (`max_tokens`, `temperature`, `top_p`, `width`, `height`,
`seed`, `image_bytes`, `image_pixels`, `image_count`). A used capability or
option advertised twice is refused as ambiguous.
- Other capabilities (`multimodal_embedding`, `decision`, audio, future values),
formats (`content_batch`, `decision`, `decisions`, future values), option names,
availability states and reasons, and response or result fields are ignored.
Any availability other than `available` means unavailable, and its reason is
shown.
- The capability observation is bounded at 1 MiB. `GET /v1/served-models` is
preferred for listing serving aliases with their profiles; gateways without it
(HTTP 404) fall back to `/v1/models`, which lists each ID once with `profiles`.

Availability is a live observation, not a model qualification receipt.

Choose **Pumas typed v1** in the image caption form, select the serving alias and
optional exact profile, and inspect capabilities. On each new attempt, the owner
requires `pumas.model-operations.image-to-text:1` in the gateway build advertisement
and an available Image→Text descriptor for the exact resolved model/profile.
and an available Image→Text descriptor for the exact resolved model/profile. The
gateway advertisement (`GET /.well-known/pumas`) has its own versioned decoder,
which also grows additively: unknown fields and new protocol, schema, capability or
compiled-feature entries are ignored and are not retained in the stored build
observation, which keeps only the known fields. Missing required fields, wrong
types, unsupported schema versions and malformed endpoints are refused with a
reason naming the field; a gateway scan lists such refused advertisements with
their reasons instead of hiding them.
The request uses the facade's `messages`, `semantic_task:"image_to_text"`,
text-generation options and `stream:false`. The seed is omitted. Named image and
`image_messages` inputs are also supported by the bounded consumer request builder.
Expand All @@ -25,8 +55,10 @@ messages can contain images; audio, URLs, paths and data-URL envelopes are refus

The consumer applies the producer's 32 MiB whole-request, 8 MiB per-image, 16 MiB
aggregate, four-image, 4096-axis, 4,194,304-pixel, 128-message and 128-total-part
bounds. Tokens default to 512 and permit 1–2048; temperature/top-p must be finite
and within 0–2/0–1. The caption application's existing preparation is smaller:
bounds. Tokens default to 512. Pumas no longer caps Image→Text `max_tokens` at
2048; the live `max_tokens` bound follows the served context window and is
checked before admission. Temperature/top-p must be finite and within 0–2/0–1.
Advertised image byte, pixel, count and dimension bounds are checked when present. The caption application's existing preparation is smaller:
one RGB JPEG, at most 2 MiB and 1600 pixels on its longest side. It decodes the
captured, hash-verified canonical image and retains both canonical-source and
prepared-input hashes. Preparation is explicit in request history.
Expand All @@ -37,8 +69,8 @@ replace Pumas's production PNG/turbojpeg validation, allocation controls or
admission authority, and does not claim equivalent JPEG warning detection.
No local validation result is used as permission to bypass provider refusals.

The response is the closed `{contract_version, request_id, result}` envelope.
The request ID must match; `result.kind` must be text. There is no response-model
The response is the `{contract_version, request_id, result}` envelope; added
fields are ignored. The request ID must match; `result.kind` must be text. There is no response-model
requirement and no private provider envelope projection. This application requires
a complete `stop` finish reason and valid caption JSON within a 256 KiB response
bound; partial or filtered output is not applied. Capability/build observations,
Expand All @@ -47,8 +79,15 @@ on the exact job. List responses omit image-bearing canonical requests and raw
bytes. Explicit application creates a draft target and records its evidence in
revision history; human review remains separate.

HTTP 400/413/422/503 pre-admission refusals and 502 failures retain their typed
code, HTTP status and `outcome` in the asynchronous job. A disconnect, uncertain
Every typed error is `{contract_version, request_id, error:{code, outcome, message}}`.
`error.outcome` is authoritative: `not_admitted` records no provider effect and
anything else is `unknown`, whatever the HTTP status. 404 `model_not_found` and
409 `ambiguous_model`/`ambiguous_operation` are ordinary refusals. An error whose
`request_id` is `null` (Pumas could not read the body) is still a typed refusal.
Unknown error codes are kept verbatim. The job retains the code, HTTP status and
outcome, and its error text includes Pumas' `error.message`, bounded and on one
line. Capability refusals show the same message. On the OpenAI-compatible routes,
a `pumas_error` body's `error.message` is shown after the existing redaction. A disconnect, uncertain
response or possibly dispatched interrupted attempt remains `unknown`. Repeating
an existing exact application request ID returns the retained attempt; it never
replays inference. A new attempt requires a new explicit request. Browser recovery
Expand All @@ -65,27 +104,30 @@ and packaged application acceptance remain integration-lead/provider-owner gates

`tests/fixtures/pumas-image-to-text-v1/source.json` labels the capability/wire
fixture as **source-derived**, with inspected production-source hashes. It is not
a captured native DTO schema export or an actual model reply. The tests exercise
seven-capability parsing, named/facade PNG/JPEG inputs (including progressive
a captured native DTO schema export or an actual model reply. The fixture follows
the pinned descriptor construction for a llama.cpp vision serving with an
8192-token context, including the `multimodal_embedding` and `decision`
descriptors. The tests exercise additive capability parsing, named/facade PNG/JPEG inputs (including progressive
JPEG), order, closed shapes, finite/resource bounds, typed application captions,
draft/history, live selection refusal, cancellation/borrowed-owner survival,
HTTP outcomes, restart and no replay. The existing typed browser suite additionally
checks the actual caption form, capability inspection, application and disconnect.

The six actual production DTO schemas regenerated from the combined source
are retained in `tests/fixtures/pumas-image-to-text-v1/schemas/`, with SHA-256
identities in `source.json`. The source-derived capability fixture and authored
named/facade image requests and typed responses validate against these exports.
The schemas describe wire shape; finite bounds and live readiness remain runtime
checks. Neither fixture output nor schema validity proves native inference.
The six actual production DTO schemas regenerated at the pinned source with the
`export-contract` feature are retained in
`tests/fixtures/pumas-image-to-text-v1/schemas/`, with SHA-256 identities in
`source.json`. All six changed from the PR68 export (new capabilities, formats,
`context_tokens`, decision and content-batch DTOs and the required error
`message`). The
source-derived capability fixture and authored named/facade image requests and
typed responses validate against these exports in the vision tests. The schemas
describe wire shape; finite bounds and live readiness remain runtime checks.
Neither fixture output nor schema validity proves native inference.

The reviewed producer retains identical DTO definitions and schema dependencies;
all six exported schema SHA-256 identities are unchanged. `source.json` records
the export commit and refreshed handler/controlled-test source hashes. The fixture
gateway advertisement reads the same versioned source pin as its consumer
acceptance evidence.
This pin is the immutable merged Pumas main commit. Its source tree is identical
to the reviewed producer that passed CI before the coordinated merge.
`source.json` records the branch, commit, tree, contract document hash and
handler/controlled-test source hashes. The pin is a branch commit, not a merged
Pumas main commit; repin when it merges. The fixture gateway advertisement reads
the same versioned source pin as its consumer acceptance evidence.
The combined desktop contract and packaged application are provider integration
gates. Real model/projector inference, semantic quality, managed native teardown
and production audio qualification remain unclaimed. No models or runtimes are
Expand Down
23 changes: 17 additions & 6 deletions gateway_discovery.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,10 @@ def listening_endpoints():
return sorted(endpoints, key=lambda endpoint: (endpoint[1], endpoint[0]))


def get_json(host, port, path, deadline, payload=None, max_response=MAX_RESPONSE, decode=json.loads, require_complete=False):
def get_json(host, port, path, deadline, payload=None, max_response=MAX_RESPONSE, decode=json.loads, require_complete=False,
error=None):
"""GET/POST bounded JSON. With `error`, a non-200 body is read under the same bounds
and passed to `error(status, raw)`, which raises a readable refusal."""
timeout = min(1.5, deadline - time.monotonic())
if timeout <= 0:
raise TimeoutError()
Expand Down Expand Up @@ -64,7 +67,7 @@ def expire():
expiry.daemon = True
expiry.start()
with connection.getresponse() as response:
if response.status != 200:
if response.status != 200 and error is None:
raise ValueError('Not a gateway response')
if require_complete:
declared = response.getheader('Content-Length')
Expand All @@ -86,6 +89,9 @@ def expire():
raise ValueError('Pumas descriptor response ended before its declared length')
if require_complete and time.monotonic() >= deadline:
raise TimeoutError()
if response.status != 200:
error(response.status, bytes(data))
raise ValueError('Not a gateway response')
return decode(data)
finally:
if expiry is not None:
Expand Down Expand Up @@ -212,15 +218,20 @@ def scan_advertised():
def observe(item):
host, port = item
address = '[' + host + ']' if ':' in host else host
url = f'http://{address}:{port}'
try:
return inspect_advertised(f'http://{address}:{port}', deadline)
return inspect_advertised(url, deadline), None
except descriptor.Rejected as error:
# Pumas answered but its advertisement was refused: keep the reason for the user.
return None, {'server_url': url, 'reason': str(error)}
except (OSError, ValueError, TypeError, http.client.HTTPException):
return None
return None, None
with ThreadPoolExecutor(max_workers=32) as pool:
results = list(pool.map(observe, endpoints))
# Distinct IPv4/IPv6 services on one port must retain their library context.
found = {row['server_url']: row for row in results if row is not None}
return {'gateways': list(found.values()), 'qualification':
found = {row['server_url']: row for row, _ in results if row is not None}
rejected = [refusal for _, refusal in results if refusal is not None]
return {'gateways': list(found.values()), 'rejected': rejected, 'qualification':
'Read-only HTTP advertisements. Core ownership is not authenticated; compiled features do not prove model readiness.'}
finally:
SCAN_LOCK.release()
8 changes: 7 additions & 1 deletion image_generation.py
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,13 @@ def watch_cancel():
499: 'Image generation cancelled.',
503: 'The image model is unavailable. Load it in Pumas and refresh models.',
507: 'Pumas reported insufficient GPU memory. Free memory before trying again.'}
raise ValueError(messages.get(response.status, 'Pumas image generation failed. Check its runtime status. The request was not retried.'))
message = messages.get(response.status, 'Pumas image generation failed. Check its runtime status. The request was not retried.')
try:
transport.settimeout(2)
detail = ai_http.pumas_error_detail(response.read(ai_http.MAX_ERROR_BODY + 1), payload)
except (OSError, http.client.HTTPException):
detail = ''
raise ValueError(message + (' ' + detail if detail else ''))
data = bytearray()
while not response.isclosed():
chunk = response.read1(65536)
Expand Down
Loading
Loading