Repository navigation
Releases
v6.0.0
Added
- Router benchmark harness. The routing corpus is a file of
EvalCase
objects (benchmarks/router/cases.json, taggedlabelled,shape:<id>,
trap,injection,ambiguous) andlocus.router.benchmarkadapts
selection toEvalRunner's contract: a typed target that takes any
RequestClassifierin the router's front seam, a free-form baseline that
may name an unregistered id, androuter_gate, which holds the typed
router to the baseline on the whole corpus and on the traps, to 100%
bounded under injection and, for a classifier under test, to no per-case
regression (regressionslists the cases either way). Every target
answers a protocol id,unboundedorrefused, and retries a transient
provider error before refusing; nothing is built or run.
scripts/router_benchmark.pyruns it against a model and stores the
reports;tests/integration/test_router_classifier_gate.pyis the same
gate behindRUN_ROUTER_BENCHMARK=1, and the routing benchmark beside it
reads the same file. (#342) - Checkpoint TTL. Every checkpointer takes
ttl=(seconds or a
timedelta): a checkpoint expires that long after its save and is then
neither loaded, listed nor forked, andawait cp.expire()removes what has
expired and returns the count. Redis gets its ownEXPIREon every key a
thread writes (the index hash and the tool-effect ledger's sidecar
included; the index's expiry only ever lengthens, so a shorter-lived save
never hides the longer-lived checkpoints); PostgreSQL, MySQL and
PgCheckpointerkeep anexpires_atcolumn, added to an existing table
by the first save made with attl— a checkpointer without one issues
no DDL and filters on the column only where it exists; the in-memory,
file, S3, OCI Object Storage and HTTP checkpointers record it beside the
checkpoint, and a load of a thread's latest falls back to its newest
live checkpoint when the pointer names an expired one. (#298) - Checkpoint encryption at rest.
EncryptedSerializer(AES-256-GCM via
cryptography,pip install "locus-sdk[encryption]") seals the state
before any backend stores it:encryption=on every checkpointer, a key
or akey_providercallable for a vault fetch,previous_keysfor
rotation, and a versioned envelope that keeps the iteration readable and
is bound to its place — the stored thread id, the checkpoint id and the
iteration are the cipher's associated data, so a ciphertext moved to
another thread or checkpoint, or an envelope whose iteration was edited,
is refused. With encryption configured a plaintext checkpoint is refused
too;EncryptedSerializer(..., allow_plaintext=True)loads it with a
warning, for migrating a store written before encryption was turned on.
The listing fields — ids, times, iteration, size, parent and the metadata
passed tosave()— stay in the clear solist()works without the key.
(#298) - Per-application and per-user scoping.
CheckpointScope(app_id=, user_id=)on every checkpointer (scope=) or per run (agent.run(…, scope=…), alsoarun,run_sync,resume,continue_turn) stores a
thread underapp=<app_id>/user=<user_id>/<thread_id>— a key, directory
or object prefix, thethread_idcolumn's prefix on SQL — so the same
thread_idunder another scope is a miss, not another tenant's thread.
Each segment of the stored id is percent-encoded, so no thread id can
spell a scope marker, an app-only scope sees app-level threads only, and
an unscoped checkpointer never resolves a scoped id; a run's scope is
resolved once and carried by a view of the checkpointer
(cp.with_scope(scope)), never a context variable, withscope=None
inheriting the checkpointer's scope andCheckpointScope()explicitly
unscoped;list_threads(scope=)lists one scope, and unscoped data stays
reachable with no scope. (#298) python -m locus.runnertakes its workspace fromLOCUS_WORKSPACEwhen
set, for a runner started outside an OpenShell sandbox (a gateway's local
box driver, a CI job); unset, it works on/sandboxas before.locus audit verify --format json. The verification of an exported
audit trail as data:{"file", "verified", "records", "keys", "head_checked"}on stdout for both outcomes, where the command printed
prose only and a job archiving its results had to scrape it. Exit codes
are unchanged: 0 when the trail verifies, 1 when it does not. (#483)locus eval gate --markdownandGateResult.to_markdown(). The
gate's verdict as Markdown with one table row per failed check, for a
pull-request comment, the wayeval diffandeval summaryalready
render with--markdown. The exit code is still the gate's verdict. (#484)HeatWaveVectorStore— MySQL HeatWave vector store (#299). Documents
live in one InnoDB table with aVECTOR(n)column, aJSONmetadata
column and aFULLTEXTindex on the content; the store mirrors
OracleVectorStore's surface (add,add_batch,get,delete,
search,count,clear,close) plushybrid_search, which blends
DISTANCE()similarity withMATCH ... AGAINSTrelevance client-side the
way the Elasticsearch store does. It probes the server once: HeatWave
MySQL computes and orders byDISTANCE()on the server
(server_side_distance=True); community MySQL 9+ has theVECTORtype
but noDISTANCE(), so the store fetches up tocandidate_limitrows and
ranks them here. Metadata filters areJSON_EXTRACTequality predicates
with the path and the value bound as parameters. Blocking driver calls run
on worker threads (asyncio.to_thread), so the pooled connections never
bind to an event loop. Newheatwaveextra (the same
mysql-connector-pythonthemysqlcheckpoint extra installs), lazy
export fromlocus.rag.stores, docs rows and a HeatWave vs community
MySQL section, and the shared conformance suite behindHEATWAVE_DSN.- Control-layer conformance fixtures.
conformance/v1/holds the test
vectors a port of the governance core proves parity against: canonical
JSON digests in both escaping modes, unsigned, signed and rotated-key audit
trails with a file per tamper class and theAuditReporteach yields,
policy documents with their hash, lint findings and decisions, malformed
documents with the error key, approval digests, ids and decision
sequences, and the exactaction-admissionline an admission writes.
scripts/conformance_export.pyregenerates them from a fixed clock and
fixture keys; a unit test fails on any difference, so a format change is a
deliberatev2. A dependency-free Node script under
conformance/v1/tools/recomputes the digests and verifies the signatures
from the other side. (#343)
Changed
- Changed in 6.0:
Agent(tool_call_integrity=...)defaults toTrue.
Every tool call is signed as the model's response is parsed and verified
before it runs, so a hook that rewritesevent.argumentsmust call
event.resign(by="MyHook")or the call is refused with a
ToolCallIntegrityError; the built-inGuardrailsHookredaction and
ExternalHooksrewrites already do. PassAgent(tool_call_integrity=False)
to keep the 5.x behaviour. (#450) - Unscoped thread ids that spell a scope marker are stored encoded. A
thread id of the formapp=…oruser=…(or beginningapp%/
user%) on a checkpointer with noscope=is now stored
percent-encoded (user=alice/chatasuser%3Dalice%2Fchat), so the
bare stored id can only ever be another tenant's scoped thread. A thread
of that exact shape written by an earlier release is no longer found
under its bare id: load it throughCheckpointScope(user_id="alice")
(the bare id parses as that scope's threadchat) or rename it before
upgrading. Every other unscoped id keeps its bare stored form. The
adapter'sexists()now reads the document to honour a recorded expiry
(one extra round trip), and a file checkpointer names its directories
by percent-encoding the characters outside[A-Za-z0-9_-], reading a
directory an earlier release named lossily while its files record the
thread. (#298) - LiteLLM gateway example: the platform pieces the how-to promised are
wired (#269).examples/litellm-gateway/gainsconfig.platform.yaml
— the gateway ofconfig.yamlplus the OpenTelemetry callback and the
Redis response cache;docker-compose.ymlselects it whenREDIS_URLis
set and starts a redis sidecar under thecacheprofile, with the
Langfuse variables passed through for the alternative callback. Both
configs carry an in-process PII guardrail (LiteLLM's content filter masks
US SSNs and card numbers before the upstream call; Presidio is documented
as the alternative).helm-values.yamlnow uses the keys the chart reads
(environmentSecretsinstead of the ignoredenvFrom, the master key
from the same Secret, an external Postgres without the bundled
StatefulSet). The how-to gains Observability, Caching and Guardrails
sections and the sequence to verify the Helm install on a cluster, which
the maintainers have not run.tests/unit/test_litellm_gateway_example.py
keeps the two configs in step;tests/integration/test_litellm_gateway_platform.py
drives the guardrail and the cache against a live gateway. RequestClassifierandProtocolPicker, the router's two seams.
Router(classifier=...)takes anyasync classify(text) -> GoalFramein
place of the extractor agent, which is now wrapped in
AgentFrameExtractor, the default implementation of the same protocol;
CognitiveCompiler(protocol_picker=...)takes anyProtocolPicker, of
whichLLMProtocolPickeris the one that ships. Behaviour is unchanged
by default. (#342)- Router: LOW-complexity requests go to
direct_responsebefore any
goal gate. A frame atComplexity.LOW...
v5.6.0
Added
on_request/on_responseon the HTTP-backed OCI models.
OCIResponsesModelandOCIChatCompletionsModel(and their configs)
take a pair of sync callables that see each outgoinghttpx.Request
after signing and eachhttpx.Responseas its headers arrive — the seam
for request-shape tests and for seeing what goes on the wire when
debugging, where reaching intomodel._http_client()to attach httpx
event hooks was the only way. Both areNoneby default and install
nothing;model_kwargscarries them through theoci:factory.- Time travel on every checkpointer.
checkpointer.list(thread_id)
describes a thread's checkpoints newest first asCheckpointInfo
records (id, write time, the state's iteration, the checkpoint's size
as that backend stores it, the checkpoint it descends from —None
only for a thread's first — and, for a fork, the thread it came from);
checkpointer.fork(thread_id, checkpoint_id)starts a new thread from
any of them, with the thread's tool-effect ledger copied up to that
step and no further, so a run on the fork never replays what the
parent did past the fork point;agent.run(..., from_checkpoint=...),
arun,run_syncandagent.resume(..., from_checkpoint=...)
continue a thread from a past checkpoint, the run's first lasting save
recording it as its parent and the rest following on, so the thread's
history shows the branch as a chain; the checkpoint run from is never
deleted.Agent.forkandStateGraph.aforkgo through the
checkpointer'sfork. EveryBaseCheckpointerhas the surface through
the base defaults; the in-memory, file, adapter-wrapped (Redis,
PostgreSQL, MySQL, OpenSearch, Oracle), S3, OCI Object Storage and
PgCheckpointerbackends read the step fields without loading the
state, and the versionedOracleCheckpointSaver(the reference, one
row per checkpoint with a parent link) gainsforkandlisttoo.
max_checkpoints_per_threadonMemoryCheckpointer,S3Backend,
OCIBucketBackend,StorageBackendAdapterand the*_checkpointer()
factories bounds a thread's history (FileCheckpointerand
PgCheckpointeralready had one); no bound ever trims a ledger
sidecar, and the object-store backends order checkpoints saved within
one second by the write time in their own metadata, not the listing's
coarse modification time.draw_mermaid_history(checkpointer, *thread_ids)andStateGraph.adraw_mermaid_historydraw the
histories with a fork as a branch of its parent (node ids stay
distinct for thread ids that differ only in punctuation; labels escape
Mermaid's specials). The checkpointers page has the per-backend table;
notebook 50 forks a thread on the in-memory checkpointer.
(locus.memory.time_travel; #454) SandboxBackend: the harness workspace as a documented protocol. Every
harness backend now implements it overWorkspaceBackend: a lifecycle
(state,start(),stop(),close(), each idempotent), declared
ResourceLimits(amax_exec_sis enforced by clamping everyexec
timeout), andadd_exec_hook(), which hands anExecRecordof every
command the backend runs to whoever holds it — after the command, so a
hook that raises is logged and the result still reaches the caller.
SandboxMixingives a backend of your own all of it by overriding
_start,_stopand_destroy.
locus.harness.testing.assert_backend_conformance(factory)
is the conformance kit: the file, shell, deadline, background-command and
protocol checks the tools assume, run on a backend and reported together;
run_conformance(backend)does the same without closing it.SSHSandboxBackend. Any host withsshdas a workspace (thessh
extra,paramiko): commands run under a watchdog on the host so a deadline
kills the process group where it runs, both streams come back in order,
files move over SFTP with acatfallback that checks the byte count,
host keys are checked againstknown_hostsor a pinnedhost_key=(a key
accepted underknown_hosts="accept-unknown"stays in memory; the user's
file is never written), andvia=SSHJump(...)connects through a bastion.OCIContainerInstanceBackend. An OCI Container Instance as the
Oracle-native remote sandbox (theoci-containerextra):create()
provisions the instance from an image withsshdor a package manager,
bootstrapssshdwith a key pair generated for the backend, reads the
container's host keys from its log and connects with them pinned, directly
or through an OCI Bastion port-forwarding session for a private subnet
(bastion_session_ttl=sets its lifetime; a restart past it makes a new
one). A container or bastion that reports no host key is refused unless
known_hosts="accept-unknown"is passed.stop()/start()restart the
instance andclose()deletes it and the session.E2BBackendandDaytonaBackend. Thin adapters over the two hosted
sandbox services' Python clients (thee2banddaytonaextras), checked
with stand-ins; the live tests run when the service's API key is set.SandboxSpecandopen_sandbox(). A sandbox named in configuration:
backend="local" | "ssh" | "oci-container" | "oci-sandbox" | "openshell" | "e2b" | "daytona" | "memory"plusroot,env,limits, a
WarmPoolHintand the backend'soptions;from_mapping()reads it from
a parsed YAML or JSON document and refuses unknown keys;
register_backend()adds a name.SandboxPool/open_pool(spec)keep
warm_pool.readysandboxes created ahead of need, and the hint'sname
reaches a service-side pool (OCI GenAI Sandbox warm pools). The new
sandbox backends page documents the protocol,
the kit and each backend's prerequisites.- Durability modes.
Agent(durability=...), anddurability=on
run,arunandrun_sync, say when a run writes its iteration
checkpoints:"sync"(the default, and what every earlier release did)
awaits each one before the next model call;"async"schedules it and
awaits every pending write before the run's final save;"exit"writes
once at the end of the run. The final save and the save before an
interrupt are awaited in every mode.GraphConfig.durabilitydoes the
same for aStateGraph's per-step saves. Every checkpointer gets the
modes through the protocol; none needed code of its own.
(locus.agent.durability) - Tool-effect ledger. With
durability="async"or"exit"(or
Agent(tool_ledger=True)in any mode) the executor records every
executed tool call in the thread's checkpointer the moment it returns,
keyed by(thread id, step, tool name, canonical arguments), as
checkpoints of the sidecar thread<thread_id>~ledger. A run that
continues the turn after a crash —Agent.continue_turn(thread_id),
the newAgent.resume(invocation_id=..., thread_id=...), or
Agent.run(..., invocation_id=...)under the id the crashed run was
started with — replays a recorded call instead of running the tool
again and runs only the calls with no record;ToolResult.replayed
marks a replayed result.continue_turnnow also picks up a turn none
of whose checkpoints landed, from the ledger's manifest. Tools not
marked idempotent run at least once;Agent(rerun_idempotent_on_replay= True)letsidempotent=Truetools run again on replay instead. The
turn's final save clears the ledger. Temporal and DBOS segments record
into the same ledger, andrun_agent_segment(kind="continue")finishes
an interrupted segment by replaying it. The checkpointers page has an
overhead table for each mode on the in-memory and PostgreSQL
checkpointers. (locus.memory.ledger; #453) - A2A: every binding the specification defines. Next to JSON-RPC,
A2AServerserves the HTTP+JSON binding (POST /message:send,
GET /tasks/{id},POST /tasks/{id}:cancel, the push-config resources,
server-sent events formessage:streamandtasks/{id}:subscribe) on the
same app, and the gRPC binding (lf.a2a.v1.A2AService, all eleven RPCs)
ongrpc_port, behind the newa2a-grpcextra. The card's
supportedInterfaceslists what is on (transports=); every binding lands
in one set of handlers and reports the sameErrorInforeason on a
failure.A2AClient.connect(url, prefer=[...])/from_card(card, ...)
pick a binding from the card in preference order and move to the next one
when an interface is unreachable;binding=selects one outright.
SubscribeToTasknow streams a task's live events after the snapshot. - A2A push notifications.
A2AServer(push_notifications= PushNotificationSettings(...))delivers every status and artifact change
to the webhooks a task registers (inSendMessage's configuration or with
the*TaskPushNotificationConfigmethods), with the token and
Authorizationthe config asks for, retries, and a URL policy that refuses
private addresses unless told otherwise.PushNotificationSignersigns
each body (Ed25519) and publishes the key at/.well-known/jwks.json;
PushNotificationReceiveris the client-side webhook that checks the token
and the signature.send_message(..., push_notification_config=..., blocking=False)returns the task at once and runs it in the background. - A2A interrupt mapping. A run that pauses for a person —
ask_user, or
an approval hold fromgate_tool(on_refusal="interrupt")— surfaces as the
task stateinput-requiredwith the question (or the hold summary) as the
status message. The peer's next message on the task resumes the run through
Agent.resume(); for a hold its first word decides (approve/deny),
recorded on the approval store passed asA2AServer(approvals=...). An
approved hold performs the call once; a denied hold ends the task
rejected. - **`locus a2a card ...
v5.5.0
Added
- Reasoning effort on
OCIResponsesModel.OCIResponsesConfigtakes
reasoning_effort(also a constructor argument), sent as
reasoning={"effort": ...}on bothcomplete()andstream(). A
reasoning_effortcall kwarg, such as an agent'smodel_kwargs,
overrides it for that call. Unset, noreasoningfield is sent, so the
request body is unchanged. Before,reasoning_effortpassed to the
constructor or inmodel_kwargswas dropped without a warning.
Fixed
OCIResponsesModel.stream()error bodies. A non-2xx on the streaming
path was raised ashttpx.ResponseNotRead, because the error body had not
been read when it was classified. The body is read first now, so the typed
exceptions and the server's message surface exactly as oncomplete().
Classification also reads the error'sparamfield, so an envelope that
namesprevious_response_idthere rather than in the message still maps
toOCIResponsesStateLostError.OCIProjectRequiredErroron a 400. The Responses endpoint signals the
project requirement for non-OpenAI models with a 400 naming the
OpenAI-Project/opc-conversation-store-idheader. That is now mapped to
OCIProjectRequiredErrorinstead of a plainRuntimeError.project_ocidreaches the Responses endpoint. It was sent only as
opc-project-id, which the endpoint does not read for this requirement, so
following the exception's advice changed nothing. The OCID now also goes out
asOpenAI-Project; with it a non-OpenAI model answers on/responses.
v5.4.0
Added
- The rubric as data.
locus.evaluation.Rubricnames the dimensions a
judge scores 0-100, each with a weight and a line of guidance, plus
optional letter bands (Rubric.default_grades()offers A 90 / B 75 / C 60
/ D 45 / F 0) and apass_score. The weighted composite, the letter and
the pass are computed by code; missing dimensions count as zero rather
than vanishing from the average.Rubric.revision()hashes the rubric
and the judge prompt so two reports are comparable only when it matches.
Rubrics load from JSON or YAML (Rubric.load). AnEvalCase.rubricmay
be a string, as before, or aRubric. - Typed verdicts with provenance.
Verdictcarriesgrade,
dimensions,issues, the judge's advisoryjudge_reported_passed/
judge_reported_score, and aJudgeProvenance(judge model id, rubric
revision, prompt hash, temperature, seed, channel, token usage,
self_graded).EvalResultexposesgradeand the fullverdict;
EvalReportaddsgrade_distribution. - A structured judge channel with pinned sampling.
LLMJudgesends
temperature=0.0by default, takes an optionalseedandtimeout_s,
and receives the verdict through asubmit_verdicttool call where the
model takes tools (channel="auto"), falling back to a plain-JSON reply;
channel="text"never offers the tool. The response under grading is
delimited and declared as data in the prompt. - The run's own evidence as checks.
EvidenceLedgerlays the run's tool
executions out as rows with stable ids (E0,E1, ...,Pfor the
prompt).EvalCase.require_receiptsfails when a figure, identifier, date
or quoted string in the answer appears in no row;EvalCase.claimsare
confirmed by code when the evidence carries their figures and settled by
the judge otherwise, through asubmit_claim_checkstool call whose
citations are verified against the rows (a quote not in the cited row
downgrades the check tounverifiable);EvalCase.groundingruns the
GSAR audit over the answer and the ledger with the judge model. Results
carryreceipts,claim_checksandgrounding_score. - Control-layer assertions.
EvalCase.forbidden_toolspasses when the
tool never executed, where a call the gate refused did not execute;
EvalCase.expected_refusalspasses when the gate answereddeniedor
held_for_approvalat least once.EvalCase.expected_tool_callsmatches
a call on its arguments (ToolCallExpectation). - Budgets.
EvalCase.max_total_tokensandmax_cost_usdread the run's
metrics; a target that reports none fails the check. - Rubric caps.
Rubric.capsdrop the grade to a ceiling when a
contradicted claim, a missing receipt or an ungrounded answer is found;
the runner applies them after the verdict and recordscaps_applied. - Repeats.
EvalRunner(repeats=)orarun(cases, repeats=)reads every
case several times. A case passes only when every graded reading passed
(pass^k), the reading shown is the most pessimistic,EvalResult.samples
keeps them all, andEvalResult.consistencyflags a case whose readings
disagreed by more than the gate; the report countsunstablecases and
the summary printspass k/n. - Judge panels and second opinions.
EvalRunner(judges=[...])grades
every judged answer with each judge; the first scores the case,
EvalResult.panelrecords the panel's agreement andEvalResult.trust
the decision between the first two judges (trusted,
calibration_required,rejected), which the summary prints. - Pairwise comparison in both orders.
LLMJudge.compareasks which of
two answers better satisfies the rubric, once in each order; a preference
that flips with the position is atiewithconsistent=False. locus.evaluation.reliability. Pure functions over verdicts and grade
pairs:consistency,panel_agreement,trust_decision,cohen_kappa,
calibration_drift,wilson_interval,bootstrap_ciand
publication_gates.- Comparable reports. Every
EvalReportcarries afingerprintof the
cases it measured (suite_fingerprint),by_tagcounts,check_failures,
the judge models and rubric revisions seen, andsave/load/
to_markdown.diff_reportscompares two reports case by case (regressed,
improved, added, removed, score and dimension deltas, newly failing
checks) and refuses two different suites unless forced.EvalGateis the
rule a build applies (pass rate, average, not graded, unstable, and
against a baseline no regressions or a bounded average drop), reporting
every reason it failed. - Cases as data.
load_casesreads a JSON, JSONL or YAML file of cases,
with a top-level rubric applied to cases that name none;dump_cases
writes one back. locus eval.runloads cases and an agent (and optionally a judge
and a rubric), prints the report, saves it and exits with the gate's
verdict;diff,gateandsummarywork on saved reports, with
--markdowntables for pull-request comments. How-to: Evaluate an agent
in CI.- Notebook 56 now covers the rubric with a judge, receipts, repeats and
a saved, diffed, gated pair of reports.
Changed
- A judge that returns no verdict leaves the case not graded. An empty
reply, prose without JSON, a call to another tool or no scored dimension
isVerdict(abstained=True). The result carriesnot_graded_reason, the
report counts it underEvalReport.not_gradedand leaves it out of
failedandavg_score, and the summary prints[NOT GRADED]with the
reason. Thejudge_unparseable:...check is still recorded, so nothing
that used to be visible is hidden. - Self-graded suites are named. When the judge model id equals the
model under test,provenance.self_gradedis stamped and the report
summary ends with a warning. The case is not failed for it.
v5.3.2
Fixed
- The
locus.testingdoubles report a context window, so an agent built on
ScriptedModel,FunctionModelorCompromisedModelcounts tokens as it
does for a provider instead of warning that no window is known for model
<unnamed>.context_window=shrinks it for a compaction test;None
keeps the message-window path.
v5.3.1
Fixed
locus codex runpasses the arguments after--to Codex in the order
typed, whichever side of--the prompt is on;-- -m <model> "task"
used to reach Codex scrambled.--helpnames the Codex profile file
(~/.codex/<name>.config.toml) correctly.- The retrieval scenario's check in
codex/scenarios/accepts
make_retriever()as a plain function or as a coroutine.
v5.3.0
Added
- Codex scenarios.
codex/scenarios/is a series of twelve tasks Codex
builds from the Locus skill alone, each with aPROMPT.mdand acheck.sh
that runs in the project Codex built: a gated refund with its audit trail,
a hold a person approves and a resumed run, aStateGraphfan-out, a
retrieval tool, the coding harness behind the gate, a checkpointed
conversation, an agent served over HTTP, an orchestrator with specialists,
a typed answer with a termination rule and an evaluation, an agent on OCI
Generative AI, the permission rules of a coding agent, and a playbook with
a custom hook.python codex/scenarios/run.pyruns them in empty
directories throughlocus codex run --execand prints a summary table;
--locus-installpoints Codex at a checkout, so a change to the SDK or the
skill is tried the way an application would use it. The skill gains a fifth
reference,extending-and-advanced.md(subagents, voice sessions, external
hooks, tool sandboxes, custom model providers, the ReAct loop, core
protocols and settings, DeepAgent internals, graph evaluation, the remaining
router, memory and observability surface), the four existing references
name the rest of each package's public surface, and
tests/docs/test_codex_skill.pymeasures that coverage against every
package's__all__so it cannot regress. - Codex builds on Locus. The repository ships a Codex skill,
.agents/skills/locus/: aSKILL.mdthat gives a coding agent the shape
of the SDK (the agent and its tools, the admission gate, the shapes,
memory and RAG, the harness, the providers, offline tests) and four
reference files with every option, each snippet checked against the
installed SDK bytests/docs/test_codex_skill.py. The wheel carries the
skill, andlocus codexplaces and uses it:initputs it in a
project's.agents/skills/locuswith a Locus section inAGENTS.md, or
in~/.agents/skillswith--home;runinstalls it where it is missing
and starts Codex with the sandbox settings its recipes need (--exec,
--codex-profile, and anything after--go to Codex);pathprints
the bundled copy.examples/codex-on-oci/is a loopback LiteLLM gateway
that signs Codex's own model calls with an OCI profile, so Codex runs on
OCI Generative AI and needs no account elsewhere. The how-to page and the
README section describe all three.
Fixed
-
OCI_REGIONselects the region foroci:model strings. The provider
guide and the environment-variables page said so; the factory behind
Agent(model="oci:...")only readOCI_PROFILEand sent every request
to the default region. It now takesLOCUS_OCI_REGION, then
OCI_REGION, when neitherregion=norbase_url=is given; the
default staysus-chicago-1. -
The harness examples decide by label. The
ControlPolicyshown with
build_harness(..., wrap=gate_tool)on the README, the landing page and the
harness pages now setsrequire_verification_score=0.0; with the default
score every harness call, reads included, was held for a person because no
verification verdict accompanies a workspace tool call.
Install: pip install "locus-sdk[oci]". The full changelog is in CHANGELOG.md.
locus-sdk 5.2.0 — Oracle Agentic Harness SDK: OCI GenAI Sandboxes as a coding-harness workspace, the OCI tool-call-only turn fix, a2a-mesh on A2A v1.0
Added
- OCI GenAI Sandboxes as a coding-harness workspace.
locus.harness.OCISandboxBackendruns the harness tools in an OCI
Enterprise AI sandbox (pip install "locus-sdk[oci-sandbox]",oci
2.189.0+).create(project_id, ...)makes a sandbox and deletes it on
close();connect(sandbox_id, ...)attaches to one;extend()adds
lifetime. Commands stream with their output order kept, run under an
in-sandbox deadline, and return at most 900 kB of output, because the
service loses larger output. Background state lives in
/workspace/.locus-harness(/tmpis read-only there), now in
SKIP_DIRS.
Changed
-
locus-sdk-securityships from the repository, not from PyPI. The
5.1.0 notes said the release workflow publishes it; the upload needs a
PyPI project that does not exist, and the package is one install line
from the repository at the matching tag, so the workflow publishes
locus-sdkalone again and the install instructions say so. -
Documentation site: the coding harness has its own section, and the
site reads on a phone. Concepts gains a "The coding harness" group with
an overview and one page each for OCI GenAI Sandboxes and NVIDIA OpenShell;
the home page names the sandbox in its hero, in the Oracle Cloud grid and
in the harness grid with an end-to-end snippet. Every page was re-laid for
360 to 768 px: the title gets the full column with the page actions on
their own row, diagrams fit the column and expand full-screen at their
design width, tables that cannot be read at phone width render as cards,
filter inputs are 16 px so iPhone Safari does not zoom, and touch targets
are finger-sized. The header shows the released version from the build
instead of a badge image that could be served stale from a cache.
Fixed
- OCI Generative AI, OpenAI-compatible transport: a tool-call-only
assistant turn no longer breaks the conversation. Such a turn has no
text; OpenAI accepts"content": nullfor it, OCI's endpoint answers
400 Invalid type for 'messages[n].content': expected an object, but got null, and since the history is replayed on every later turn one tool call
ended the run. The transport now sends""for every vendor on OCI. - Cognitive router: a capability listed twice compiles once. An
extractor that repeats a capability id made the compiler bind the same tool
twice and the agent's registry rejected it (Tool already registered).
Ids are de-duplicated before binding. - The
a2a-meshexample routed no requests, and spoke only the pre-v1.0
surface.A2AClient.get_agent_card()returns v1.0 cards whose skills
areAgentSkillobjects, but the orchestrator matched them as strings, so
every query failed with "No peer advertises skill". The orchestrator now
routes on skill ids, prints each peer'sprotocolVersionand
supportedInterfaces, and talks A2A v1.0 JSON-RPC:SendMessage, with
the reply read from the task's artifacts, andSendStreamingMessagefor
--stream.--legacykeeps the flat/a2a/invokeand/a2a/stream
endpoints to show backwards compatibility. The web console does the same:
it discovers peers from/.well-known/agent-card.json, sends with
SendMessageand renders theSendStreamingMessagetask events. Tests
cover the v1.0 card, both methods and routing on v1.0 skill ids (#274).
locus-sdk 5.1.0 — Oracle Agentic Harness SDK: the cognitive router holds too-risky requests and ranks canonical shapes first, locus-sdk-security on PyPI, the Codex build guide
Added
- Intent meanings in the goal frame.
GoalFrame.primary_goalcarries one
line perTaskType(TASK_TYPE_GUIDE), so an extractor model sees what
separatesplanfrombuildorresearchfromdiagnoseinstead of
thirteen bare names. locus-sdk-securityon PyPI. The release workflow publishes the
security package next tolocus-sdk, sopip install locus-sdk-security
replaces the install-from-repository line; the two stay in lockstep.- Build it with Codex.
codex/SPEC.mdandcodex/PROMPT.mddrive a
coding agent through the Quickstart and the first controlled action from a
clone: a fresh environment, a first agent with a typed tool against the
provider the operator names, the admission gate allowing, holding and
denying, and the rogue-agent challenge, each step with its checkpoint.
AGENTS.mdat the repository root carries the rules a coding agent follows
here. The site gains the how-to page and the README a section;
tests/docs/test_codex_spec.pykeeps the files the specification quotes
identical to the guide pages.
Changed
- Cognitive router: a request too risky for its shape is held, not
refused. When every protocol that handles a frame's intent caps risk
below the frame's, the compiler used to raiseNoMatchingProtocolError:
a HIGH-risk plan, diagnosis or question had nowhere to go. It now compiles
ontoapproval_gated_executionand is always held for approval, whatever
the gate's thresholds;router.explain()reports the choice as
method="risk_fallback".CognitiveCompiler(risk_fallback=None)restores
the error, and a goal no protocol handles still raises. - Cognitive router: canonical fit outranks cost distance when adjacent.
The ranker put cost-to-complexity distance first, so a MEDIUM-complexity
research request landed onhandoff_chain(a coordination shape) and a
HIGH-complexity coordination onspecialist_fanout. A protocol that lists
the goal inprimary_fornow wins whenever its cost is within one step of
the frame's complexity; a LOW-complexity task still never gets a HIGH-cost
shape for being canonical. - Cognitive router:
debateaccepts MEDIUM risk. A debate weighs options
and recommends; it changes nothing. Capped at LOW, a comparison the
extractor rated MEDIUM risk fell through tospecialist_fanout; on the
Frankfurt benchmark that was two of Llama 3.3 70B's seven misses. - Routing benchmark gates on what the router guarantees. The
typed-frame-versus-free-form accuracy comparison is printed as data rather
than asserted: on OCI Generative AI it goes both ways by model (Cohere
Command A beats the free-form baseline, Llama 3.3 70B does not). The
assertions are the structural ones: selections stay in the registered set,
including under prompt injection.
Fixed
locus.testing.tool_callcould not script the harnesswritetool.
The helper reservedcontentfor the assistant's text, so a tool argument
of that name (write(path, content)) was silently dropped and the tool
failed with a missing-argument error.tool_call(name, arguments={...})
now takes the arguments as a mapping, for any tool whose argument is named
like one of the helper's own parameters; keywords still work and win on a
repeated key.
locus-sdk 5.0.0 — Oracle Agentic Harness SDK: OpenShell sandboxes with provider credentials, a local OpenShell gateway, the documentation site redrawn, AWS posture removed
Added
- Sandbox image and OpenShell providers from
OpenShellBackend.create.
image=picks the container image;providers=attaches OpenShell
providers, whose credentials stay at the gateway while the sandbox sees a
placeholder the sandbox proxy swaps in at the provider's endpoints. The
live test exercises OpenShell'soci-genaiprofile: a sandboxedcurl
reaches OCI Generative AI without the key.examples/openshell-gateway/ provider.pyimports a profile and creates a provider where the OpenShell
CLI is not installed. - A local NVIDIA OpenShell gateway for the coding harness.
examples/openshell-gateway/starts the gateway withdocker compose up -d
(loopback, Docker-outside-of-Docker, adapted from NVIDIA's reference
deployment) soOpenShellBackendand the live harness tests run on any
machine with Docker;LOCUS_OPENSHELL_ENDPOINT=127.0.0.1:8080points at it.
The README lists the one host requirement (Landlock in the kernel's active
LSM list). The live tests name their sandboxes within OpenShell's
19-character limit.
Changed
-
CloudSource.describe/eventstake a keyword-onlyclient. OCI
services expose several SDK clients (corealone has five), so the
SecurityContext().cloudport names one; when omitted it resolves the
service's only client and otherwise returns anerrordict listing them.
Third-partyCloudSourceproviders should accept the new keyword. -
Documentation site: diagrams instead of ASCII, and a Markdown twin of
every page. The sixteen diagrams the site drew as text inside code blocks
(the provider tree, the OCI transports, the memory layers, the admission
gates in notebooks 72–75, the incident-response, concession and contract
workflows, the EventBus, the audio pipelines, in-database embeddings and
scatter-gather) are SVGs drawn from the SDK source, themed with the page,
and checked against the code. The Memory page's five-column table that
wrapped class names mid-token is a diagram plus a prose table, and
identifiers in any table no longer break mid-token. Build facts and
requirements show as a row of tiles rather than key/value tables. The
colour scheme follows the operating system on first visit, with a
three-way toggle; pages carry previous/next links, edit and view-source
actions, and a Copy page button that copies the page as Markdown.
Every page is also published as Markdown at<page>/index.md, with
/llms.txtand/llms-full.txtfor tools that read the site that way
(hooks/llms_txt.py). The captured output on the cloud-resource gate,
red-team and SOC-triage notebook pages is refreshed to what the examples
print today, and the cloud-resource gate page now describes all three
attempts its example runs. -
Documentation site: a diagram on every concept page, provider tabs, and
searchable catalogues. Nineteen concept pages gained a diagram drawn from
the SDK source and reviewed against it: the hook lifecycle, the event
taxonomy, the observability pipeline, state flow, checkpointer shapes,
streaming paths, the termination algebra, the server request flow,
interrupt and resume, the RAG pipeline, context strategies, idempotent
execution, the fallback chain, structured output, Oracle Database 26ai
primitives, the tool pipeline, skills disclosure, playbook enforcement and
the evaluation flow; the older drawings now carry their status words and
pass the same lint. The first generic code block on 31 pages renders as
linked provider tabs (OCI, OpenAI, Anthropic, self-hosted) written once with
{{ locus_model_tabs }}, and the generic example model is an OCI id. The
event catalogues and the environment-variable reference have a filter box
that hides rows and empty sections as you type. Several facts the reviews
surfaced are corrected: the hook lifecycle has nine points, not eight, and
on_before_compactionis in the table;HookRegistryorders providers and
the agent'sHookOrchestratorruns them; three rerankers ship, including
OCICohereReranker; the/resumeroute's behaviour is described as the
code implements it. -
Documentation site: one template for the 89 notebook pages. Each page
shows, in the same order, what the example builds, the diagram of its
shape, the functions that carry the point, how to run it, what it prints
where that is worth reading, and the full source collapsed at the end. A
new build macro,{{ locus_source <file>::<symbol> }}, quotes a function
or class by name so the excerpt follows the code and a renamed symbol
fails the build;tests/docs/test_notebook_pages.pyenforces the template;
scripts/notebook_output.pycaptures the printed trail of every notebook
whose offline run is deterministic and worth reading. Run blocks are fenced
commands with the provider sentence that is true for each notebook. -
Documentation site: home page. The three card grids (shapes, Oracle
Cloud, harness) open with a small drawing of the pattern each card is about
instead of a generic icon; a "What are you building?" section offers four
tabs (support bot, incident response, contract review, SOC alert triage),
each a short snippet linked to the notebook that runs it in full; "Your
first agent" switches providers with the site's tabs while the hero keeps
one literal OCI call; the notebook sidebar nests its topic groups so a
notebook page fits the viewport; and the Markdown twins drop the glyph
markup. Page copy is corrected where it had drifted from the code: the
Responses transport is opt-in throughOCIResponsesModel, not chosen by
region, and product names are written in full.
Removed
- AWS cloud-posture tools.
locus_security.aws(describe_aws,use_aws
and their@toolwrappers), theawsextra on both packages and the
LOCUS_AWS_*variables are gone; Locus targets OCI first. The cloud-posture
capability stays, on the core OCI tools:create_soc_analyst,
SecurityControls,SecurityContext().cloud, thecloud_posture_audit
playbook andsecurity_toolset(oci=True)drivedescribe_oci/use_oci
(read-only by default), andSecurityControlscarries the OCIprofile,
auth_type,regionandcompartment_idthe review runs as.
S3-compatible object storage —S3Backendand thes3extra — is
unaffected: it is how OCI Object Storage is reached.