Understand the current RtU request model, verdicts, statuses, and evidence fields.
Right-to-Use (RtU)
Right-to-Use is the decision layer behind Souma's live validation workflow. Each check asks a narrow question:
Can this source be used for this purpose?
The current platform evaluates URLs and usage purpose, then writes the result into the dashboard and evidence log.
Request model
Every validation request contains:
| Field | Meaning |
|---|---|
request_id | Your correlation ID for the job |
url | The source being evaluated |
purpose | The usage you want reviewed, such as model training, summarization, or customer-facing publication |
When the check is accepted, Souma returns a validation_id and starts tracking the job through the current workflow.
Verdicts
Souma returns one of three right-to-use judgments:
| Verdict | Description |
|---|---|
| PERMITTED | The available policy evidence supports the requested use |
| NOT_PERMITTED | Souma found language that blocks or materially restricts the requested use |
| UNCLEAR | The policy picture is incomplete or conflicting, so a human review path is recommended |
Status lifecycle
Verdicts are distinct from job status. A request moves through one of these processing states:
| Status | Meaning |
|---|---|
PENDING | Accepted and still running |
COMPLETED | Finished with a verdict or an explainable null result |
ERROR_NOT_FOUND | The URL could not be retrieved |
ERROR_NO_POLICY | No usable policy could be found |
ERROR_LLM | The reasoning step failed upstream |
ERROR_TIMEOUT | Processing exceeded the allowed time window |
ERROR_NETWORK | The source could not be reached reliably |
ERROR_INVALID_URL | The submitted URL was malformed |
Confidence and evidence fields
Every completed result can include the following evidence:
| Field | Why it matters |
|---|---|
confidence_score | Indicates how strongly the available evidence supports the decision |
llm_reasoning | Plain-language explanation of the judgment |
conditions | Use constraints that operators should preserve |
policy_source_urls | The policy pages that informed the result |
policy_source_text | Captured excerpts for downstream review and audit trails |
How to interpret uncertainty
UNCLEAR is not a soft permit. In the current Souma workflow it should be treated as an escalation signal:
- keep the output out of customer-facing release paths
- route it to legal, policy, or operations review
- store the evidence packet so the team can justify the final call
Handling large batches
Massive URL lists are where sloppy RtU implementations usually fail. The current Souma checker deliberately chunks work into batches of 8 URLs with concurrency 2 to stay inside the proxy timeout window.
If you are building your own integration, use the same operating posture:
- submit in small batches instead of one huge request
- persist every
validation_idthat comes back - poll or stream results asynchronously
- show partial completion in the UI instead of waiting for the entire batch
This matters because the current /api/validate proxy enforces a hard timeout. If you treat RtU as a single blocking request for very large workloads, you will eventually see 504 responses.