induscode 0.1.0__py3-none-any.whl

induscode/capability_deck/cards/memory.py

@@ -0,0 +1,226 @@
+"""Working-memory capability — read and update a persistent scratch note the
+agent carries across turns.
+
+Status: minimal in-memory implementation + clearly-typed seam for the
+framework memory subsystem.
+
+The framework's ``indusagi.memory`` facade is not yet populated with a public
+working-memory store, so this card ships a self-contained, framework-agnostic
+implementation: a single mutable text buffer the agent overwrites or appends
+to, scoped to one built capability (one session). When the framework exposes a
+persistent memory store, a host adapts it to the :class:`MemoryStore` port and
+injects it via :attr:`DeckContext.framework` under :data:`MEMORY_HANDLE_KEY` —
+the :data:`Capability` surface and the tool's wire contract do not change.
+
+TODO(framework-memory): adapt ``indusagi.memory`` once it exports a public
+working-memory store; read it from ``ctx.framework[MEMORY_HANDLE_KEY]``.
+
+The single tool keys behavior on an ``action`` discriminant:
+
+- ``read``    — return the current working-memory note.
+- ``replace`` — overwrite the note with the supplied ``content``.
+- ``append``  — add a line to the end of the note.
+
+Port note: the TypeBox schema becomes a dict-literal JSON Schema; an unknown
+``action`` yields a defensive ``isError`` result rather than relying on
+upstream validation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from indusagi.agent import AgentToolResult
+from indusagi.ai import TextContent
+
+from ..contract import Capability, CapabilityCard, DeckContext, Schema, capability_id
+
+__all__ = [
+    "InMemoryStore",
+    "MEMORY_HANDLE_KEY",
+    "MemoryDetails",
+    "MemoryStore",
+    "build_memory_capability",
+    "memory_card",
+]
+
+
+# ---------------------------------------------------------------------------
+# Store (in-memory, card-owned) + injection seam
+# ---------------------------------------------------------------------------
+
+#: Key under which a host may wire a framework-backed memory store in later.
+MEMORY_HANDLE_KEY = "memoryStore"
+
+
+class MemoryStore(Protocol):
+    """The narrow port the memory capability binds to.
+
+    The in-memory default below satisfies it; a future framework-backed store
+    can be adapted to the same three methods and injected through the context.
+    """
+
+    def read(self) -> str: ...
+
+    def replace(self, content: str) -> None: ...
+
+    def append(self, line: str) -> None: ...
+
+
+class InMemoryStore:
+    """A trivial in-process working-memory buffer, one per built capability."""
+
+    def __init__(self) -> None:
+        self._buffer = ""
+
+    def read(self) -> str:
+        return self._buffer
+
+    def replace(self, content: str) -> None:
+        self._buffer = content
+
+    def append(self, line: str) -> None:
+        self._buffer = line if not self._buffer else f"{self._buffer}\n{line}"
+
+
+def _read_store(ctx: DeckContext) -> MemoryStore:
+    handle = (ctx.framework or {}).get(MEMORY_HANDLE_KEY)
+    if (
+        handle is not None
+        and callable(getattr(handle, "read", None))
+        and callable(getattr(handle, "replace", None))
+        and callable(getattr(handle, "append", None))
+    ):
+        return handle  # type: ignore[return-value] — structural check above
+    return InMemoryStore()
+
+
+# ---------------------------------------------------------------------------
+# Parameters (dict-literal JSON Schema)
+# ---------------------------------------------------------------------------
+
+_MEMORY_PARAMS: Schema = {
+    "type": "object",
+    "properties": {
+        "action": {
+            "type": "string",
+            "enum": ["read", "replace", "append"],
+            "description": (
+                "`read` returns the note; `replace` overwrites it; `append` adds a "
+                "line to the end."
+            ),
+        },
+        "content": {
+            "type": "string",
+            "description": (
+                "New note body (for `replace`) or the line to add (for `append`). "
+                "Ignored for `read`."
+            ),
+        },
+    },
+    "required": ["action"],
+    "additionalProperties": False,
+}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MemoryDetails:
+    """Structured detail returned alongside the model-facing content."""
+
+    action: Literal["read", "replace", "append"]
+    ok: bool
+    # Length of the note after the call, for quick status.
+    length: int
+
+
+_MEMORY_DESCRIPTION = (
+    "Keep a small working-memory note that persists across turns — durable facts, decisions, "
+    "or reminders you want to retain even after older messages scroll out of context. Use "
+    '`action:"read"` to recall it, `action:"replace"` to rewrite it from scratch, and '
+    '`action:"append"` to add a single line. Keep it concise; it is a scratchpad, not a log.'
+)
+
+_HEADINGS: Mapping[str, str] = {
+    "read": "Working memory:",
+    "replace": "Working memory replaced:",
+    "append": "Working memory appended:",
+}
+
+
+def _field(params: object, key: str) -> object:
+    if isinstance(params, Mapping):
+        return params.get(key)
+    return getattr(params, key, None)
+
+
+# ---------------------------------------------------------------------------
+# Capability builder
+# ---------------------------------------------------------------------------
+
+
+class _MemoryCapability:
+    """The live working-memory capability — structurally an ``AgentTool``."""
+
+    name = "memory"
+    label = "Working memory"
+    description = _MEMORY_DESCRIPTION
+    parameters: Schema = _MEMORY_PARAMS
+
+    def __init__(self, store: MemoryStore) -> None:
+        self._store = store
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        params: object,
+        signal: object = None,
+        on_update: object = None,
+    ) -> AgentToolResult:
+        del tool_call_id, signal, on_update
+        action = _field(params, "action")
+        if action not in ("read", "replace", "append"):
+            return AgentToolResult(
+                content=(
+                    TextContent(
+                        text='`action` must be "read", "replace", or "append".'
+                    ),
+                ),
+                details=None,
+                isError=True,
+            )
+        content = _field(params, "content")
+        if action == "replace":
+            self._store.replace(content if isinstance(content, str) else "")
+        elif action == "append" and isinstance(content, str) and content:
+            self._store.append(content)
+        note = self._store.read()
+        body = "(empty)" if not note else note
+        return AgentToolResult(
+            content=(TextContent(text=f"{_HEADINGS[action]}\n{body}"),),
+            details=MemoryDetails(action=action, ok=True, length=len(note)),
+        )
+
+
+def build_memory_capability(ctx: DeckContext) -> _MemoryCapability:
+    """Build the working-memory capability, binding it to an injected store
+    when one is wired into the context, or a fresh in-memory store otherwise.
+
+    :param ctx: the deck context; an optional store is read from
+        ``ctx.framework[MEMORY_HANDLE_KEY]``
+    """
+    return _MemoryCapability(_read_store(ctx))
+
+
+def _build(ctx: DeckContext) -> Capability:
+    return build_memory_capability(ctx)
+
+
+#: Catalog row for the working-memory capability.
+memory_card = CapabilityCard(
+    id=capability_id("memory"),
+    title="Working memory",
+    summary="Read and update a persistent scratch note that survives across turns.",
+    build=_build,
+)

induscode/capability_deck/cards/saas.py

@@ -0,0 +1,280 @@
+"""SaaS-action capability — a thin wrapper over the framework's connector
+gateway (Composio-style remote tool execution).
+
+The heavy lifting (authenticating to a vendor, resolving toolkit scopes,
+executing a remote tool slug) lives in the framework's connectors layer. This
+card does NOT re-implement any of it; it adapts an injected gateway handle to
+the deck's :data:`Capability` shape so the agent can invoke remote SaaS
+actions by slug. When no gateway is wired into the context the card still
+builds and returns a typed stub, so the deck assembles in every environment.
+
+The single tool keys behavior on an ``action`` discriminant:
+
+- ``discover`` — list executable remote tool slugs (optionally filtered).
+- ``execute``  — run one remote tool slug with arguments.
+
+Vendor-defined identifiers (uppercase tool slugs like ``GITHUB_CREATE_ISSUE``)
+are passed through verbatim — they are part of the connector's wire contract.
+
+Port note: the TypeBox schema becomes a dict-literal JSON Schema; the
+``slug``-required-for-execute check was already a runtime guard in TS and
+ports as-is.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Mapping
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from indusagi.agent import AgentToolResult
+from indusagi.ai import TextContent
+
+from ..contract import Capability, CapabilityCard, DeckContext, Schema, capability_id
+
+__all__ = [
+    "RemoteExecution",
+    "RemoteToolSummary",
+    "SAAS_GATEWAY_KEY",
+    "SaasDetails",
+    "SaasGatewayPort",
+    "build_saas_capability",
+    "saas_card",
+]
+
+
+# ---------------------------------------------------------------------------
+# Gateway handle (injected via DeckContext.framework)
+# ---------------------------------------------------------------------------
+
+#: Key under which a host wires a live SaaS gateway into the deck context.
+#: (Kept camelCase — it names a context-bag entry, mirroring the TS wiring.)
+SAAS_GATEWAY_KEY = "saasGateway"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RemoteToolSummary:
+    """One executable remote tool advertised by the connector."""
+
+    # Vendor-defined slug, passed through verbatim (e.g. `GITHUB_CREATE_ISSUE`).
+    slug: str
+    # Human-readable description from the connector, if any.
+    description: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RemoteExecution:
+    """The outcome of executing one remote tool slug."""
+
+    ok: bool
+    # Connector payload, surfaced to the model as serialized text.
+    data: object
+
+
+class SaasGatewayPort(Protocol):
+    """The slice of a framework SaaS gateway this card adapts.
+
+    Deliberately narrow — the deck only needs to list and execute remote
+    tools. The framework's full gateway (connection lifecycle, scope planning,
+    status reporting) is a superset; a host adapts it to this shape when
+    wiring it in.
+    """
+
+    def discover(
+        self, filter: Mapping[str, object] | None = None
+    ) -> Awaitable[list[RemoteToolSummary]]:
+        """List executable remote tools, optionally filtered by ``toolkits``
+        or ``query`` entries of the filter mapping."""
+        ...
+
+    def execute(
+        self, slug: str, args: Mapping[str, object]
+    ) -> Awaitable[RemoteExecution]:
+        """Execute one remote tool slug with arguments."""
+        ...
+
+
+def _read_gateway(ctx: DeckContext) -> SaasGatewayPort | None:
+    handle = (ctx.framework or {}).get(SAAS_GATEWAY_KEY)
+    if (
+        handle is not None
+        and callable(getattr(handle, "discover", None))
+        and callable(getattr(handle, "execute", None))
+    ):
+        return handle  # type: ignore[return-value] — structural check above
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Parameters (dict-literal JSON Schema)
+# ---------------------------------------------------------------------------
+
+_SAAS_PARAMS: Schema = {
+    "type": "object",
+    "properties": {
+        "action": {
+            "type": "string",
+            "enum": ["discover", "execute"],
+            "description": (
+                "`discover` lists available remote tool slugs; `execute` runs one "
+                "slug with arguments."
+            ),
+        },
+        "slug": {
+            "type": "string",
+            "description": (
+                "Vendor tool slug to run (e.g. GITHUB_CREATE_ISSUE). Required for "
+                "`execute`."
+            ),
+        },
+        "arguments": {
+            "type": "object",
+            "additionalProperties": True,
+            "description": "Arguments object for the remote tool, as the connector expects.",
+        },
+        "toolkits": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "On `discover`, restrict results to these toolkit names.",
+        },
+        "query": {
+            "type": "string",
+            "description": "On `discover`, free-text filter over available tools.",
+        },
+    },
+    "required": ["action"],
+    "additionalProperties": False,
+}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SaasDetails:
+    """Structured detail returned alongside the model-facing content."""
+
+    action: Literal["discover", "execute"]
+    ok: bool
+    slug: str | None = None
+    count: int | None = None
+
+
+_SAAS_DESCRIPTION = (
+    "Discover and run third-party SaaS actions (GitHub, Slack, Gmail, etc.) through the "
+    'connector gateway. Use `action:"discover"` to find the right tool slug, then '
+    '`action:"execute"` with that `slug` and an `arguments` object to perform the action. '
+    "Tool slugs are vendor-defined and case-sensitive; pass them exactly as listed."
+)
+
+_STUB_NOTE = (
+    "The SaaS connector gateway is not configured in this environment, so no remote action "
+    "was performed. Configure a connector (and authenticate the relevant toolkit) to enable "
+    "these actions."
+)
+
+
+def _field(params: object, key: str) -> object:
+    if isinstance(params, Mapping):
+        return params.get(key)
+    return getattr(params, key, None)
+
+
+def _stringify(data: object) -> str:
+    """``JSON.stringify(data, null, 2)`` with a non-throwing fallback."""
+    try:
+        return json.dumps(data, indent=2, ensure_ascii=False, default=str)
+    except Exception:
+        return str(data)
+
+
+# ---------------------------------------------------------------------------
+# Capability builder
+# ---------------------------------------------------------------------------
+
+
+class _SaasCapability:
+    """The live SaaS-action capability — structurally an ``AgentTool``."""
+
+    name = "saas-action"
+    label = "SaaS action"
+    description = _SAAS_DESCRIPTION
+    parameters: Schema = _SAAS_PARAMS
+
+    def __init__(self, gateway: SaasGatewayPort | None) -> None:
+        self._gateway = gateway
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        params: object,
+        signal: object = None,
+        on_update: object = None,
+    ) -> AgentToolResult:
+        del tool_call_id, signal, on_update
+        action_raw = _field(params, "action")
+        action: Literal["discover", "execute"] = (
+            "discover" if action_raw == "discover" else "execute"
+        )
+        if self._gateway is None:
+            return AgentToolResult(
+                content=(TextContent(text=_STUB_NOTE),),
+                details=SaasDetails(action=action, ok=False),
+                isError=True,
+            )
+        if action_raw == "discover":
+            tools = await self._gateway.discover(
+                {"toolkits": _field(params, "toolkits"), "query": _field(params, "query")}
+            )
+            text = (
+                "No remote tools matched."
+                if not tools
+                else "\n".join(
+                    f"- {t.slug}{f' — {t.description}' if t.description else ''}"
+                    for t in tools
+                )
+            )
+            return AgentToolResult(
+                content=(TextContent(text=text),),
+                details=SaasDetails(action="discover", ok=True, count=len(tools)),
+            )
+        slug = _field(params, "slug")
+        if not isinstance(slug, str) or slug == "":
+            return AgentToolResult(
+                content=(
+                    TextContent(text="`slug` is required to execute a SaaS action."),
+                ),
+                details=SaasDetails(action="execute", ok=False),
+                isError=True,
+            )
+        arguments = _field(params, "arguments")
+        args: Mapping[str, object] = (
+            arguments if isinstance(arguments, Mapping) else {}
+        )
+        result = await self._gateway.execute(slug, args)
+        return AgentToolResult(
+            content=(TextContent(text=_stringify(result.data)),),
+            details=SaasDetails(action="execute", ok=result.ok, slug=slug),
+            isError=not result.ok,
+        )
+
+
+def build_saas_capability(ctx: DeckContext) -> _SaasCapability:
+    """Build the SaaS-action capability, adapting an injected gateway when
+    present.
+
+    :param ctx: the deck context; an optional gateway is read from
+        ``ctx.framework[SAAS_GATEWAY_KEY]``
+    """
+    return _SaasCapability(_read_gateway(ctx))
+
+
+def _build(ctx: DeckContext) -> Capability:
+    return build_saas_capability(ctx)
+
+
+#: Catalog row for the SaaS-action capability.
+saas_card = CapabilityCard(
+    id=capability_id("saas-action"),
+    title="SaaS action",
+    summary="Discover and run third-party SaaS actions through the connector gateway.",
+    build=_build,
+)