manigent-server 0.1.0__py3-none-any.whl

manigent/server/public_profile.py

@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: BUSL-1.1
+"""
+manigent/server/public_profile.py
+What an anonymous visitor may know about an account's public agents — one
+builder for the account page's listing and the chat widget's header.
+
+An agent is public when its web chat widget is on, enabled, and one of its keys
+lists this server among its allowed sites (``ChannelGateway.hosted_grant``):
+the key the server's own pages chat with. So "listed" and "chattable here"
+never disagree.
+
+URLs are absolute (``MANIGENT_SERVER_URL``): the widget renders them on other
+people's sites.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional
+from urllib.parse import quote
+
+from manigent.models.agent import Agent
+from manigent.models.user import User
+from manigent.server.channels import webchat
+from manigent.server.channels.gateway import provider_gateway
+from manigent.server.channels.store import ChannelConnection, WebchatGrant
+
+if TYPE_CHECKING:
+    from manigent.server.context import ServerContext
+
+
+@dataclass(frozen=True)
+class PublicAgentRef:
+    agent: Agent
+    connection: ChannelConnection
+    grant: WebchatGrant
+    #: The short name — the handle in the agent's chat URL.
+    handle: str
+
+
+def account_url(ctx: "ServerContext", username: str) -> str:
+    return f"{_base(ctx)}/users/{quote(username)}/agents/"
+
+
+def chat_url(ctx: "ServerContext", username: str, handle: str) -> str:
+    return f"{_base(ctx)}/users/{quote(username)}/agents/{quote(handle)}/chat"
+
+
+def _base(ctx: "ServerContext") -> str:
+    gateway = provider_gateway(ctx)
+    return gateway.config.server_url.rstrip("/") if gateway is not None else ""
+
+
+def public_agents(ctx: "ServerContext", owner: User) -> list[PublicAgentRef]:
+    """The owner's public agents, by name."""
+    gateway = provider_gateway(ctx)
+    if gateway is None or webchat.CHANNEL not in gateway.adapters:
+        return []
+    out: list[PublicAgentRef] = []
+    for connection in gateway.store.list_connections(owner.id):
+        if connection.channel != webchat.CHANNEL or connection.disabled:
+            continue
+        grant = gateway.hosted_grant(connection)
+        if grant is None:
+            continue
+        agent = Agent.get(connection.agent_id, ctx.model_ctx)
+        if agent is None or agent.registered_by != owner.id:
+            continue
+        out.append(PublicAgentRef(agent, connection, grant, agent.short_name_for(owner.username)))
+    out.sort(key=lambda ref: ref.agent.name)
+    return out
+
+
+def account(ctx: "ServerContext", owner: User) -> dict:
+    return {
+        "handle": owner.username,
+        "display_name": owner.display_name or owner.username,
+        "bio": "",
+        "website": None,
+        "avatar_url": owner.avatar_url,
+        "url": account_url(ctx, owner.username),
+    }
+
+
+def agent_card(ctx: "ServerContext", ref: PublicAgentRef) -> dict:
+    """One agent as the listing shows it (no key, no account)."""
+    agent = ref.agent
+    profile = agent.public_chat
+    teams = agent.user_teams
+    return {
+        "id": ref.handle,
+        "display_name": profile["display_name"] or ref.handle,
+        "team_id": teams[0] if teams else None,
+        "description": agent.description,
+        "skills": list(agent.capabilities or []),
+        "takes_direct_requests": profile["takes_direct_requests"],
+        "online": ctx.ws_hub.is_connected(agent.id),
+        "starter_questions": profile["starter_questions"],
+    }
+
+
+def default_agent(cards: list[dict]) -> Optional[str]:
+    """The agent "Ask <account>" opens: the first that takes requests."""
+    return next((c["id"] for c in cards if c["takes_direct_requests"]), None)
+
+
+def request_taker(cards: list[dict], card: dict) -> Optional[dict]:
+    """Where a visitor goes to start real work when ``card`` only answers
+    questions: the first agent in its team that takes requests, else the
+    account's default."""
+    if card["takes_direct_requests"]:
+        return None
+    others = [c for c in cards if c["id"] != card["id"] and c["takes_direct_requests"]]
+    same_team = [c for c in others if card["team_id"] and c["team_id"] == card["team_id"]]
+    if same_team:
+        return same_team[0]
+    default = default_agent(cards)
+    return next((c for c in others if c["id"] == default), None)
+
+
+def widget_profile(ctx: "ServerContext", connection: ChannelConnection) -> Optional[dict]:
+    """What the chat widget draws in its header and intro for one key's agent.
+    None when the agent or its owner is gone."""
+    owner = User.get(connection.owner_id, ctx.model_ctx)
+    agent = Agent.get(connection.agent_id, ctx.model_ctx)
+    if owner is None or agent is None:
+        return None
+    handle = agent.short_name_for(owner.username)
+    gateway = provider_gateway(ctx)
+    grant = gateway.hosted_grant(connection) if gateway is not None else None
+    card = agent_card(ctx, PublicAgentRef(agent, connection, grant, handle))
+    # The request-taker link and the account page only exist while public.
+    refs = public_agents(ctx, owner)
+    is_public = any(r.handle == handle for r in refs)
+    taker = None
+    if is_public:
+        taker = request_taker([agent_card(ctx, r) for r in refs], card)
+    return {
+        **card,
+        "handle": handle,
+        "account": {
+            "handle": owner.username,
+            "display_name": owner.display_name or owner.username,
+            "url": account_url(ctx, owner.username) if is_public else None,
+        },
+        "request_taker": taker and {
+            "display_name": taker["display_name"],
+            "chat_url": chat_url(ctx, owner.username, taker["id"]),
+        },
+    }

manigent/server/public_requests/candidates.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: BUSL-1.1
+"""
+manigent/server/public_requests/candidates.py
+
+Every public agent a user could send a request to, in one shape
+(``ranking.Candidate`` plus what the request record snapshots).
+
+- **This server:** every discoverable agent another account owns (never the
+  user's own, never an assistant). Its retain count is ``local_retainers``.
+- **Other servers:** the hub directory. The hub matches a substring of its
+  query, so the whole request would match nothing; it is asked once per
+  strongest term (at most ``HUB_LOOKUPS``, inside the directory's per-user
+  limit) and the pages are merged. A hub that is off, unreachable or rate
+  limited just contributes nothing.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional
+
+from manigent.models.agent import Agent
+from manigent.models.user import User
+from manigent.server.hub.browser import HubError
+from manigent.server.hub.retain import local_hub_id
+from manigent.server.public_requests import ranking
+
+if TYPE_CHECKING:
+    from manigent.server.context import ServerContext
+
+logger = logging.getLogger(__name__)
+
+HUB_LOOKUPS = 3
+
+
+@dataclass(frozen=True)
+class Shaped:
+    """A candidate plus the card fields the request record keeps."""
+
+    candidate: ranking.Candidate
+    kind: str                       # "local" | "hub"
+    agent_id: Optional[str]
+    display_name: str
+    owner: str
+    deployment_name: Optional[str] = None
+
+
+def _genesis(ctx: "ServerContext") -> Optional[str]:
+    runtime = getattr(ctx, "hub_runtime", None)
+    reg = runtime.registration() if runtime is not None else None
+    return reg.genesis_fp if reg is not None and reg.genesis_fp else None
+
+
+def local_candidates(ctx: "ServerContext", user: User) -> list[Shaped]:
+    from manigent.server.agent_visibility import retainers_of
+
+    genesis = _genesis(ctx)
+    owners: dict[str, Optional[User]] = {}
+    out: list[Shaped] = []
+    for card in Agent.list_all_cards(ctx.model_ctx):
+        owner_id = card.get("registered_by")
+        name = card.get("name") or ""
+        if (not owner_id or owner_id == user.id or not card.get("discoverable_through_registry", True)
+                or name.endswith("-assistant")):
+            continue
+        if owner_id not in owners:
+            owners[owner_id] = User.get(owner_id, ctx.model_ctx)
+        owner = owners[owner_id]
+        if owner is None:
+            continue
+        agent = Agent.get(card["id"], ctx.model_ctx)
+        if agent is None:
+            continue
+        short = name[len(owner.username) + 1:] if name.startswith(f"{owner.username}-") else name
+        chat = agent.public_chat
+        candidate = ranking.Candidate(
+            agent_ref=local_hub_id(agent, genesis),
+            name=short,
+            description=card.get("description") or "",
+            expertise=[c for c in card.get("capabilities") or [] if isinstance(c, str)],
+            teams=[t for t in card.get("user_teams") or [] if isinstance(t, str)],
+            starter_questions=chat["starter_questions"],
+            retained_count=len(retainers_of(ctx, agent.id)),
+            online=ctx.ws_hub.is_connected(agent.id),
+        )
+        out.append(Shaped(candidate=candidate, kind="local", agent_id=agent.id,
+                          display_name=chat["display_name"] or short, owner=owner.username))
+    return out
+
+
+async def hub_candidates(ctx: "ServerContext", user: User, request: str) -> list[Shaped]:
+    from manigent.server.hub.browser import HubAgentSearch
+
+    runtime = getattr(ctx, "hub_runtime", None)
+    if runtime is None:
+        return []
+    # The longest terms are the most specific ones.
+    lookups = sorted(ranking.terms(request), key=len, reverse=True)[:HUB_LOOKUPS]
+    seen: dict[str, Shaped] = {}
+    for term in lookups:
+        try:
+            page = await runtime.directory.search(user.id, HubAgentSearch(q=term, limit=20))
+        except HubError as exc:
+            logger.info("Public request: hub search for %r skipped (%s)", term, exc.code)
+            break
+        for a in page.agents:
+            if a.is_local or not a.accepting_messages or a.hub_agent_id in seen:
+                continue
+            candidate = ranking.Candidate(
+                agent_ref=a.hub_agent_id, name=a.name, description=a.description,
+                expertise=list(a.capabilities), online=a.agent_online and a.deployment_connected,
+            )
+            seen[a.hub_agent_id] = Shaped(candidate=candidate, kind="hub", agent_id=None,
+                                          display_name=a.name, owner=a.deployment_label or a.deployment_name,
+                                          deployment_name=a.deployment_name)
+    return list(seen.values())

manigent/server/public_requests/dispatch.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: BUSL-1.1
+"""
+manigent/server/public_requests/dispatch.py
+
+Sending a public request to one matched agent, and reading back where that
+conversation stands. Nothing new carries the message: each agent gets the
+same thread a user would open by hand.
+
+- **This server:** a fresh Front Desk requester thread
+  (``_create_front_desk_requester_thread``), then the request posted as the
+  user, exactly as ``POST .../user-message`` posts it.
+- **Other servers:** a hub thread (``HubMirror.start_conversation``), then
+  ``HubMirror.send``, charged against the same send windows as the hub route.
+  An agent that is away still gets it: the request waits for it like any
+  hub message does.
+
+Status is read from the thread itself: an agent has responded once a
+non-ack message from the thread's counterpart is in it.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import TYPE_CHECKING, Literal, Optional
+
+from fastapi import HTTPException
+
+from manigent.models.chatroom import Chatroom
+from manigent.models.project import Project, counterpart_of
+from manigent.models.public_request import PublicRequest, RequestMatch
+from manigent.models.user import User
+from manigent.server.hub.browser import HubError
+
+if TYPE_CHECKING:
+    from manigent.server.context import ServerContext
+
+logger = logging.getLogger(__name__)
+
+UC = "user-communication"
+
+Status = Literal["not_sent", "working", "responded"]
+
+
+def _send_guard(ctx: "ServerContext"):
+    from manigent.server.hub.agent_send_guard import AgentSendGuard
+
+    guard = getattr(ctx, "hub_send_guard", None)
+    if guard is None:
+        guard = AgentSendGuard(ctx.channel_store)
+        ctx.hub_send_guard = guard
+    return guard
+
+
+async def _send_local(ctx: "ServerContext", user: User, request: PublicRequest, match: RequestMatch) -> str:
+    from manigent.models.agent import Agent
+    from manigent.server.routes.messages import send_message_as_user
+    from manigent.server.routes.projects import _create_front_desk_requester_thread
+
+    agent = Agent.get(match.agent_id or "", ctx.model_ctx)
+    if agent is None:
+        raise HubError("agent_not_found", "no such agent on this server")
+    project = await _create_front_desk_requester_thread(ctx, user, agent.name)
+    await send_message_as_user(
+        ctx, user.id, user.username, project.id, UC, request.text, owner_post=True,
+        client_request_id=f"public-request:{request.id}:{match.agent_ref}",
+    )
+    return project.id
+
+
+async def _send_hub(ctx: "ServerContext", user: User, request: PublicRequest, match: RequestMatch) -> str:
+    runtime = getattr(ctx, "hub_runtime", None)
+    if runtime is None:
+        raise HubError("hub_off_on_server", "the hub is off on this server")
+    key = f"public-request:{request.id}:{match.agent_ref}"
+    thread = await runtime.mirror.start_conversation(user, match.agent_ref, key,
+                                                     deployment_name=match.deployment_name)
+    _send_guard(ctx).charge(user_id=user.id, agent_id=None, target=thread.stand_in_id)
+    await runtime.mirror.send(user, thread.project_id, text=request.text, client_message_id=key)
+    return thread.project_id
+
+
+async def send(ctx: "ServerContext", user: User, request: PublicRequest, match: RequestMatch) -> None:
+    """Send ``request`` to ``match``'s agent, recording the thread (or why it
+    failed) on ``match``. Never raises for one agent's failure: the others
+    still go out."""
+    if match.project_id is not None:
+        return
+    try:
+        if match.kind == "local":
+            match.project_id = await _send_local(ctx, user, request, match)
+        else:
+            match.project_id = await _send_hub(ctx, user, request, match)
+    except HubError as exc:
+        match.send_error = exc.code
+        return
+    except HTTPException as exc:
+        match.send_error = "agent_not_found" if exc.status_code == 404 else "send_failed"
+        return
+    except Exception:
+        logger.warning("Public request %s: sending to %s failed", request.id, match.agent_ref, exc_info=True)
+        match.send_error = "send_failed"
+        return
+    match.sent_at = time.time()
+    match.send_error = None
+
+
+def thread_state(ctx: "ServerContext", match: RequestMatch) -> tuple[Status, Optional[float]]:
+    """The match's status and when its agent first answered (epoch seconds)."""
+    if match.project_id is None:
+        return "not_sent", None
+    try:
+        counterpart = counterpart_of(Project.get(match.project_id, ctx.model_ctx))
+    except ValueError:
+        return "working", None
+    room = Chatroom.get(match.project_id, UC, ctx.model_ctx)
+    if room is None or counterpart is None:
+        return "working", None
+    for message in room.get_messages():
+        if message.from_participant_id == counterpart and not message.is_ack:
+            return "responded", message.ts.timestamp()
+    return "working", None

manigent/server/public_requests/ranking.py

@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: BUSL-1.1
+"""
+manigent/server/public_requests/ranking.py
+
+How well a public agent fits a plain-words request. Pure functions, no I/O:
+the candidates come in already shaped (``candidates.Candidate``) and the
+ranked list goes out; the browser only ever sees the result.
+
+``fit`` (0-97) counts request terms that land in the agent's profile fields,
+weighted per field; ``rep`` (0-40) is how many users retained it, on a log
+scale. ``score = fit * 0.8 + rep * 0.2``. Agents under ``MIN_FIT`` are not
+matches at all, and at most ``MAX_MATCHES`` come back.
+
+Ratings do not exist, so ``rep`` is the retain-count term only, and an agent
+on another server (whose retains this server cannot count) gets 0.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Iterable, Sequence
+
+MIN_FIT = 20
+MAX_MATCHES = 12
+FIT_CAP = 97
+
+#: Label (shown in "Why it matched") -> weight per term that hits it.
+FIELD_WEIGHTS: dict[str, float] = {
+    "Name": 2.0,
+    "Expertise": 2.5,
+    "Teams": 2.0,
+    "Description": 1.0,
+    "Starter questions": 1.0,
+}
+#: A whole expertise phrase ("offer negotiation") appearing in the request.
+PHRASE_WEIGHT = 2.2
+
+_STOPWORDS = frozenset("""
+    the and for help what after one with that this from have has had are was were will would
+    could should can you your yours our their them they there here about into over under than
+    then when where which who whom why how all any some more most much many such very just only
+    also not but its it's i'm i've get got make want need like please me my mine
+""".split())
+_SPLIT = re.compile(r"[^a-z0-9$]+")
+_SUFFIXES = ("ations", "ation", "ings", "ing", "ions", "ion", "ers", "ed", "es", "er", "s", "e")
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """One public agent, in the shape ranking reads."""
+
+    agent_ref: str
+    name: str
+    description: str = ""
+    expertise: Sequence[str] = ()
+    teams: Sequence[str] = ()
+    starter_questions: Sequence[str] = ()
+    retained_count: int = 0
+    online: bool = False
+
+    def fields(self) -> dict[str, str]:
+        return {
+            "Name": self.name.replace("-", " "),
+            "Expertise": " ".join(self.expertise),
+            "Teams": " ".join(self.teams),
+            "Description": self.description,
+            "Starter questions": " ".join(self.starter_questions),
+        }
+
+
+@dataclass(frozen=True)
+class Ranked:
+    candidate: Candidate
+    fit: int
+    rep: int
+    score: float
+    why: dict[str, list[str]] = field(default_factory=dict)
+
+
+def _stem(word: str) -> str:
+    for suffix in _SUFFIXES:
+        if word.endswith(suffix) and len(word) - len(suffix) >= 4:
+            return word[: -len(suffix)]
+    return word
+
+
+def stems(text: str) -> dict[str, str]:
+    """The request's search terms: stem -> the word the user wrote, in
+    first-seen order. Matching uses the stem, "Why it matched" the word."""
+    out: dict[str, str] = {}
+    for word in _SPLIT.split(text.lower()):
+        word = word.strip("$")
+        if len(word) <= 2 or word in _STOPWORDS or word.isdigit():
+            continue
+        out.setdefault(_stem(word), word)
+    return out
+
+
+def terms(text: str) -> list[str]:
+    """The request's stemmed search terms, in first-seen order."""
+    return list(stems(text))
+
+
+def _hits(term: str, text: str) -> bool:
+    """``term`` starts a word of ``text`` (so "negotiat" hits "negotiation")."""
+    return re.search(r"(^|[^a-z0-9])" + re.escape(term), text) is not None
+
+
+def why(candidate: Candidate, request_terms: Iterable[str]) -> dict[str, list[str]]:
+    """Field label -> the request terms that hit it (fields with none left out)."""
+    request_terms = list(request_terms)
+    out: dict[str, list[str]] = {}
+    for label, text in candidate.fields().items():
+        lowered = text.lower()
+        hits = [t for t in request_terms if _hits(t, lowered)]
+        if hits:
+            out[label] = hits
+    return out
+
+
+def phrase_hits(candidate: Candidate, request: str) -> list[str]:
+    """Multi-word expertise phrases that appear whole in the request."""
+    lowered = request.lower()
+    return [p for p in candidate.expertise if " " in p.strip() and _hits(p.strip().lower(), lowered)]
+
+
+def fit(candidate: Candidate, request: str) -> tuple[int, dict[str, list[str]]]:
+    """The fit score and, per field, the request's own words that hit it."""
+    words = stems(request)
+    matched = why(candidate, words)
+    s = len(phrase_hits(candidate, request)) * PHRASE_WEIGHT
+    s += sum(len(hits) * FIELD_WEIGHTS[label] for label, hits in matched.items())
+    shown = {label: [words[h] for h in hits] for label, hits in matched.items()}
+    return min(FIT_CAP, round(100 * (1 - math.exp(-s / 9)))), shown
+
+
+def rep(retained_count: int) -> int:
+    return round(min(40.0, math.log10(max(0, retained_count) + 1) * 12))
+
+
+def rank(candidates: Iterable[Candidate], request: str) -> list[Ranked]:
+    """Matches, best first: fit >= MIN_FIT, at most MAX_MATCHES. Ties go to
+    the agent that is online, then by name, so the order is stable."""
+    out: list[Ranked] = []
+    for c in candidates:
+        f, matched = fit(c, request)
+        if f < MIN_FIT:
+            continue
+        r = rep(c.retained_count)
+        out.append(Ranked(candidate=c, fit=f, rep=r, score=round(f * 0.8 + r * 0.2, 2), why=matched))
+    out.sort(key=lambda x: (-x.score, not x.candidate.online, x.candidate.name))
+    return out[:MAX_MATCHES]