chore(docs): add scopes to API reference, architecture, and design patterns
- Add the seven /scopes routes and their schemas to openapi.json, plus the scope/kind fields on chat, representation, session-create, and peer-list schemas; generate the endpoint pages and register a scopes nav group - Add a Scopes subsection and diagram node to the architecture data model - Add scope guidance to design patterns: quick-reference rows, an isolation boundary comparison (workspace / scope / session allowlist), and common mistakes (scope-per-reader, scopes-as-access-control) - Replace the "Underneath the Facade" section in scopes.mdx with behavioral guardrails and pointers to the implementation source Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
ajspig
parent
5cf635f2d6
commit
1b66601b30
|
|
@ -213,6 +213,18 @@
|
|||
"v3/api-reference/endpoint/sessions/search-session"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "scopes",
|
||||
"pages": [
|
||||
"v3/api-reference/endpoint/scopes/get-or-create-scope",
|
||||
"v3/api-reference/endpoint/scopes/get-scopes",
|
||||
"v3/api-reference/endpoint/scopes/get-scope",
|
||||
"v3/api-reference/endpoint/scopes/add-sessions-to-scope",
|
||||
"v3/api-reference/endpoint/scopes/get-scope-sessions",
|
||||
"v3/api-reference/endpoint/scopes/remove-session-from-scope",
|
||||
"v3/api-reference/endpoint/scopes/get-scope-status"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "messages",
|
||||
"pages": [
|
||||
|
|
|
|||
|
|
@ -0,0 +1,3 @@
|
|||
---
|
||||
openapi: post /v3/workspaces/{workspace_id}/scopes/{scope_id}/sessions
|
||||
---
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
---
|
||||
openapi: post /v3/workspaces/{workspace_id}/scopes
|
||||
---
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
---
|
||||
openapi: post /v3/workspaces/{workspace_id}/scopes/{scope_id}/sessions/list
|
||||
---
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
---
|
||||
openapi: get /v3/workspaces/{workspace_id}/scopes/{scope_id}/status
|
||||
---
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
---
|
||||
openapi: get /v3/workspaces/{workspace_id}/scopes/{scope_id}
|
||||
---
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
---
|
||||
openapi: post /v3/workspaces/{workspace_id}/scopes/list
|
||||
---
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
---
|
||||
openapi: delete /v3/workspaces/{workspace_id}/scopes/{scope_id}/sessions/{session_id}
|
||||
---
|
||||
|
|
@ -20,15 +20,19 @@ Honcho has a hierarchical data model centered around the entities below.
|
|||
|
||||
P <-.->|many-to-many| S
|
||||
|
||||
SC[Scopes] -.->|group| S
|
||||
|
||||
style W fill:#B6DBFF,stroke:#333,color:#000
|
||||
style P fill:#B6DBFF,stroke:#333,color:#000
|
||||
style S fill:#B6DBFF,stroke:#333,color:#000
|
||||
style SM fill:#B6DBFF,stroke:#333,color:#000
|
||||
style SC fill:#FFE0B2,stroke:#333,color:#000
|
||||
```
|
||||
|
||||
- A Workspace has Peers & Sessions
|
||||
- A Peer can be in multiple Sessions and can send Messages in a Session
|
||||
- A Session can have many Peers and stores Messages sent by its Peers
|
||||
- A Scope is a named set of Sessions that bounds recall to just those Sessions
|
||||
|
||||
### <Icon icon="building" /> Workspaces
|
||||
|
||||
|
|
@ -58,6 +62,14 @@ Session-level configuration gives you fine-grained control over perspective-taki
|
|||
|
||||
---
|
||||
|
||||
### <Icon icon="shield-halved" /> Scopes
|
||||
|
||||
Scopes are named sets of sessions that act as visibility boundaries for recall. When a query names a scope, Honcho answers only from what happened in that scope's sessions, while the peer keeps its single unified representation across everything. Use them when one peer's history spans contexts that shouldn't leak into each other--clinical sessions that must not inform a billing assistant, or one human working across multiple tenants.
|
||||
|
||||
A session can belong to any number of scopes (or none), and queries that don't name a scope still see everything. See [Scopes](/v3/documentation/features/advanced/scopes) for how to create them and read through them.
|
||||
|
||||
---
|
||||
|
||||
### <Icon icon="envelope" /> Messages
|
||||
|
||||
Messages are the fundamental units of interaction within sessions. While they typically represent back-and-forth communication between peers, you can also use messages to ingest any information that provides context--emails, documents, files, user actions, system notifications, or rich media content.
|
||||
|
|
|
|||
|
|
@ -23,11 +23,15 @@ Ready to add Honcho to your codebase? The **`/honcho-integration` skill** applie
|
|||
| How does cross-session reasoning work? | Session memory stays local to one session. Peer representations accumulate across every session where the peer is included, and `session.context()` becomes cross-session when you include a peer target. |
|
||||
| Should I set `observe_me: false`? | Yes, for deterministic peers Honcho does not need to model, like bots or tool agents. Still save their messages so other peers have session context. Keep it enabled for users and evolving agents. |
|
||||
| Do I need `observe_others`? | Only when a peer needs its own perspective on another participant, such as in games, multi-agent systems, or parent/subagent workflows. |
|
||||
| When do I need a scope? | When one peer's history spans contexts that must not leak into each other's recall — but you still want one workspace and one unified peer. Group the confidential sessions into a [scope](/v3/documentation/features/advanced/scopes) and pass it at query time. |
|
||||
| Perspectives or scopes? | `observe_others` gives a *participant* its own view of another peer. A scope bounds recall to *where things were said*, for a reader that isn't a participant. If the reader is in the session, use perspectives; if you're fencing off a set of sessions, use a scope. |
|
||||
|
||||
## Workspace Design
|
||||
|
||||
A workspace is a hard isolation boundary. **Default to one workspace per application,** and split only at a real privacy, compliance, or product boundary (e.g. per-tenant SaaS, or a tool that needs intentionally isolated memory). Agents that collaborate over the same product, user, or game state belong in the *same* workspace so each can retrieve what the others produced.
|
||||
|
||||
If what you actually need is "this part of a peer's history shouldn't inform that assistant," don't split the workspace — that severs the peer's identity too. Use a [scope](/v3/documentation/features/advanced/scopes) instead: the peer stays whole, and recall through the scope sees only its member sessions.
|
||||
|
||||
Honcho plugins default to one workspace *per host* (`hermes`, `claude_code`, `cursor`, `opencode`). To unify memory across them, point each at the same workspace — see [Unified Memory Setup](/v3/guides/recipes/unified-memory-setup).
|
||||
|
||||
<Info>
|
||||
|
|
@ -75,6 +79,23 @@ So you can start a session fresh or pull in a peer's long-term memory. [`session
|
|||
|
||||
---
|
||||
|
||||
## Choosing an Isolation Boundary
|
||||
|
||||
Honcho gives you three boundaries at different strengths. Pick the weakest one that solves your problem:
|
||||
|
||||
| Boundary | Strength | Use when |
|
||||
|----------|----------|----------|
|
||||
| **Workspace** | Hard isolation — nothing crosses, including the peer itself | Different products, tenants, or environments |
|
||||
| **[Scope](/v3/documentation/features/advanced/scopes)** | Recall boundary — one peer, but queries through the scope see only its sessions | One peer's contexts must not leak into each other (clinical vs. billing, per-reseller support) |
|
||||
| **Session allowlist** (`sessions=[...]`) | Ad-hoc recall restriction, decided per request | The session set varies per query, or you need a quick boundary without provisioning anything |
|
||||
|
||||
Two things scopes are **not**:
|
||||
|
||||
- **Not authorization.** A workspace key reads any session, scoped or not. A scope constrains queries that name it; it doesn't protect data from queries that don't.
|
||||
- **Not topic filtering.** Scopes bound recall by *where something was said*, not what it's about. A therapy detail mentioned in a billing session lands in the billing scope. If you might ever need a scope boundary, align your session boundaries with your confidentiality boundaries from the start — the session is the unit scopes can enforce.
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
- **Splitting one identity across peer IDs** -- If the same user is `alice`, `alice-discord`, and `alice-cursor`, Honcho builds separate representations. Use one stable peer ID when you want unified memory.
|
||||
|
|
@ -82,6 +103,8 @@ So you can start a session fresh or pull in a peer's long-term memory. [`session
|
|||
- **Separating agents that should collaborate** -- If agents need shared product, customer, or team context, put them in the same workspace. Separate workspaces are hard isolation boundaries.
|
||||
- **Leaving `observe_me` on for assistants** -- Wastes reasoning compute on a peer you control. Deterministic behavior doesn't need to be modeled.
|
||||
- **Turning on `observe_others` everywhere** -- Directional representations are powerful, but they add complexity. Use them when peers need distinct perspectives, not just because a session has multiple peers.
|
||||
- **A scope per reader** -- Scopes should map to real confidentiality boundaries, not to consumers. If every assistant gets its own scope, you've rebuilt workspace fragmentation inside one workspace, and each projection reasons over a thin slice. Fewer, boundary-shaped scopes; many readers can share one.
|
||||
- **Treating scopes as access control** -- A scope bounds *recall*, not *access*. Enforce who may query what in your application layer; use scopes to keep the answers themselves from drawing on out-of-bounds sessions.
|
||||
- **Forgetting `peer_target` on session context** -- `session.context()` defaults to the active session's summary and recent messages, which are session-scoped. It becomes cross-session only through adding a peer_target which includes the peer representation.
|
||||
- **Blocking on processing** -- Messages are processed asynchronously in the background. Don't poll or wait for reasoning to complete before continuing your application flow.
|
||||
|
||||
|
|
@ -94,6 +117,9 @@ So you can start a session fresh or pull in a peer's long-term memory. [`session
|
|||
<Card title="Get Context" icon="messages" href="/v3/documentation/features/get-context">
|
||||
Retrieve formatted context from sessions for your LLM
|
||||
</Card>
|
||||
<Card title="Scopes" icon="shield-halved" href="/v3/documentation/features/advanced/scopes">
|
||||
Bound recall to named sets of sessions
|
||||
</Card>
|
||||
<Card title="Chat Endpoint" icon="comments" href="/v3/documentation/features/chat">
|
||||
Query Honcho about your peers with natural language
|
||||
</Card>
|
||||
|
|
|
|||
|
|
@ -51,10 +51,7 @@ Three consequences worth internalizing:
|
|||
that name it; it does not hide the sessions from requests that don't.
|
||||
|
||||
<Warning>
|
||||
Scopes are a recall boundary, not an authorization boundary. Anyone holding a
|
||||
workspace key can read any session with or without a scope. Enforcing that a
|
||||
given caller *must* go through a given scope is a separate feature (scope-bound
|
||||
API keys) and is not shipped.
|
||||
Scopes are a recall boundary, not an authorization boundary. Access can be scoped by workspace, session, or peer boundaries.
|
||||
</Warning>
|
||||
|
||||
## The Two Arms
|
||||
|
|
@ -359,32 +356,27 @@ Design accordingly: keep the session boundary aligned with the confidentiality
|
|||
boundary you actually care about, since that session boundary is the one scopes
|
||||
can enforce.
|
||||
|
||||
## Underneath the Facade
|
||||
## Guardrails
|
||||
|
||||
The `/scopes` routes are a facade. A scope named `therapy` is a peer named
|
||||
`scope.therapy` that observes its member sessions (`observe_others=true`) and
|
||||
never speaks (`observe_me=false`), marked with `{"kind": "scope"}` in
|
||||
server-controlled internal metadata. That is why the single-scope arm has depth:
|
||||
the scope occupies an observer position, so the deriver and dreamer build a real
|
||||
representation there, exactly as they do for a peer observing another peer — see
|
||||
[Directional Representations](/v3/documentation/features/advanced/directional-representations)
|
||||
for that mechanism.
|
||||
|
||||
You never need this detail to use scopes, but it explains the guardrails:
|
||||
A few behaviors follow from how scopes are built:
|
||||
|
||||
- **The `scope.` prefix is reserved.** Creating a peer, or adding a peer to a
|
||||
session, with a `scope.`-prefixed name is rejected — the prefix contains `.`,
|
||||
which is outside the peer-name charset, so no validated API call can occupy the
|
||||
namespace.
|
||||
- **Scope peers are hidden from peer listings by default.** Pass
|
||||
`kind="scope"` to list only scopes, or `kind="all"` to see both.
|
||||
session, with a `scope.`-prefixed name is rejected.
|
||||
- **Scopes are hidden from peer listings by default.** Pass `kind="scope"` to
|
||||
list only scopes, or `kind="all"` to see both.
|
||||
- **A scope can't be observed.** No representation is formed *of* a scope, so a
|
||||
scope is rejected in any `target` / observed position, including as a dream
|
||||
target.
|
||||
- **Membership is managed only through the scopes surface.** The session
|
||||
add-peers, set-peers, and remove-peers routes reject scope peers and point you
|
||||
add-peers, set-peers, and remove-peers routes reject scope names and point you
|
||||
at `/scopes/{scope_id}/sessions` or the `scopes` field on session create.
|
||||
|
||||
Honcho is open source — if you want to understand how scopes work under the
|
||||
hood, read the implementation:
|
||||
[`src/routers/scopes.py`](https://github.com/plastic-labs/honcho/blob/main/src/routers/scopes.py),
|
||||
[`src/crud/scope.py`](https://github.com/plastic-labs/honcho/blob/main/src/crud/scope.py),
|
||||
and [`src/deriver/scope_backfill.py`](https://github.com/plastic-labs/honcho/blob/main/src/deriver/scope_backfill.py).
|
||||
|
||||
## Limits
|
||||
|
||||
| Limit | Value |
|
||||
|
|
@ -395,3 +387,6 @@ You never need this detail to use scopes, but it explains the guardrails:
|
|||
| Scopes in one `scope` read option | 100 |
|
||||
| Scopes on session create | 100 |
|
||||
| Sessions in a resolved allowlist | 1,000 |
|
||||
|
||||
Full request and response shapes are in the
|
||||
[API reference](/v3/api-reference/endpoint/scopes/get-or-create-scope).
|
||||
|
|
|
|||
|
|
@ -1574,7 +1574,7 @@
|
|||
"get": {
|
||||
"tags": ["sessions"],
|
||||
"summary": "Get Peer Config",
|
||||
"description": "Get the configuration for a Peer in a Session.\n\nMember-read lets a peer-scoped key reach this route, but a peer may only\nread its own per-session config — not a co-member's. Workspace/admin and\nsession-scoped tokens (which already span the whole session) are unaffected.",
|
||||
"description": "Get the configuration for a Peer in a Session.\n\nMember-read lets a peer-scoped key reach this route, but a peer may only\nread its own per-session config \u2014 not a co-member's. Workspace/admin and\nsession-scoped tokens (which already span the whole session) are unaffected.",
|
||||
"operationId": "get_peer_config_v3_workspaces__workspace_id__sessions__session_id__peers__peer_id__config_get",
|
||||
"security": [{ "HTTPBearer": [] }],
|
||||
"parameters": [
|
||||
|
|
@ -2234,6 +2234,319 @@
|
|||
}
|
||||
}
|
||||
},
|
||||
"/v3/workspaces/{workspace_id}/scopes": {
|
||||
"post": {
|
||||
"tags": ["scopes"],
|
||||
"summary": "Get Or Create Scope",
|
||||
"description": "Get a Scope by ID or create a new Scope with the given ID.\n\nReturns 201 when the scope is created and 200 when it already exists.\nA pre-existing peer occupying the scope's reserved internal name is never\nadopted; that conflict returns 409.",
|
||||
"operationId": "get_or_create_scope_v3_workspaces__workspace_id__scopes_post",
|
||||
"security": [{ "HTTPBearer": [] }],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "workspace_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Workspace Id" }
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ScopeCreate",
|
||||
"description": "Scope creation parameters"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/Scope" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/HTTPValidationError" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v3/workspaces/{workspace_id}/scopes/list": {
|
||||
"post": {
|
||||
"tags": ["scopes"],
|
||||
"summary": "Get Scopes",
|
||||
"description": "Get all Scopes for a Workspace. Results are paginated.",
|
||||
"operationId": "get_scopes_v3_workspaces__workspace_id__scopes_list_post",
|
||||
"security": [{ "HTTPBearer": [] }],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "workspace_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Workspace Id" }
|
||||
},
|
||||
{
|
||||
"name": "reverse",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "boolean",
|
||||
"description": "Whether to reverse the order of results",
|
||||
"default": false,
|
||||
"title": "Reverse"
|
||||
},
|
||||
"description": "Whether to reverse the order of results"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/Page_Scope_" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/HTTPValidationError" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v3/workspaces/{workspace_id}/scopes/{scope_id}": {
|
||||
"get": {
|
||||
"tags": ["scopes"],
|
||||
"summary": "Get Scope",
|
||||
"description": "Get a single Scope by ID.",
|
||||
"operationId": "get_scope_v3_workspaces__workspace_id__scopes__scope_id__get",
|
||||
"security": [{ "HTTPBearer": [] }],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "workspace_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Workspace Id" }
|
||||
},
|
||||
{
|
||||
"name": "scope_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Scope Id" }
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/Scope" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/HTTPValidationError" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v3/workspaces/{workspace_id}/scopes/{scope_id}/sessions": {
|
||||
"post": {
|
||||
"tags": ["scopes"],
|
||||
"summary": "Add Sessions To Scope",
|
||||
"description": "Add Sessions to a Scope.\n\nAll named sessions must already exist (404 otherwise). Adding a session that\nis already a member is a no-op. List the resulting membership with\n`POST /scopes/{scope_id}/sessions/list`.\n\nNote: any added session that already has messages triggers an asynchronous\nbackfill-by-copy of its existing documents into the scope; track progress\nvia ``GET /scopes/{scope_id}/status``.",
|
||||
"operationId": "add_sessions_to_scope_v3_workspaces__workspace_id__scopes__scope_id__sessions_post",
|
||||
"security": [{ "HTTPBearer": [] }],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "workspace_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Workspace Id" }
|
||||
},
|
||||
{
|
||||
"name": "scope_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Scope Id" }
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ScopeSessionsAdd",
|
||||
"description": "IDs of the sessions to add to the scope"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"204": { "description": "Successful Response" },
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/HTTPValidationError" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v3/workspaces/{workspace_id}/scopes/{scope_id}/sessions/{session_id}": {
|
||||
"delete": {
|
||||
"tags": ["scopes"],
|
||||
"summary": "Remove Session From Scope",
|
||||
"description": "Remove a Session from a Scope.\n\nNote: documents copied/derived while the session was a member are\nreconciled asynchronously \u2014 the session's explicit copies are soft-deleted\nfrom the scope, dependent derived documents follow (fail-closed), and the\nscope's card is rebuilt from the remaining evidence.",
|
||||
"operationId": "remove_session_from_scope_v3_workspaces__workspace_id__scopes__scope_id__sessions__session_id__delete",
|
||||
"security": [{ "HTTPBearer": [] }],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "workspace_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Workspace Id" }
|
||||
},
|
||||
{
|
||||
"name": "scope_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Scope Id" }
|
||||
},
|
||||
{
|
||||
"name": "session_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Session Id" }
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"204": { "description": "Successful Response" },
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/HTTPValidationError" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v3/workspaces/{workspace_id}/scopes/{scope_id}/sessions/list": {
|
||||
"post": {
|
||||
"tags": ["scopes"],
|
||||
"summary": "Get Scope Sessions",
|
||||
"description": "Get the Sessions that are members of a Scope, paginated.\n\nOrdered by how long each session has been a member: longest-standing member\nfirst, or most recently added first when `reverse` is true.",
|
||||
"operationId": "get_scope_sessions_v3_workspaces__workspace_id__scopes__scope_id__sessions_list_post",
|
||||
"security": [{ "HTTPBearer": [] }],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "workspace_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Workspace Id" }
|
||||
},
|
||||
{
|
||||
"name": "scope_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Scope Id" }
|
||||
},
|
||||
{
|
||||
"name": "reverse",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "boolean",
|
||||
"description": "Whether to reverse the order of results",
|
||||
"default": false,
|
||||
"title": "Reverse"
|
||||
},
|
||||
"description": "Whether to reverse the order of results"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/Page_Session_" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/HTTPValidationError" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v3/workspaces/{workspace_id}/scopes/{scope_id}/status": {
|
||||
"get": {
|
||||
"tags": ["scopes"],
|
||||
"summary": "Get Scope Status",
|
||||
"description": "Get the backfill/reconciliation job status for a Scope.\n\nReturns a per-session map of the backfill job state (pending / completed /\nfailed) with the number of documents copied once complete. Empty when no\nbackfill has ever been enqueued for the scope.",
|
||||
"operationId": "get_scope_status_v3_workspaces__workspace_id__scopes__scope_id__status_get",
|
||||
"security": [{ "HTTPBearer": [] }],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "workspace_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Workspace Id" }
|
||||
},
|
||||
{
|
||||
"name": "scope_id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "title": "Scope Id" }
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/ScopeStatus" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"422": {
|
||||
"description": "Validation Error",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/HTTPValidationError" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v3/workspaces/{workspace_id}/conclusions": {
|
||||
"post": {
|
||||
"tags": ["conclusions"],
|
||||
|
|
@ -2917,6 +3230,20 @@
|
|||
"title": "Filters",
|
||||
"description": "Optional filters to scope recall. This endpoint supports only the 'session_id' key: a session id, a list of session ids, or {\"in\": [...]}. Recall (conclusions and messages) is restricted to the allowlist; unsupported keys are rejected. When session_id is also set, it must be included in the allowlist."
|
||||
},
|
||||
"scope": {
|
||||
"anyOf": [
|
||||
{ "type": "string" },
|
||||
{
|
||||
"items": { "type": "string" },
|
||||
"type": "array",
|
||||
"maxItems": 100,
|
||||
"minItems": 1
|
||||
},
|
||||
{ "type": "null" }
|
||||
],
|
||||
"title": "Scope",
|
||||
"description": "Optional (unprefixed) scope name(s) to confine recall. A single scope answers from the scope's own representation of the target peer: conclusion recall is confined to what the scope observed and message recall to the scope's member sessions. A list of scopes restricts recall to the union of the scopes' member sessions (explicit allowlist, fail-closed: an empty union recalls nothing). Mutually exclusive with `filters` and `session_id`. Requires a workspace- or admin-level key."
|
||||
},
|
||||
"target": {
|
||||
"anyOf": [{ "type": "string" }, { "type": "null" }],
|
||||
"title": "Target",
|
||||
|
|
@ -3174,6 +3501,22 @@
|
|||
"required": ["items", "total", "page", "size", "pages"],
|
||||
"title": "Page[Peer]"
|
||||
},
|
||||
"Page_Scope_": {
|
||||
"properties": {
|
||||
"items": {
|
||||
"items": { "$ref": "#/components/schemas/Scope" },
|
||||
"type": "array",
|
||||
"title": "Items"
|
||||
},
|
||||
"total": { "type": "integer", "minimum": 0.0, "title": "Total" },
|
||||
"page": { "type": "integer", "minimum": 1.0, "title": "Page" },
|
||||
"size": { "type": "integer", "minimum": 1.0, "title": "Size" },
|
||||
"pages": { "type": "integer", "minimum": 0.0, "title": "Pages" }
|
||||
},
|
||||
"type": "object",
|
||||
"required": ["items", "total", "page", "size", "pages"],
|
||||
"title": "Page[Scope]"
|
||||
},
|
||||
"Page_Session_": {
|
||||
"properties": {
|
||||
"items": {
|
||||
|
|
@ -3356,6 +3699,14 @@
|
|||
{ "type": "null" }
|
||||
],
|
||||
"title": "Filters"
|
||||
},
|
||||
"kind": {
|
||||
"anyOf": [
|
||||
{ "type": "string", "enum": ["scope", "all"] },
|
||||
{ "type": "null" }
|
||||
],
|
||||
"title": "Kind",
|
||||
"description": "Which kinds of peers to list. Omitted (default): regular peers only (scope peers are excluded). 'scope': scope peers only. 'all': every peer."
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
|
|
@ -3376,6 +3727,20 @@
|
|||
"title": "Filters",
|
||||
"description": "Optional filters to scope the representation. This endpoint supports only the 'session_id' key: a session id, a list of session ids, or {\"in\": [...]}. When session_id is also set, it must be included in the allowlist."
|
||||
},
|
||||
"scope": {
|
||||
"anyOf": [
|
||||
{ "type": "string" },
|
||||
{
|
||||
"items": { "type": "string" },
|
||||
"type": "array",
|
||||
"maxItems": 100,
|
||||
"minItems": 1
|
||||
},
|
||||
{ "type": "null" }
|
||||
],
|
||||
"title": "Scope",
|
||||
"description": "Optional (unprefixed) scope name(s) to confine the representation. A single scope reads the scope's own representation of the target peer, formed only from the scope's member sessions. A list of scopes restricts the representation to conclusions from the union of the scopes' member sessions (explicit allowlist, fail-closed: an empty union yields an empty representation). Mutually exclusive with `filters` and `session_id`. Requires a workspace- or admin-level key."
|
||||
},
|
||||
"target": {
|
||||
"anyOf": [{ "type": "string" }, { "type": "null" }],
|
||||
"title": "Target",
|
||||
|
|
@ -3542,6 +3907,72 @@
|
|||
"required": ["observer", "dream_type"],
|
||||
"title": "ScheduleDreamRequest"
|
||||
},
|
||||
"Scope": {
|
||||
"properties": {
|
||||
"id": { "type": "string", "title": "Id" },
|
||||
"metadata": {
|
||||
"additionalProperties": true,
|
||||
"type": "object",
|
||||
"title": "Metadata"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"title": "Created At"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": ["id", "created_at"],
|
||||
"title": "Scope",
|
||||
"description": "Scope response \u2014 external view of the peer backing a scope.\n\nThe ``id`` is the unprefixed scope name; the reserved peer-name prefix is\nan internal implementation detail and never surfaces here."
|
||||
},
|
||||
"ScopeCreate": {
|
||||
"properties": {
|
||||
"id": { "type": "string", "minLength": 1, "title": "Id" },
|
||||
"metadata": {
|
||||
"anyOf": [
|
||||
{ "additionalProperties": true, "type": "object" },
|
||||
{ "type": "null" }
|
||||
],
|
||||
"title": "Metadata"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": ["id"],
|
||||
"title": "ScopeCreate",
|
||||
"description": "Schema for creating (or getting) a scope by its unprefixed name."
|
||||
},
|
||||
"ScopeSessionsAdd": {
|
||||
"properties": {
|
||||
"session_ids": {
|
||||
"items": { "type": "string" },
|
||||
"type": "array",
|
||||
"maxItems": 100,
|
||||
"minItems": 1,
|
||||
"title": "Session Ids",
|
||||
"description": "IDs of existing sessions to add to the scope"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"required": ["session_ids"],
|
||||
"title": "ScopeSessionsAdd",
|
||||
"description": "Schema for adding sessions to a scope."
|
||||
},
|
||||
"ScopeStatus": {
|
||||
"properties": {
|
||||
"backfill_status": {
|
||||
"additionalProperties": {
|
||||
"additionalProperties": true,
|
||||
"type": "object"
|
||||
},
|
||||
"type": "object",
|
||||
"title": "Backfill Status"
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"title": "ScopeStatus",
|
||||
"description": "Per-session backfill/reconciliation job status for a scope.\n\n``backfill_status`` maps each session that has had a backfill enqueued to\nits current job state: ``{state, updated_at[, docs_copied]}`` where\n``state`` is ``pending``/``completed``/``failed`` and ``docs_copied`` is\npresent once a backfill completes."
|
||||
},
|
||||
"Session": {
|
||||
"properties": {
|
||||
"id": { "type": "string", "title": "Id" },
|
||||
|
|
@ -3669,6 +4100,18 @@
|
|||
{ "$ref": "#/components/schemas/SessionConfiguration" },
|
||||
{ "type": "null" }
|
||||
]
|
||||
},
|
||||
"scopes": {
|
||||
"anyOf": [
|
||||
{
|
||||
"items": { "type": "string" },
|
||||
"type": "array",
|
||||
"maxItems": 100
|
||||
},
|
||||
{ "type": "null" }
|
||||
],
|
||||
"title": "Scopes",
|
||||
"description": "Optional list of (unprefixed) scope names to add this session to. Each scope is created if it does not exist yet. If the session already has messages, its existing documents are backfilled into the scope asynchronously."
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
|
|
|
|||
Loading…
Reference in New Issue