Skip to content

Releases

v6.0.0

Choose a tag to compare

@fede-kamel fede-kamel released this 17 Nov 22:38
d7e7dbe

Added

  • Router benchmark harness. The routing corpus is a file of EvalCase
    objects (benchmarks/router/cases.json, tagged labelled, shape:<id>,
    trap, injection, ambiguous) and locus.router.benchmark adapts
    selection to EvalRunner's contract: a typed target that takes any
    RequestClassifier in the router's front seam, a free-form baseline that
    may name an unregistered id, and router_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 (regressions lists the cases either way). Every target
    answers a protocol id, unbounded or refused, and retries a transient
    provider error before refusing; nothing is built or run.
    scripts/router_benchmark.py runs it against a model and stores the
    reports; tests/integration/test_router_classifier_gate.py is the same
    gate behind RUN_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, and await cp.expire() removes what has
    expired and returns the count. Redis gets its own EXPIRE on 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
    PgCheckpointer keep an expires_at column, added to an existing table
    by the first save made with a ttl — 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 a key_provider callable for a vault fetch, previous_keys for
    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 to save() — stay in the clear so list() 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=…), also arun, run_sync, resume, continue_turn) stores a
    thread under app=<app_id>/user=<user_id>/<thread_id> — a key, directory
    or object prefix, the thread_id column's prefix on SQL — so the same
    thread_id under 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, with scope=None
    inheriting the checkpointer's scope and CheckpointScope() explicitly
    unscoped; list_threads(scope=) lists one scope, and unscoped data stays
    reachable with no scope. (#298)
  • python -m locus.runner takes its workspace from LOCUS_WORKSPACE when
    set, for a runner started outside an OpenShell sandbox (a gateway's local
    box driver, a CI job); unset, it works on /sandbox as 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 --markdown and GateResult.to_markdown(). The
    gate's verdict as Markdown with one table row per failed check, for a
    pull-request comment, the way eval diff and eval summary already
    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 a VECTOR(n) column, a JSON metadata
    column and a FULLTEXT index on the content; the store mirrors
    OracleVectorStore's surface (add, add_batch, get, delete,
    search, count, clear, close) plus hybrid_search, which blends
    DISTANCE() similarity with MATCH ... AGAINST relevance client-side the
    way the Elasticsearch store does. It probes the server once: HeatWave
    MySQL computes and orders by DISTANCE() on the server
    (server_side_distance=True); community MySQL 9+ has the VECTOR type
    but no DISTANCE(), so the store fetches up to candidate_limit rows and
    ranks them here. Metadata filters are JSON_EXTRACT equality 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. New heatwave extra (the same
    mysql-connector-python the mysql checkpoint extra installs), lazy
    export from locus.rag.stores, docs rows and a HeatWave vs community
    MySQL section, and the shared conformance suite behind HEATWAVE_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 the AuditReport each yields,
    policy documents with their hash, lint findings and decisions, malformed
    documents with the error key, approval digests, ids and decision
    sequences, and the exact action-admission line an admission writes.
    scripts/conformance_export.py regenerates them from a fixed clock and
    fixture keys; a unit test fails on any difference, so a format change is a
    deliberate v2. 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 to True.
    Every tool call is signed as the model's response is parsed and verified
    before it runs, so a hook that rewrites event.arguments must call
    event.resign(by="MyHook") or the call is refused with a
    ToolCallIntegrityError; the built-in GuardrailsHook redaction and
    ExternalHooks rewrites already do. Pass Agent(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 form app=… or user=… (or beginning app% /
    user%) on a checkpointer with no scope= is now stored
    percent-encoded (user=alice/chat as user%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 through CheckpointScope(user_id="alice")
    (the bare id parses as that scope's thread chat) or rename it before
    upgrading. Every other unscoped id keeps its bare stored form. The
    adapter's exists() 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/ gains config.platform.yaml
    — the gateway of config.yaml plus the OpenTelemetry callback and the
    Redis response cache; docker-compose.yml selects it when REDIS_URL is
    set and starts a redis sidecar under the cache profile, 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.yaml now uses the keys the chart reads
    (environmentSecrets instead of the ignored envFrom, 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.
  • RequestClassifier and ProtocolPicker, the router's two seams.
    Router(classifier=...) takes any async classify(text) -> GoalFrame in
    place of the extractor agent, which is now wrapped in
    AgentFrameExtractor, the default implementation of the same protocol;
    CognitiveCompiler(protocol_picker=...) takes any ProtocolPicker, of
    which LLMProtocolPicker is the one that ships. Behaviour is unchanged
    by default. (#342)
  • Router: LOW-complexity requests go to direct_response before any
    goal gate.
    A frame at Complexity.LOW ...
Read more

v5.6.0

Choose a tag to compare

@fede-kamel fede-kamel released this 17 Nov 00:45
5d92ff0

Added

  • on_request / on_response on the HTTP-backed OCI models.
    OCIResponsesModel and OCIChatCompletionsModel (and their configs)
    take a pair of sync callables that see each outgoing httpx.Request
    after signing and each httpx.Response as its headers arrive — the seam
    for request-shape tests and for seeing what goes on the wire when
    debugging, where reaching into model._http_client() to attach httpx
    event hooks was the only way. Both are None by default and install
    nothing; model_kwargs carries them through the oci: factory.
  • Time travel on every checkpointer. checkpointer.list(thread_id)
    describes a thread's checkpoints newest first as CheckpointInfo
    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_sync and agent.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.fork and StateGraph.afork go through the
    checkpointer's fork. Every BaseCheckpointer has the surface through
    the base defaults; the in-memory, file, adapter-wrapped (Redis,
    PostgreSQL, MySQL, OpenSearch, Oracle), S3, OCI Object Storage and
    PgCheckpointer backends read the step fields without loading the
    state, and the versioned OracleCheckpointSaver (the reference, one
    row per checkpoint with a parent link) gains fork and list too.
    max_checkpoints_per_thread on MemoryCheckpointer, S3Backend,
    OCIBucketBackend, StorageBackendAdapter and the *_checkpointer()
    factories bounds a thread's history (FileCheckpointer and
    PgCheckpointer already 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) and StateGraph.adraw_mermaid_history draw 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 over WorkspaceBackend: a lifecycle
    (state, start(), stop(), close(), each idempotent), declared
    ResourceLimits (a max_exec_s is enforced by clamping every exec
    timeout), and add_exec_hook(), which hands an ExecRecord of 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.
    SandboxMixin gives a backend of your own all of it by overriding
    _start, _stop and _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 with sshd as a workspace (the ssh
    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 a cat fallback that checks the byte count,
    host keys are checked against known_hosts or a pinned host_key= (a key
    accepted under known_hosts="accept-unknown" stays in memory; the user's
    file is never written), and via=SSHJump(...) connects through a bastion.
  • OCIContainerInstanceBackend. An OCI Container Instance as the
    Oracle-native remote sandbox (the oci-container extra): create()
    provisions the instance from an image with sshd or a package manager,
    bootstraps sshd with 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 and close() deletes it and the session.
  • E2BBackend and DaytonaBackend. Thin adapters over the two hosted
    sandbox services' Python clients (the e2b and daytona extras), checked
    with stand-ins; the live tests run when the service's API key is set.
  • SandboxSpec and open_sandbox(). A sandbox named in configuration:
    backend="local" | "ssh" | "oci-container" | "oci-sandbox" | "openshell" | "e2b" | "daytona" | "memory" plus root, env, limits, a
    WarmPoolHint and the backend's options; 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.ready sandboxes created ahead of need, and the hint's name
    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=...), and durability= on
    run, arun and run_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.durability does the
    same for a StateGraph'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 new Agent.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_turn now 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) lets idempotent=True tools run again on replay instead. The
    turn's final save clears the ledger. Temporal and DBOS segments record
    into the same ledger, and run_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,
    A2AServer serves the HTTP+JSON binding (POST /message:send,
    GET /tasks/{id}, POST /tasks/{id}:cancel, the push-config resources,
    server-sent events for message:stream and tasks/{id}:subscribe) on the
    same app, and the gRPC binding (lf.a2a.v1.A2AService, all eleven RPCs)
    on grpc_port, behind the new a2a-grpc extra. The card's
    supportedInterfaces lists what is on (transports=); every binding lands
    in one set of handlers and reports the same ErrorInfo reason 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.
    SubscribeToTask now 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 (in SendMessage's configuration or with
    the *TaskPushNotificationConfig methods), with the token and
    Authorization the config asks for, retries, and a URL policy that refuses
    private addresses unless told otherwise. PushNotificationSigner signs
    each body (Ed25519) and publishes the key at /.well-known/jwks.json;
    PushNotificationReceiver is 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 from gate_tool(on_refusal="interrupt") — surfaces as the
    task state input-required with 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 as A2AServer(approvals=...). An
    approved hold performs the call once; a denied hold ends the task
    rejected.
  • **`locus a2a card ...
Read more

v5.5.0

Choose a tag to compare

@fede-kamel fede-kamel released this 16 Nov 14:53
8b1faf2

Added

  • Reasoning effort on OCIResponsesModel. OCIResponsesConfig takes
    reasoning_effort (also a constructor argument), sent as
    reasoning={"effort": ...} on both complete() and stream(). A
    reasoning_effort call kwarg, such as an agent's model_kwargs,
    overrides it for that call. Unset, no reasoning field is sent, so the
    request body is unchanged. Before, reasoning_effort passed to the
    constructor or in model_kwargs was dropped without a warning.

Fixed

  • OCIResponsesModel.stream() error bodies. A non-2xx on the streaming
    path was raised as httpx.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 on complete().
    Classification also reads the error's param field, so an envelope that
    names previous_response_id there rather than in the message still maps
    to OCIResponsesStateLostError.
  • OCIProjectRequiredError on a 400. The Responses endpoint signals the
    project requirement for non-OpenAI models with a 400 naming the
    OpenAI-Project / opc-conversation-store-id header. That is now mapped to
    OCIProjectRequiredError instead of a plain RuntimeError.
  • project_ocid reaches 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
    as OpenAI-Project; with it a non-OpenAI model answers on /responses.

v5.4.0

Choose a tag to compare

@fede-kamel fede-kamel released this 10 Nov 22:10
18d6724

Added

  • The rubric as data. locus.evaluation.Rubric names 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 a pass_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). An EvalCase.rubric may
    be a string, as before, or a Rubric.
  • Typed verdicts with provenance. Verdict carries grade,
    dimensions, issues, the judge's advisory judge_reported_passed /
    judge_reported_score, and a JudgeProvenance (judge model id, rubric
    revision, prompt hash, temperature, seed, channel, token usage,
    self_graded). EvalResult exposes grade and the full verdict;
    EvalReport adds grade_distribution.
  • A structured judge channel with pinned sampling. LLMJudge sends
    temperature=0.0 by default, takes an optional seed and timeout_s,
    and receives the verdict through a submit_verdict tool 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. EvidenceLedger lays the run's tool
    executions out as rows with stable ids (E0, E1, ..., P for the
    prompt). EvalCase.require_receipts fails when a figure, identifier, date
    or quoted string in the answer appears in no row; EvalCase.claims are
    confirmed by code when the evidence carries their figures and settled by
    the judge otherwise, through a submit_claim_checks tool call whose
    citations are verified against the rows (a quote not in the cited row
    downgrades the check to unverifiable); EvalCase.grounding runs the
    GSAR audit over the answer and the ledger with the judge model. Results
    carry receipts, claim_checks and grounding_score.
  • Control-layer assertions. EvalCase.forbidden_tools passes when the
    tool never executed, where a call the gate refused did not execute;
    EvalCase.expected_refusals passes when the gate answered denied or
    held_for_approval at least once. EvalCase.expected_tool_calls matches
    a call on its arguments (ToolCallExpectation).
  • Budgets. EvalCase.max_total_tokens and max_cost_usd read the run's
    metrics; a target that reports none fails the check.
  • Rubric caps. Rubric.caps drop 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 records caps_applied.
  • Repeats. EvalRunner(repeats=) or arun(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, and EvalResult.consistency flags a case whose readings
    disagreed by more than the gate; the report counts unstable cases and
    the summary prints pass k/n.
  • Judge panels and second opinions. EvalRunner(judges=[...]) grades
    every judged answer with each judge; the first scores the case,
    EvalResult.panel records the panel's agreement and EvalResult.trust
    the decision between the first two judges (trusted,
    calibration_required, rejected), which the summary prints.
  • Pairwise comparison in both orders. LLMJudge.compare asks which of
    two answers better satisfies the rubric, once in each order; a preference
    that flips with the position is a tie with consistent=False.
  • locus.evaluation.reliability. Pure functions over verdicts and grade
    pairs: consistency, panel_agreement, trust_decision, cohen_kappa,
    calibration_drift, wilson_interval, bootstrap_ci and
    publication_gates.
  • Comparable reports. Every EvalReport carries a fingerprint of the
    cases it measured (suite_fingerprint), by_tag counts, check_failures,
    the judge models and rubric revisions seen, and save / load /
    to_markdown. diff_reports compares two reports case by case (regressed,
    improved, added, removed, score and dimension deltas, newly failing
    checks) and refuses two different suites unless forced. EvalGate is 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_cases reads 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. run loads cases and an agent (and optionally a judge
    and a rubric), prints the report, saves it and exits with the gate's
    verdict; diff, gate and summary work on saved reports, with
    --markdown tables 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
    is Verdict(abstained=True). The result carries not_graded_reason, the
    report counts it under EvalReport.not_graded and leaves it out of
    failed and avg_score, and the summary prints [NOT GRADED] with the
    reason. The judge_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_graded is stamped and the report
    summary ends with a warning. The case is not failed for it.

v5.3.2

Choose a tag to compare

@fede-kamel fede-kamel released this 02 Nov 18:17
7ed68cc

Fixed

  • The locus.testing doubles report a context window, so an agent built on
    ScriptedModel, FunctionModel or CompromisedModel counts 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

Choose a tag to compare

@fede-kamel fede-kamel released this 02 Nov 15:17
2798add

Fixed

  • locus codex run passes the arguments after -- to Codex in the order
    typed, whichever side of -- the prompt is on; -- -m <model> "task"
    used to reach Codex scrambled. --help names 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

Choose a tag to compare

@fede-kamel fede-kamel released this 30 Oct 16:12
3c4ed60

Added

  • Codex scenarios. codex/scenarios/ is a series of twelve tasks Codex
    builds from the Locus skill alone, each with a PROMPT.md and a check.sh
    that runs in the project Codex built: a gated refund with its audit trail,
    a hold a person approves and a resumed run, a StateGraph fan-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.py runs them in empty
    directories through locus codex run --exec and prints a summary table;
    --locus-install points 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.py measures that coverage against every
    package's __all__ so it cannot regress.
  • Codex builds on Locus. The repository ships a Codex skill,
    .agents/skills/locus/: a SKILL.md that 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 by tests/docs/test_codex_skill.py. The wheel carries the
    skill, and locus codex places and uses it: init puts it in a
    project's .agents/skills/locus with a Locus section in AGENTS.md, or
    in ~/.agents/skills with --home; run installs it where it is missing
    and starts Codex with the sandbox settings its recipes need (--exec,
    --codex-profile, and anything after -- go to Codex); path prints
    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_REGION selects the region for oci: model strings. The provider
    guide and the environment-variables page said so; the factory behind
    Agent(model="oci:...") only read OCI_PROFILE and sent every request
    to the default region. It now takes LOCUS_OCI_REGION, then
    OCI_REGION, when neither region= nor base_url= is given; the
    default stays us-chicago-1.

  • The harness examples decide by label. The ControlPolicy shown with
    build_harness(..., wrap=gate_tool) on the README, the landing page and the
    harness pages now sets require_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

Choose a tag to compare

@fede-kamel fede-kamel released this 29 Oct 19:51
dbb7e59

Added

  • OCI GenAI Sandboxes as a coding-harness workspace.
    locus.harness.OCISandboxBackend runs 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 (/tmp is read-only there), now in
    SKIP_DIRS.

Changed

  • locus-sdk-security ships 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-sdk alone 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": null for 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-mesh example routed no requests, and spoke only the pre-v1.0
    surface.
    A2AClient.get_agent_card() returns v1.0 cards whose skills
    are AgentSkill objects, 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's protocolVersion and
    supportedInterfaces, and talks A2A v1.0 JSON-RPC: SendMessage, with
    the reply read from the task's artifacts, and SendStreamingMessage for
    --stream. --legacy keeps the flat /a2a/invoke and /a2a/stream
    endpoints to show backwards compatibility. The web console does the same:
    it discovers peers from /.well-known/agent-card.json, sends with
    SendMessage and renders the SendStreamingMessage task 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

Choose a tag to compare

@fede-kamel fede-kamel released this 29 Oct 16:29
64724f3

Added

  • Intent meanings in the goal frame. GoalFrame.primary_goal carries one
    line per TaskType (TASK_TYPE_GUIDE), so an extractor model sees what
    separates plan from build or research from diagnose instead of
    thirteen bare names.
  • locus-sdk-security on PyPI. The release workflow publishes the
    security package next to locus-sdk, so pip install locus-sdk-security
    replaces the install-from-repository line; the two stay in lockstep.
  • Build it with Codex. codex/SPEC.md and codex/PROMPT.md drive 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.md at 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.py keeps 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 raise NoMatchingProtocolError:
    a HIGH-risk plan, diagnosis or question had nowhere to go. It now compiles
    onto approval_gated_execution and 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 on handoff_chain (a coordination shape) and a
    HIGH-complexity coordination on specialist_fanout. A protocol that lists
    the goal in primary_for now 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: debate accepts MEDIUM risk. A debate weighs options
    and recommends; it changes nothing. Capped at LOW, a comparison the
    extractor rated MEDIUM risk fell through to specialist_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_call could not script the harness write tool.
    The helper reserved content for 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

Choose a tag to compare

@fede-kamel fede-kamel released this 29 Oct 13:28
77ed06f

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's oci-genai profile: a sandboxed curl
    reaches OCI Generative AI without the key. examples/openshell-gateway/ provider.py imports 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 with docker compose up -d
    (loopback, Docker-outside-of-Docker, adapted from NVIDIA's reference
    deployment) so OpenShellBackend and the live harness tests run on any
    machine with Docker; LOCUS_OPENSHELL_ENDPOINT=127.0.0.1:8080 points 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 / events take a keyword-only client. OCI
    services expose several SDK clients (core alone has five), so the
    SecurityContext().cloud port names one; when omitted it resolves the
    service's only client and otherwise returns an error dict listing them.
    Third-party CloudSource providers 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.txt and /llms-full.txt for 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_compaction is in the table; HookRegistry orders providers and
    the agent's HookOrchestrator runs them; three rerankers ship, including
    OCICohereReranker; the /resume route'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.py enforces the template;
    scripts/notebook_output.py captures 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 through OCIResponsesModel, 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 @tool wrappers), the aws extra 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, the cloud_posture_audit
    playbook and security_toolset(oci=True) drive describe_oci / use_oci
    (read-only by default), and SecurityControls carries the OCI profile,
    auth_type, region and compartment_id the review runs as.
    S3-compatible object storage — S3Backend and the s3 extra — is
    unaffected: it is how OCI Object Storage is reached.