Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,12 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
the namespace → Connect apps, which copies its address (`/mcp/<namespace>`). An agent connected there has the same
tools but sees that namespace alone, whatever else the person who signs it in can read, and a token an app gets for
it opens nothing else in Lens. Off by default ([One namespace's MCP server](docs/mcp.md#one-namespaces-mcp-server)).
- **Chat completions for any app, from one namespace.** A namespace can answer OpenAI's chat completions API at
`/api/v1/namespaces/<namespace>`, so any app that speaks it (with a Lens API key and the model `lens`) gets answers
from the configured model, grounded in that namespace and citing it: `[n]` with a Sources list, `citations` and
`lens.sources`, streamed or not. Its owners pick the read tools the model may use there (none by default: one search,
one model call). Calls count for the namespace's budget. Off by default; turned on under Admin → Namespaces → the
namespace → Connect apps ([Chat completions for any app](docs/api.md#chat-completions-for-any-app)).

## 0.11.0 <small>October 15, 2026</small> {id="0.11.0"}

Expand Down
59 changes: 59 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,10 @@ PATCH /api/v1/namespaces/{name}/collections/{cid}
DELETE /api/v1/namespaces/{name}/collections/{cid}
GET /api/v1/namespaces/{name}/collections/{cid}/members
PUT /api/v1/namespaces/{name}/collections/{cid}/members
GET /api/v1/namespaces/{name}/integrations
PATCH /api/v1/namespaces/{name}/integrations
GET /api/v1/namespaces/{name}/models
POST /api/v1/namespaces/{name}/chat/completions
```

`GET /namespaces` lists the namespaces you have a role in, with their counts and your `role`, and those you see only
Expand Down Expand Up @@ -312,6 +316,61 @@ also queues the `nsfw` step for its videos, documents and images not classified
`queued`. Audited as `namespace.nsfw`. `POST …/nsfw/classify` queues them on its own (editors) and answers the `jobs`.
Both are a 409 where classification is off in the namespace.

`/namespaces/{name}/integrations` says whether the namespace's [own MCP server](mcp.md#one-namespaces-mcp-server)
(`mcp`, at `mcp_url`) and its [chat completions](#chat-completions-for-any-app) (`chat`, at `chat_url`) are on, the
read tools the model may use there (`tools`) and the ones it may be offered (`tool_choices`), for anyone who can read
the namespace. `PATCH` with any of `{mcp, chat, tools}` changes them (owners); what isn't sent stays. A tool that
isn't one of `tool_choices` is a 400. Audited as `namespace.integrations`.

### Chat completions for any app

A namespace can answer OpenAI's chat completions API, so any app that speaks it (a chat app, an automation tool, a
library's OpenAI client) gets answers from the configured model, grounded in that namespace and citing it. Give the app:

- **Base URL**: `https://lens.example.org/api/v1/namespaces/<namespace>` (the app adds `/chat/completions`);
- **API key**: a Lens [API token](authentication.md) (`la_…`; read-only is enough) or an app's OAuth token;
- **Model**: `lens`, the configured model. One of the models people may pick in Lens's chat works too
(`GET …/models` lists them); any other name answers with the configured model.

```bash
curl https://lens.example.org/api/v1/namespaces/family/chat/completions \
-H "Authorization: Bearer la_…" -H "Content-Type: application/json" \
-d '{"model": "lens", "messages": [{"role": "user", "content": "When is the dentist?"}]}'
```

Each request is answered like a question in Lens's chat, from that namespace alone, with what the token's person can
read there:

- the last message is the question (a `user` message), the `user` and `assistant` messages before it the
conversation, and `system` (or `developer`) messages the app's own instructions, which the model reads after Lens's
rules. Pictures and files in a message are left out;
- the namespace's excerpts that best answer it are found and the model answers from them, citing each claim as `[n]`.
With no model set up, the best excerpts come back on their own;
- when the namespace's owners picked tools, the model may first look things up with them, in the namespace. They are
the assistant's tools that only read (`tool_choices`). A model that can't call tools answers from the excerpts and
says so in `lens.notice`;
- when the namespace's [own assistant](assistant.md#a-namespaces-own-assistant) is on, its name and instructions answer.

What it cites comes back three ways, so any app can show it: `[n]` in the text with a **Sources** list of links after
it (left out when the request has a `response_format`), `citations` (the link for `[n]` is the n-th), and
`lens.sources` (`n`, `recording_id`, `title`, `time`, `speaker`, `url`, `cited`). `lens.steps` lists the tools the
model used. With `"stream": true` the answer comes as OpenAI's `chat.completion.chunk` events, ending with
`data: [DONE]`; the last chunk before it carries `finish_reason: "stop"`, `citations` and `lens`. While the tools run,
the stream sends SSE comments, so nothing in between closes it.

It is off until an owner of the namespace turns it on: **Admin → Namespaces →** the namespace **→ Connect apps**,
which also copies the base URL and picks the tools, or `PATCH /namespaces/{name}/integrations` with `{"chat": true}`,
or an agent's `set_namespace_integrations`. Errors come in OpenAI's shape (`{"error": {"message", "type", "code"}}`):
401 `invalid_api_key` without a token, 422 for a body that isn't a request (FastAPI's shape), 404 `not_found` for a
namespace the token's person can't read (or that doesn't exist), 403 `endpoint_off` while it's off, 400
`invalid_messages` with nothing to answer, 429 `insufficient_quota` when the namespace's [budget](budgets.md) or
Lens's overall one is used up, 502 `upstream_error` when the model server fails.

It only reads. Model calls go through the activity ledger and count for the namespace (`space:<id>`), so its budget
covers them. Not yet: the app's own `tools` (they are ignored), `max_tokens`, enforcing a `response_format`, token
counts in `usage`, streaming the tools' answer piece by piece (it comes in one chunk), and what the namespace's
assistant remembers.

### Collections of a namespace

Every asset lives in exactly one collection of its namespace, and collections nest (at most 8 deep, 5000 per
Expand Down
9 changes: 6 additions & 3 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,9 @@ app was given for a namespace's server opens that server and nothing else: not a
the API. A token for Lens or for `/mcp` (and an API token) works on every namespace's own server, seeing only that
namespace there.

For an app that speaks OpenAI's API rather than MCP, the namespace can also answer
[chat completions](api.md#chat-completions-for-any-app), turned on in the same place (Connect apps).

## Tools

| Tool | |
Expand Down Expand Up @@ -90,8 +93,8 @@ namespace there.
| `nsfw_settings` | how [NSFW classification](nsfw.md) works in a namespace: on or off, the threshold, how flagged resources show, and how many are classified, flagged and not classified yet |
| `set_nsfw` | turn NSFW classification on or off, set its threshold and display, for a namespace (owners) or the archive (admins), and optionally classify what's there. Needs a write-scope token |
| `mark_nsfw` | mark a resource NSFW or not by hand, or hand it back to the model's score. Needs a write-scope token and editor access |
| `namespace_integrations` | whether a namespace has [its own MCP server](#one-namespaces-mcp-server) on, and its address |
| `set_namespace_integrations` | turn a namespace's own MCP server on or off. Owners, with a write-scope token |
| `namespace_integrations` | whether a namespace has [its own MCP server](#one-namespaces-mcp-server) and [chat completions](api.md#chat-completions-for-any-app) on, their addresses, and the tools offered there |
| `set_namespace_integrations` | turn a namespace's own MCP server or chat completions on or off, and pick the read tools its chat completions may use. Owners, with a write-scope token |
| `list_files` | a folder of [the graph as files](file-tree.md): your namespaces, then their collections, topics (nested by narrower topics) and entities, each holding its assets' files |
| `read_file` | a text file of that tree (an asset's `.txt` text or `.json` metadata), a page at a time; other files' download link |
| `file_storage` | where Lens keeps its own files (notes' images and attachments) and the connections it could use; `check` tests it. Admins only |
Expand All @@ -117,7 +120,7 @@ which records an undoable change (proposed by default), `undo_graph_change`, `ed
`merge_topics`, `delete_topic` and `undo_topic_change`, which curate entities and topics as an editor does in the web
app (merges and deletes can be undone), `write_note`, which adds a note, `create_podcast`, which
queues an episode, `set_nsfw` and `mark_nsfw`, which change [NSFW classification](nsfw.md) (owners or admins, and
editors), `set_namespace_integrations`, which turns a namespace's own MCP server on or off (owners), `set_file_storage`, which changes where new files are kept (admins), and `set_monitoring` and
editors), `set_namespace_integrations`, which turns a namespace's own MCP server or chat completions on or off (owners), `set_file_storage`, which changes where new files are kept (admins), and `set_monitoring` and
`set_install_settings`, which have the machine change how Lens runs (admins).
Importing stays in the web app and the API.

Expand Down
38 changes: 28 additions & 10 deletions fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -1761,15 +1761,19 @@ def _integrations(ctx: Context, namespace: str, sid: int) -> dict[str, Any]:
"namespace": namespace,
**integrations.profile(ctx.db, sid),
"mcp_url": f"{ctx.web}/mcp/{namespace}",
"chat_url": f"{ctx.web}/api/v1/namespaces/{namespace}",
"tool_choices": [{"name": n, "description": d} for n, d in integrations.tool_choices()],
"settings": f"{ctx.web}/admin/namespaces/{namespace}#connect-apps",
}


@tool(
"namespace_integrations",
"A namespace's own MCP server",
"A namespace's own MCP server and chat completions",
"Whether a namespace has its own MCP server on (mcp), seeing that namespace alone, and its address (mcp_url) to "
"give an agent that should see nothing else. Off unless the namespace's owner turns it on.",
"give an agent that should see nothing else; whether its OpenAI-style chat completions are on (chat), answered "
"from that namespace alone and citing it, with the base URL to give an app (chat_url), and the read tools the "
"model may use there (tools, from tool_choices). Each is off unless the namespace's owner turns it on.",
Arg("namespace", "string", "the namespace (see list_namespaces)", required=True),
)
def namespace_integrations(ctx: Context, namespace: str) -> dict[str, Any]:
Expand All @@ -1778,20 +1782,34 @@ def namespace_integrations(ctx: Context, namespace: str) -> dict[str, Any]:

@tool(
"set_namespace_integrations",
"Turn a namespace's own MCP server on or off",
"Turn on (mcp true) or off a namespace's own MCP server, which sees that namespace alone: agents connected to it "
"read only that namespace, with the roles of the person who signs them in. Owners of the namespace, with a token "
"that has the write scope.",
"Turn a namespace's own MCP server or chat completions on or off",
"Turn on or off a namespace's own MCP server (mcp) or its OpenAI-style chat completions (chat), and pick the read "
'tools the model may use there (tools, from namespace_integrations\' tool_choices; ["none"] for none). Each sees that '
"namespace alone, with the roles of the person who signs the app in. What isn't given stays as it is. Owners of "
"the namespace, with a token that has the write scope.",
Arg("namespace", "string", "the namespace", required=True),
Arg("mcp", "boolean", "on or off", required=True),
Arg("mcp", "boolean", "its own MCP server on or off"),
Arg("chat", "boolean", "its chat completions on or off"),
Arg(
"tools",
"string[]",
'the read tools its chat completions may use, or ["none"]',
enum=(*(n for n, _ in integrations.tool_choices()), "none"),
),
writes=True,
)
def set_namespace_integrations(ctx: Context, namespace: str, mcp: bool) -> dict[str, Any]:
def set_namespace_integrations(
ctx: Context, namespace: str, mcp: bool | None, chat: bool | None, tools: list[str] | None
) -> dict[str, Any]:
if not ctx.user.can_write:
raise ToolError("this token is read-only: ask for a token with the write scope to change this")
if mcp is None and chat is None and tools is None:
raise ToolError("give mcp, chat or tools to change")
sid = ctx.acl.namespace(namespace, "manage")
integrations.save(ctx.db, sid, mcp, ctx.user.email)
auth.audit(ctx.db, ctx.user.as_audit(), "namespace.integrations", namespace, {"mcp": mcp, "via": "mcp"})
tools = None if tools is None else [t for t in tools if t != "none"]
integrations.save(ctx.db, sid, mcp=mcp, chat=chat, tools=tools, user=ctx.user.email)
changed = store.clean({"mcp": mcp, "chat": chat, "tools": tools})
auth.audit(ctx.db, ctx.user.as_audit(), "namespace.integrations", namespace, {**changed, "via": "mcp"})
return _integrations(ctx, namespace, sid)


Expand Down
2 changes: 2 additions & 0 deletions fastapi_backend/app/api/v1/router.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
chats,
collections,
comments,
completions,
components,
content_types,
custom_nodes,
Expand Down Expand Up @@ -86,6 +87,7 @@
namespaces,
ns_assistant,
integrations,
completions,
hierarchy,
recordings,
notes,
Expand Down
Loading
Loading