[adamant-pwn]

Last of four stacked PRs for labeled traversal, on #710.

This PR adds GraphClient.resolve() and GraphClient.traverse() to the Python client, and metagraph/docs/traverse.md. The document covers the routes and the CLI, the request and response schemas, the walk rule, the end reasons, the bounds and what version 1 leaves out of gr/labeled-traversal. An integration test runs the client against a server.

No caller uses the client methods yet: the staging service calls the HTTP routes directly. They give Python users the same access to the experimental routes that search() and align() give to the others.

Co-authored-by: Gunnar Rätsch

🤖 Generated with Claude Code

[cubic-dev-ai]

All reported issues were addressed across 3 files

Architecture diagram

sequenceDiagram
    participant User as Python User
    participant GC as GraphClient
    participant GCJ as GraphClientJson
    participant HTTP as HTTP Layer (_do_request)
    participant Server as Server (--experimental-traverse)
    participant Routes as /resolve, /traverse Routes
    participant Index as Graph Index + Annotation

    Note over User,GC: NEW: Python client methods for labeled traversal

    User->>GC: resolve(sequence, labels/discover, select)
    GC->>GCJ: resolve(sequence, labels, discover, select)
    GCJ->>GCJ: Build payload {sequence, labels|discover, select}
    Note over GCJ: Exactly one of labels/discover
    GCJ->>HTTP: _do_request('resolve', payload)
    HTTP->>Server: POST /resolve
    Server->>Routes: Route request
    Routes->>Index: Resolve labels on sequence
    Index-->>Routes: Support profile + seeds
    Routes-->>Server: JSON response
    Server-->>HTTP: Response
    HTTP-->>GCJ: json_obj
    GCJ-->>GC: Support profile dict
    GC-->>User: Profile with selection

    User->>GC: traverse(seeds, strategy)
    GC->>GCJ: traverse(seeds, strategy)
    GCJ->>GCJ: Build payload {seeds, strategy?}
    GCJ->>HTTP: _do_request('traverse', payload)
    HTTP->>Server: POST /traverse
    Server->>Routes: Route request
    Routes->>Index: Walk seeds under labels
    Index-->>Routes: Extension results per seed
    Routes-->>Server: JSON response
    Server-->>HTTP: Response
    HTTP-->>GCJ: json_obj
    GCJ-->>GC: Results dict
    GC-->>User: Results

    alt Invalid strategy field
        User->>GC: traverse(seeds, {unknown: 1})
        GC->>GCJ: traverse(seeds, strategy)
        GCJ->>HTTP: _do_request('traverse', payload)
        HTTP->>Server: POST /traverse
        Server->>Routes: Validate schema
        Routes-->>Server: HTTP 400
        Server-->>HTTP: Error response
        HTTP-->>GCJ: Raise RuntimeError
        GCJ-->>GC: Exception propagates
        GC-->>User: RuntimeError raised
    end

    Note over User,Index: Routes gated unless server started with --experimental-traverse

Loading

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>