Add the assistant: a chat that drives the MCP tools in-process
Docs / docs (push) Successful in 42s
Playwright Tests / test-playwright (1, 2) (push) Failing after 2m42s
Playwright Tests / test-playwright (2, 2) (push) Failing after 10s
pre-commit / pre-commit (push) Failing after 2m33s
Test Backend / test-backend (push) Failing after 2m48s
Compose Smoke Test / test-compose (push) Failing after 9s
Playwright Tests / merge-reports (push) Failing after 2m17s

A provider set under Settings (OpenAI-compatible; key encrypted in
flow-data/ai.json) turns on an Assistant panel in the sidebar. Each turn runs
the FastMCP tools in-process as the person chatting, streams the rounds over
SSE and keeps one transcript per user. The panel floats on any screen and
shares the editor's lane: a settings panel keeps the top half, the chat the
bottom. The MCP client is now built once, for the endpoint and the chat.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
2026-09-16 23:28:23 +02:00
co-authored by Claude Fable 5.1
parent d9630f66f5
commit cc4091166e
25 changed files with 1957 additions and 43 deletions
+7
View File
@@ -0,0 +1,7 @@
"""The assistant: a model driving the MCP tools from inside the dashboard.
``config`` is the provider and the key, ``client`` the one call every
OpenAI-compatible provider answers, ``agent`` the loop between the model and
the tools. The tools are the MCP server's own, so what the assistant can do is
exactly what an external agent can do.
"""
+172
View File
@@ -0,0 +1,172 @@
"""The turn: the model, the tools, and the rounds between them.
The tools are the MCP server's own, called in-process rather than over the
endpoint: same names, same schemas, same REST calls underneath. A tool added
for external agents is there for the assistant the moment it exists, and the
assistant can do nothing an external agent could not.
The transcript is a list of chat-completion messages, mutated in place by
:func:`run_turn` and persisted by the caller. It is also what the browser
renders, so nothing is stored twice.
"""
from __future__ import annotations
import json
import logging
from collections.abc import AsyncIterator
from typing import Any
import httpx
from mcp.types import TextContent
from fluksio.ai import client
from fluksio.ai.config import AIConfig
from fluksio.flow.schemas import FlowDef
from fluksio.mcp.server import caller_authorization, mcp
logger = logging.getLogger(__name__)
_SYSTEM = """You are the assistant inside a Fluksio instance. You read, build, edit and \
operate flows through the tools; they are the same API the editor uses, so \
anything you save appears in the editor at once.
How to work:
- Read before you write: get_flow before save_flow, and pass back the version \
you read. On a version conflict, read again and reapply the change.
- save_flow writes a draft, and validate_flow tells you whether it is sound. \
Publish only when the user asks for the change to go live; otherwise leave \
the draft for review in the editor and say so.
- list_node_types gives the node types and their parameters; get_node_source \
shows how a Python node is written before you write one.
- Keep answers short, in plain text without markdown. Name what you changed.
The flow document `save_flow` takes, as a JSON schema:
"""
# ponytail: a tool's answer is replayed on every later round of the
# conversation, so one big one is paid for again and again; cut it here rather
# than summarise it. A per-tool digest is the upgrade if this bites.
_RESULT_LIMIT = 20_000
def system_prompt(flow: str | None) -> str:
prompt = _SYSTEM + json.dumps(FlowDef.model_json_schema())
if flow:
prompt += f"\n\nThe user is looking at the flow named {flow!r}."
return prompt
async def tool_specs() -> list[dict[str, Any]]:
return [
{
"type": "function",
"function": {
"name": tool.name,
"description": tool.description or "",
"parameters": tool.inputSchema,
},
}
for tool in await mcp.list_tools()
]
def _arguments(raw: Any) -> dict[str, Any]:
if isinstance(raw, dict):
return raw
try:
parsed = json.loads(raw or "{}")
except ValueError:
return {}
return parsed if isinstance(parsed, dict) else {}
async def _call_tool(name: str, arguments: dict[str, Any]) -> str:
"""Run one tool; whatever goes wrong is text the model can read."""
try:
result = await mcp.call_tool(name, arguments)
except Exception as exc: # noqa: BLE001 - an unknown tool, or refused arguments
return json.dumps({"error": str(exc)})
if isinstance(result, dict):
text = json.dumps(result)
else:
text = "".join(c.text for c in result if isinstance(c, TextContent))
if len(text) > _RESULT_LIMIT:
text = text[:_RESULT_LIMIT] + "… (truncated)"
return text
def summarize(content: str | None) -> dict[str, Any]:
"""What the browser shows for a tool's answer: whether it worked."""
try:
result = json.loads(content or "")
except ValueError:
return {"ok": True}
if isinstance(result, dict) and "error" in result:
return {"ok": False, "error": str(result["error"])[:300]}
return {"ok": True}
async def run_turn(
config: AIConfig,
messages: list[dict[str, Any]],
text: str,
*,
flow: str | None,
authorization: str,
) -> AsyncIterator[dict[str, Any]]:
"""One user turn, yielding progress events as it goes.
A round is appended to *messages* only once every tool in it has answered,
so a turn cut off part-way leaves a transcript the provider still accepts.
"""
messages.append({"role": "user", "content": text})
tools = await tool_specs()
system = {"role": "system", "content": system_prompt(flow)}
token = caller_authorization.set(authorization)
try:
for _ in range(config.max_rounds):
try:
response = await client.chat_completion(
api_base=config.api_base,
api_key=config.api_key,
model=config.model,
messages=[system, *messages],
tools=tools,
)
except (client.ProviderError, httpx.HTTPError) as exc:
yield {"type": "error", "detail": f"The provider answered {exc}"}
return
choice = response["choices"][0]["message"]
content = choice.get("content") or ""
calls = choice.get("tool_calls") or []
assistant: dict[str, Any] = {"role": "assistant", "content": content}
if content:
yield {"type": "message", "content": content}
if not calls:
messages.append(assistant)
return
assistant["tool_calls"] = calls
answers: list[dict[str, Any]] = []
for call in calls:
function = call.get("function") or {}
name = str(function.get("name", ""))
arguments = _arguments(function.get("arguments"))
yield {"type": "tool_call", "name": name, "arguments": arguments}
result = await _call_tool(name, arguments)
answers.append(
{
"role": "tool",
"tool_call_id": call.get("id", ""),
"content": result,
}
)
yield {"type": "tool_result", "name": name, **summarize(result)}
messages.append(assistant)
messages.extend(answers)
yield {
"type": "error",
"detail": f"Stopped after {config.max_rounds} rounds of tool calls.",
}
finally:
caller_authorization.reset(token)
+76
View File
@@ -0,0 +1,76 @@
"""One OpenAI-compatible provider call, and the model listing beside it.
Chat completions with function tools is the dialect every hosted provider and
every local server speaks — OpenAI, Anthropic's compatibility endpoint,
OpenRouter, Ollama, vLLM — so one client covers them without a provider SDK.
The admin types the URL; the model never chooses where a request goes.
"""
from __future__ import annotations
from typing import Any
from urllib.parse import urlparse
import httpx
class ProviderError(Exception):
"""The provider answered, and the answer was a refusal."""
def check_base(api_base: str) -> None:
parsed = urlparse(api_base)
if parsed.scheme not in ("http", "https") or not parsed.hostname:
raise ValueError("The provider URL must be an http(s) URL")
def _headers(api_key: str) -> dict[str, str]:
return {"Authorization": f"Bearer {api_key}"}
def _detail(response: httpx.Response) -> str:
try:
error = response.json().get("error")
except ValueError:
error = None
if isinstance(error, dict):
error = error.get("message")
text = str(error or response.text or response.reason_phrase)
return f"{response.status_code}: {text[:300]}"
async def chat_completion(
*,
api_base: str,
api_key: str,
model: str,
messages: list[dict[str, Any]],
tools: list[dict[str, Any]],
timeout: float = 120.0,
) -> dict[str, Any]:
"""``POST {api_base}/chat/completions``, the whole answer at once."""
body: dict[str, Any] = {"model": model, "messages": messages}
if tools:
body["tools"] = tools
async with httpx.AsyncClient(timeout=timeout) as http:
response = await http.post(
api_base.rstrip("/") + "/chat/completions",
json=body,
headers=_headers(api_key),
)
if response.is_error:
raise ProviderError(_detail(response))
result: dict[str, Any] = response.json()
return result
async def list_models(api_base: str, api_key: str, timeout: float = 15.0) -> list[str]:
"""The ids ``GET {api_base}/models`` offers, for the settings screen."""
async with httpx.AsyncClient(timeout=timeout) as http:
response = await http.get(
api_base.rstrip("/") + "/models", headers=_headers(api_key)
)
if response.is_error:
raise ProviderError(_detail(response))
data = response.json().get("data") or []
return sorted(str(m["id"]) for m in data if isinstance(m, dict) and "id" in m)
+98
View File
@@ -0,0 +1,98 @@
"""The assistant's provider: where the model is, and the key that opens it.
One file on the data volume beside ``cloud.json``, for the same reasons: it is
a credential, it must survive a rebuild, and it must never be in the flows
repository. The key is encrypted with the cipher the secrets store uses, so
both turn unreadable together when ``SECRET_KEY`` changes. Nothing here exists
until a superuser writes it, and its absence is what keeps every AI surface
off.
"""
from __future__ import annotations
import json
import logging
import os
from dataclasses import asdict, dataclass
from typing import Any
from cryptography.fernet import InvalidToken
from fluksio.core.config import settings
from fluksio.flow.secrets import fernet
logger = logging.getLogger(__name__)
@dataclass(frozen=True)
class AIConfig:
#: An OpenAI-compatible base, e.g. ``https://api.openai.com/v1``.
api_base: str
api_key: str
model: str
#: How many model-and-tools rounds one turn may take before it is stopped.
max_rounds: int = 12
@property
def ready(self) -> bool:
return bool(self.api_base and self.api_key and self.model)
def public(self) -> dict[str, Any]:
"""The secret-free view the settings screen gets."""
key = self.api_key
masked = None
if key:
masked = f"{key[:3]}…{key[-4:]}" if len(key) > 8 else "••••"
return {
"api_base": self.api_base,
"model": self.model,
"max_rounds": self.max_rounds,
"api_key_set": bool(key),
"api_key_masked": masked,
}
def load() -> AIConfig | None:
path = settings.AI_CONFIG_FILE
try:
data = json.loads(path.read_text())
except OSError:
return None
except ValueError:
logger.exception("Could not read %s; the assistant stays off", path)
return None
sealed = data.pop("api_key_enc", "")
key = ""
if sealed:
try:
key = fernet(settings.SECRET_KEY).decrypt(sealed.encode()).decode()
except InvalidToken:
logger.error(
"%s was written with a different SECRET_KEY; enter the key again",
path,
)
try:
return AIConfig(api_key=key, **data)
except TypeError:
logger.exception("Could not read %s; the assistant stays off", path)
return None
def save(config: AIConfig) -> None:
path = settings.AI_CONFIG_FILE
path.parent.mkdir(parents=True, exist_ok=True)
data = asdict(config)
key = data.pop("api_key")
data["api_key_enc"] = (
fernet(settings.SECRET_KEY).encrypt(key.encode()).decode() if key else ""
)
# Written through a temporary file so a crash mid-write cannot leave a
# half-parsed credential behind, and never group- or world-readable.
tmp = path.with_suffix(".tmp")
tmp.write_text(json.dumps(data, indent=2))
os.chmod(tmp, 0o600)
tmp.replace(path)
def delete() -> None:
settings.AI_CONFIG_FILE.unlink(missing_ok=True)