dot-agora 2.0.0__py3-none-any.whl

dot_agora/__init__.py

@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""dot_agora: mediated conversations between humans, LLM assistants and tools.
+
+Everything listed in ``__all__`` is the public API, together with the catalog
+modules (``dot_agora.protocols``, ``dot_agora.policies``, ``dot_agora.views``)
+and the hosts (``dot_agora.hosts.*``). Underscore-prefixed modules are
+internal and may change in any release.
+"""
+
+from . import policies, protocols, views
+from ._assistant import LLM, Assistant
+from ._clients import LLMClient, LLMResult, SearchClient, Stream
+from ._core import (
+    Act,
+    Decision,
+    Envelope,
+    Event,
+    Face,
+    Instance,
+    Journal,
+    Language,
+    Message,
+    Open,
+    ParticipantName,
+    Play,
+    Policy,
+    Post,
+    Protocol,
+    Refuse,
+    Role,
+    Ruling,
+    Speaker,
+    State,
+    Verdict,
+    lineage,
+)
+from ._participant import Participant, offers, serving
+from ._room import Occupant, Reactor, Room, Session, Stepper, fork, resume
+from .views import View, ViewFilter
+
+__all__ = [
+    "LLM",
+    "Act",
+    "Assistant",
+    "Decision",
+    "Envelope",
+    "Event",
+    "Face",
+    "Instance",
+    "Journal",
+    "LLMClient",
+    "LLMResult",
+    "Language",
+    "Message",
+    "Occupant",
+    "Open",
+    "Participant",
+    "ParticipantName",
+    "Play",
+    "Policy",
+    "Post",
+    "Protocol",
+    "Reactor",
+    "Refuse",
+    "Role",
+    "Room",
+    "Ruling",
+    "SearchClient",
+    "Session",
+    "Speaker",
+    "State",
+    "Stepper",
+    "Stream",
+    "Verdict",
+    "View",
+    "ViewFilter",
+    "fork",
+    "lineage",
+    "offers",
+    "policies",
+    "protocols",
+    "resume",
+    "serving",
+    "views",
+]

dot_agora/_assistant.py

@@ -0,0 +1,353 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Assistant: the LLM extension. It is the participant that chooses whom to
+call and what to ask, based on what its view shows. It adds no new concept
+and no special rule; its conduct lives in this class.
+
+Invariants:
+  Stateless. Nothing is kept between two reactions. The prompt is folded
+  from the view on each wake-up (`to_prompt`), so the same view gives the
+  same prompt (resume, replay).
+  Tools through the journal. The catalogue is the `offers(events)`
+  projection (the schemas declared in join payloads). A call is addressed
+  to whoever offers the tool.
+  The capability is its own. `llm=` accepts any
+  `(messages, tools) -> LLMResult`: the real client, or a deterministic
+  script (the scenarios). Same conduct, same journal.
+  Ask. A virtual `ask` tool is offered to the model. When the model calls
+  it, the assistant sends a request ({question, choices}) to the origin and
+  waits.
+  Schema. When the request carries one (`schema`) or the class sets one
+  (SCHEMA), the answer is checked here. A non-conforming answer becomes a
+  failure payload. The mediator knows nothing about it."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, Sequence
+from typing import ClassVar
+
+from ._clients import LLMClient, LLMResult
+from ._core.events import Event, Message
+from ._participant import Participant, offers, serving
+from .protocols import PlaysApproval
+from .views import View
+
+LLM = Callable[[list[dict], list[dict]], Awaitable[LLMResult]]
+
+ASK_TOOL = {
+    "name": "ask",
+    "description": "Ask the user a question when information is missing. "
+    "`choices` (optional) restricts the possible answers.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "question": {"type": "string"},
+            "choices": {"type": "array", "items": {"type": "string"}},
+        },
+        "required": ["question"],
+    },
+}
+
+
+class Assistant(Participant, PlaysApproval):  # PlaysApproval: it reads on_rejection
+    SCHEMA: dict | None = None  # an answer schema set by the class
+    ASK_TOOL: ClassVar[dict] = ASK_TOOL  # the HITL tool offered (overridable: a
+    # subclass can offer its own shape)
+    SYSTEM_PROMPT = (
+        "You are an assistant in a mediated conversation. You have no "
+        "memory: everything you know is in the messages above. "
+        "Other participants offer you tools. The `ask` tool asks the user "
+        "a question. Answer briefly, in the user's language."
+    )
+    LIMIT = 30  # events folded into the prompt
+    MAX_CHARS = 6000  # character budget per message
+    MAX_DELEGATION_STREAK = 8  # consecutive delegations before concluding
+
+    def __init__(self, name: str = "assistant", llm: LLM | None = None) -> None:
+        super().__init__(name)
+        self._llm = llm
+
+    @property
+    def llm(self) -> LLM:
+        """The capability, built on first use when none was given. This lets
+        `conversation.py` import without a key (the scenario passes a
+        scripted LLM)."""
+        if self._llm is None:
+            self._llm = LLMClient()
+        return self._llm
+
+    @llm.setter
+    def llm(self, value: LLM) -> None:
+        self._llm = value
+
+    # ── the acts I react to ───────────────────────────────────────────
+    async def on_request(self, event: Event, view: View) -> Sequence[Message]:
+        return await self.step(event, view)
+
+    on_reply = on_request
+    on_rejection = on_request  # my delegation was rejected: a result, I conclude
+
+    async def on_say(self, event: Event, view: View) -> Sequence[Message]:
+        # A public say reaches me too (dispatch delivers addressed and public
+        # events). My conduct: I only speak when addressed.
+        return await self.step(event, view) if self.for_me(event) else []
+
+    # ── the conduct ───────────────────────────────────────────────────
+    def catalogue(self, events: tuple[Event, ...]) -> list[dict]:
+        """The tool catalogue offered to the LLM: the offers of those present
+        (a journal projection) plus `ASK_TOOL`. It is stable: no tool is added
+        or removed per mode, so the cache prefix stays stable. It is public so
+        that a summary (compaction) offers the same tools as the assistant, which
+        keeps the same prefix and KV cache. Tools come first in the prefix
+        (tools, then system, then messages)."""
+        cat = {n: ts for n, ts in offers(events).items() if n != self.name and ts}
+        return [t for ts in cat.values() for t in ts] + [self.ASK_TOOL]
+
+    async def step(self, event: Event, view: View) -> Sequence[Message]:
+        events = view()
+
+        # 1. The tool catalogue, from the journal (whom to address a call to).
+        cat = {n: ts for n, ts in offers(events).items() if n != self.name and ts}
+        tools = self.catalogue(events)
+        if self._delegation_streak(events) >= self.MAX_DELEGATION_STREAK:
+            tools = []  # enough digging: conclude
+
+        # 2. Is my batch of calls complete, and was I woken by its last
+        #    reply? Otherwise I stay silent.
+        if self._waiting(events, event):
+            return []
+
+        # 3. The request I serve (the origin), and its schema if any.
+        origin = serving(self.name, event, events) or event
+        schema = self._schema(origin)
+        prompt = self.to_prompt(events)
+        if schema:
+            prompt.insert(
+                1,
+                {
+                    "role": "system",
+                    "content": "Answer only with JSON that conforms to this "
+                    f"schema: {json.dumps(schema)}",
+                },
+            )
+        out = await self.llm(prompt, tools)
+
+        # 4. The model asks for one or more tools: delegate through the
+        #    journal with an act addressed to whoever offers the tool (traced,
+        #    refusable). A tool nobody offers (invented) is ignored.
+        if out.calls:
+            outs: list[Message] = []
+            for tool, args in out.calls:
+                if tool == self.ASK_TOOL["name"]:  # a request to the origin
+                    return self._ask(args, origin)
+                provider = next(
+                    (n for n, ts in cat.items() if any(t["name"] == tool for t in ts)), None
+                )
+                if provider:
+                    outs += self.request({"tool": tool, "arguments": args}, to=(provider,))
+            if outs:
+                return outs
+
+        # 5. Otherwise, answer my debt (Participant.reply: `serving` finds,
+        #    in my view, the request this answer serves).
+        text = out.text or "…"
+        if schema:  # check here
+            return self.reply(event, view, self._conform(text, schema))
+        return self.reply(event, view, text)
+
+    def _ask(self, args: dict, origin: Event) -> list[Message]:
+        """Send the `ask` tool's question to the origin. Overridable: a subclass
+        can map a multi-question tool to a single `request`."""
+        return self.request(
+            {"question": args.get("question", "?"), "choices": list(args.get("choices", []))},
+            to=(origin.sender,),
+        )
+
+    # ── the view as a prompt ──────────────────────────────────────────
+    def to_prompt(self, events: tuple[Event, ...]) -> list[dict]:
+        """My view, in the model's four roles. What others say is `user`.
+        What I say is `assistant`. My tool calls are an `assistant` message
+        carrying `tool_calls` (one per call, `id` = `call_<idx>`). What
+        answers them is a `tool` message carrying that `id`. An event is a
+        result for me when it descends from one of my calls (caused_by), so
+        an interposition stays invisible.
+
+        Results are placed right after their call, whatever was said in
+        between: that is the shape the model expects. A call with no answer
+        yet is not shown."""
+        calls = self._my_calls(events)
+        cb = {e.idx: e.caused_by for e in events}
+        results: dict[int, list[Event]] = {}
+        for e in events:
+            if e.sender == self.name:
+                continue
+            call = self._ancestor_call(e.idx, calls, cb)
+            if call is not None:
+                results.setdefault(call, []).append(e)
+        msgs = [{"role": "system", "content": self.SYSTEM_PROMPT}]
+        window = [e for e in events[-self.LIMIT :] if e.act not in ("join", "leave")]
+        shown: set[int] = set()
+        i = 0
+        while i < len(window):
+            e = window[i]
+            if e.idx in shown:
+                i += 1
+                continue
+            if e.sender == self.name and self._is_call(e):
+                group = []
+                while (
+                    i < len(window) and window[i].sender == self.name and self._is_call(window[i])
+                ):
+                    group.append(window[i])
+                    i += 1
+                msgs.extend(self._exchange(group, results, shown))
+                continue
+            role = "assistant" if e.sender == self.name else "user"
+            msgs.append({"role": role, "content": self._text(e.payload)})
+            i += 1
+        return msgs
+
+    def _exchange(
+        self, group: list[Event], results: dict[int, list[Event]], shown: set[int]
+    ) -> list[dict]:
+        """A batch of consecutive calls and their replies: one `assistant`
+        message carrying the answered `tool_calls`, then one `tool` message
+        per call. Several events for the same call are concatenated."""
+        answered = [c for c in group if results.get(c.idx)]
+        if not answered:
+            return []
+        out = [
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [self._tool_call(c) for c in answered],
+            }
+        ]
+        for c in answered:
+            replies = results[c.idx]
+            shown.update(r.idx for r in replies)
+            out.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": self.call_id(c),
+                    "content": "\n".join(self._text(r.payload) for r in replies),
+                }
+            )
+        return out
+
+    @staticmethod
+    def call_id(call: Event) -> str:
+        """A call's id for the model: its journal idx. It is stable on replay
+        and unique in the conversation."""
+        return f"call_{call.idx}"
+
+    def _tool_call(self, call: Event) -> dict:
+        match call.payload:
+            case {"tool": tool, **fields}:
+                args = fields.get("arguments", {})
+            case _:
+                raise TypeError(f"event #{call.idx} is not a tool call")
+        return {
+            "id": self.call_id(call),
+            "type": "function",
+            "function": {
+                "name": tool,
+                "arguments": json.dumps(args, ensure_ascii=False, default=str),
+            },
+        }
+
+    def _text(self, payload: object) -> str:
+        """A payload as text for the model: as is for a string, JSON
+        otherwise. Truncated to `MAX_CHARS`."""
+        if payload is None:
+            return ""
+        text = (
+            payload
+            if isinstance(payload, str)
+            else json.dumps(payload, ensure_ascii=False, default=str)
+        )
+        return text[: self.MAX_CHARS]
+
+    # ── my calls and their replies, all derived ───────────────────────
+    @staticmethod
+    def _is_call(e: Event) -> bool:
+        return isinstance(e.payload, dict) and "tool" in e.payload
+
+    def _my_calls(self, events: tuple[Event, ...]) -> set[int]:
+        return {e.idx for e in events if e.sender == self.name and self._is_call(e)}
+
+    @staticmethod
+    def _ancestor_call(idx: int | None, calls: set[int], cb: dict[int, int | None]) -> int | None:
+        """My first ancestor call, walking `caused_by` up from `idx`. On the
+        rewired view the chain is view-local, so it skips a hidden
+        interposition on its own."""
+        while idx is not None:
+            if idx in calls:
+                return idx
+            idx = cb.get(idx)
+        return None
+
+    def _delegation_streak(self, events: tuple[Event, ...]) -> int:
+        """My delegations since the last real outside message. It guards
+        against getting stuck in a loop."""
+        calls = self._my_calls(events)
+        cb = {e.idx: e.caused_by for e in events}
+        n = 0
+        for e in reversed(events):
+            if e.act in ("join", "leave"):
+                continue
+            if e.sender == self.name and self._is_call(e):
+                n += 1
+            elif e.sender != self.name and self._ancestor_call(e.idx, calls, cb) is None:
+                break
+        return n
+
+    def _waiting(self, events: tuple[Event, ...], event: Event) -> bool:
+        """Should I stay silent? (a) One of my calls has no reply yet. Results
+        arrive in any order, so I wait. (b) All have replied, but a reply
+        arrived after the one waking me. That later wake-up concludes."""
+        calls = self._my_calls(events)
+        if not calls:
+            return False
+        cb = {e.idx: e.caused_by for e in events}
+        replies = [
+            (e, self._ancestor_call(e.idx, calls, cb))
+            for e in events
+            if e.sender != self.name and self.name in e.to
+        ]
+        replies = [(e, c) for e, c in replies if c is not None]
+        if calls - {c for _, c in replies}:
+            return True  # (a) some are missing
+        return any(e.idx > event.idx for e, _ in replies)  # (b) not my turn
+
+    # ── the schema: read from the request, or set by the class ────────
+    def _schema(self, origin: Event) -> dict | None:
+        schema = origin.payload.get("schema") if isinstance(origin.payload, dict) else None
+        return schema if isinstance(schema, dict) else self.SCHEMA
+
+    @staticmethod
+    def _conform(text: str, schema: dict) -> object:
+        """Minimal check (required keys, simple types). It is enough for a
+        failure to come back as an answer instead of invalid data."""
+        try:
+            data = json.loads(text)
+        except ValueError:
+            return {"error": "answer does not conform to the schema", "raw": text}
+        types = {
+            "string": str,
+            "integer": int,
+            "number": (int, float),
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+        }
+        for k in schema.get("required", []):
+            if k not in data:
+                return {"error": f"missing key: {k}", "raw": text}
+        for k, spec in schema.get("properties", {}).items():
+            t = types.get(spec.get("type"))
+            if k in data and t and not isinstance(data[k], t):
+                return {"error": f"invalid type: {k}", "raw": text}
+        return data

dot_agora/_clients/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""clients: the capabilities a participant owns. The LLM, search, and the
+stream contract."""
+
+from .llm import LLMClient, LLMResult, Stream, Subscriber
+from .search import SearchClient
+
+__all__ = ["LLMClient", "LLMResult", "SearchClient", "Stream", "Subscriber"]

dot_agora/_clients/llm.py

@@ -0,0 +1,177 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""llm: the LLM capability. A neutral contract behind a single boundary.
+
+LLMResult   what a call returns: text, or tool requests. Neutral
+            (dataclass + dicts), so a participant is written without
+            importing dot_inference.
+Stream      the contract of a capability that streams:
+            `subscribe(f, kind)`, with `kind` = "text" (default) or
+            "reasoning". Subscribers are hosts (a terminal printing word
+            by word, a front end showing the reasoning). The participant
+            only sees the complete result and the journal receives a
+            single event, so streaming is invisible to the framework and
+            to the model. Reasoning is display only: it is neither
+            returned nor journaled.
+LLMClient   the boundary: `await llm(messages, tools) -> LLMResult`. It
+            streams as soon as it has subscribers (Stream contract): each
+            fragment is published to them as it arrives, then the
+            complete result is returned. The participant only sees that
+            result.
+            The dot_inference client is resolved at construction, so a
+            missing configuration fails there rather than deep inside a
+            reading task; the translation to and from dot_inference
+            happens at call time, so this file is the only one that
+            moves when its interface changes.
+            A neutral message can carry `cache_control` (a cache
+            breakpoint set by the participant on its prompt). It travels
+            on the content block, the shape the provider reads."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+import dot_inference
+
+Subscriber = Callable[[str], None]
+KINDS = ("text", "reasoning")
+
+
+@runtime_checkable
+class Stream(Protocol):
+    def subscribe(self, f: Subscriber, kind: str = "text") -> None: ...
+
+
+@dataclass(frozen=True)
+class LLMResult:
+    """What an LLM call returns: text, or tool requests. `calls` holds all
+    the requests of the turn as (name, arguments) and is always filled.
+    Writing `LLMResult(tool=…, arguments=…)` (a convenience for fakes)
+    derives it. Readers only read `calls`."""
+
+    text: str | None = None
+    tool: str | None = None  # write convenience for fakes only
+    arguments: dict = field(default_factory=dict)
+    calls: tuple = ()  # ((name, arguments), ...), the field to read
+
+    def __post_init__(self) -> None:
+        if not self.calls and self.tool:
+            object.__setattr__(self, "calls", ((self.tool, self.arguments),))
+
+
+class LLMClient:
+    def __init__(
+        self,
+        model: str | None = None,
+        *,
+        reasoning_effort: str | None = None,
+        settings: dot_inference.InferenceSettings | None = None,
+        client: dot_inference.LLMClient | None = None,
+    ) -> None:
+        """Wrap a dot_inference client, given or built.
+
+        With ``client``, that client is used as is: several assistants can
+        share one connection pool and rate limiter, and tests pass a scripted
+        one. Otherwise dot_inference builds it from ``settings``, read from the
+        ``DOTI_*`` environment when omitted: the provider, the credentials and,
+        unless ``model`` is given, the model all come from there.
+        ``model`` and ``reasoning_effort`` only apply to a client built here.
+        """
+        if client is not None and (model, reasoning_effort, settings) != (None, None, None):
+            raise ValueError(
+                "LLMClient: model, reasoning_effort and settings configure a client "
+                "built here; they cannot be combined with client="
+            )
+        self._client = client or dot_inference.get_llm_client(
+            settings or dot_inference.InferenceSettings(),
+            model=model,
+            reasoning_effort=reasoning_effort,
+        )
+        self._subscribers: dict[str, list[Subscriber]] = {k: [] for k in KINDS}
+
+    # ── the stream: subscribers, served as fragments arrive ───────────
+    def subscribe(self, f: Subscriber, kind: str = "text") -> None:
+        """With a subscriber, calls go through `stream`. Without one, they go
+        through `call`. Same result, same translation."""
+        if kind not in KINDS:
+            raise ValueError(f"subscribe: kind {kind!r}, expected one of {KINDS}")
+        self._subscribers[kind].append(f)
+
+    def _publish(self, kind: str, fragment: str) -> None:
+        for f in self._subscribers[kind]:
+            with contextlib.suppress(Exception):  # a failing display does not break the call
+                f(fragment)
+
+    # ── the call: translate, call, translate back ─────────────────────
+    async def __call__(self, messages: list[dict], tools: list[dict]) -> LLMResult:
+        msgs = [self._message(m) for m in messages]
+        tdefs = [
+            dot_inference.ToolDef(
+                name=t["name"], description=t["description"], parameters=t["parameters"]
+            )
+            for t in tools
+        ] or None
+
+        if any(self._subscribers.values()):
+            r = await self._stream(msgs, tdefs)
+        else:
+            r = await self._client.call(msgs, tools=tdefs, tool_choice="auto")
+
+        if r.tool_calls:
+            calls = tuple(
+                (
+                    tc.name,
+                    tc.arguments
+                    if isinstance(tc.arguments, dict)
+                    else json.loads(tc.arguments or "{}"),
+                )
+                for tc in r.tool_calls
+            )
+            return LLMResult(calls=calls)
+        return LLMResult(text=(r.content or "").strip())
+
+    @staticmethod
+    def _message(m: dict) -> dot_inference.Message:
+        """A neutral message to a dot_inference Message. Tool exchanges pass
+        through as is (`tool_calls` on an assistant, `tool_call_id` on a
+        `tool`): that is the provider's shape. A `cache_control` on the
+        message becomes a content block carrying it, which is where the
+        provider reads a cache breakpoint."""
+        Role = dot_inference.Role
+        roles = {
+            "user": Role.USER,
+            "assistant": Role.ASSISTANT,
+            "system": Role.SYSTEM,
+            "tool": Role.TOOL,
+        }
+        role = roles.get(m["role"], Role.USER)
+        extra = {k: m[k] for k in ("tool_calls", "tool_call_id") if m.get(k)}
+        content = m.get("content")
+        cc = m.get("cache_control")
+        if cc is not None and isinstance(content, str):
+            content = [{"type": "text", "text": content, "cache_control": cc}]
+        return dot_inference.Message(role=role, content=content, **extra)
+
+    async def _stream(
+        self, msgs: list[dot_inference.Message], tdefs: list[dot_inference.ToolDef] | None
+    ) -> dot_inference.LLMResponse:
+        """Consume the dot_inference stream. Publish each fragment (text or
+        reasoning) to its subscribers, then return the assembled response
+        (StreamDone). It is the same response as `call`, translated back by
+        the same code."""
+        response = None
+        async for ev in self._client.stream(msgs, tools=tdefs, tool_choice="auto"):
+            if isinstance(ev, dot_inference.TextDelta):
+                self._publish("text", ev.content)
+            elif isinstance(ev, dot_inference.ReasoningDelta):
+                self._publish("reasoning", ev.content)
+            elif isinstance(ev, dot_inference.StreamDone):
+                response = ev.response
+        if response is None:
+            raise RuntimeError("LLMClient: stream ended without StreamDone")
+        return response

dot_agora/_clients/search.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""search: the web search capability, behind a single boundary.
+
+  SearchClient   `await search(query) -> str`: a sourced answer (text +
+                 Markdown links). The search counterpart of LLMClient. The
+                 key is checked at construction (a missing LINKUP_API_KEY
+                 raises), and the provider call (Linkup) lives only here.
+
+A participant that searches holds a SearchClient and has no key or HTTP code
+of its own."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+ENDPOINT = "https://api.linkup.so/v1/search"
+
+
+class SearchClient:
+    DEPTH = "standard"  # "deep": slower, more thorough
+    SOURCES = 3  # how many sources to cite
+    TIMEOUT = 30
+
+    def __init__(self, depth: str | None = None) -> None:
+        self.depth = depth or self.DEPTH
+        self.api_key = os.getenv("LINKUP_API_KEY")
+        if not self.api_key:
+            raise RuntimeError(
+                "SearchClient: LINKUP_API_KEY is not set in the environment. Real search requires it."
+            )
+
+    async def __call__(self, query: str) -> str:
+        """Search and return a sourced answer. An HTTP error response raises
+        `httpx.HTTPStatusError`."""
+        async with httpx.AsyncClient(timeout=self.TIMEOUT) as client:
+            r = await client.post(
+                ENDPOINT,
+                json={"q": query, "depth": self.depth, "outputType": "sourcedAnswer"},
+                headers={"Authorization": f"Bearer {self.api_key}"},
+            )
+            r.raise_for_status()
+            data = r.json()
+        return self._format(data)
+
+    def _format(self, data: dict) -> str:
+        answer = (data.get("answer") or "").strip()
+        sources = data.get("sources") or []
+        links = "\n".join(
+            f"- [{s.get('name', s.get('url', '?'))}]({s.get('url', '')})"
+            for s in sources[: self.SOURCES]
+        )
+        return f"{answer}\n\nSources:\n{links}" if links else answer