Skip to content

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
· 402 commits to main since this release
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.