spatialagents 0.1.0__py3-none-any.whl

spatialagents/policy.py

@@ -0,0 +1,118 @@
+"""What an agent is allowed to do, decided before anything runs.
+
+Four permission classes, from "just look" to "cannot be undone", and five
+egress classes for what leaves the process. The defaults are the ones a user
+who started a conversation and said nothing else would expect: it may read,
+look at rendered pictures and change the product's own reversible state, but
+it may not write into the user's source files or delete anything unless the
+policy allows it AND the call is confirmed -- in a conversation, by the
+person's approval (`approvals.py`), which no agent can give itself.
+
+The vocabulary is shared by every product; what each tool's class is, and how
+a call is checked against a policy, is the product's (its `ToolBackend`).
+Invariant: raw scientific data does not go to a model by default -- neither
+`row_level` nor `raw_pixels` is in `DEFAULT_EGRESS`.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+
+PERMISSIONS = ("read", "reversible_write", "source_file_write", "destructive")
+
+#: The permission classes a conversation pauses on for the person's approval.
+NEEDS_APPROVAL = ("source_file_write", "destructive")
+
+#: What a result carries out of the product, least to most.
+EGRESS = ("metadata", "aggregates", "row_level", "rendered_pixels", "raw_pixels")
+
+DEFAULT_EGRESS = frozenset({"metadata", "aggregates", "rendered_pixels"})
+
+#: What a scope check answers, most capable first. Every product's classifier
+#: answers one of these four; all four are good answers.
+SCOPE_STATES = ("can_execute", "can_analyze", "can_recommend", "outside_domain")
+CAN_EXECUTE, CAN_ANALYZE, CAN_RECOMMEND, OUTSIDE_DOMAIN = SCOPE_STATES
+
+
+@dataclass(frozen=True)
+class Policy:
+    allow_source_writes: bool = False
+    allow_destructive: bool = False
+    egress: frozenset = field(default_factory=lambda: DEFAULT_EGRESS)
+    #: False: reads only -- a `read`-scoped token's policy.
+    allow_writes: bool = True
+    #: Who is calling, when the transport knows (a token's id); in audit lines.
+    principal: str | None = None
+
+    @classmethod
+    def from_flags(cls, *, allow_source_writes=False, allow_destructive=False,
+                   egress=None) -> "Policy":
+        allowed = set(DEFAULT_EGRESS)
+        for item in egress or ():
+            item = item.strip()
+            if not item:
+                continue
+            if item not in EGRESS:
+                raise ValueError(f"unknown egress class {item!r}; expected any of {EGRESS}")
+            allowed.add(item)
+        return cls(bool(allow_source_writes), bool(allow_destructive), frozenset(allowed))
+
+    def describe(self) -> dict:
+        return {"allow_source_writes": self.allow_source_writes,
+                "allow_destructive": self.allow_destructive,
+                "allow_writes": self.allow_writes,
+                "egress": sorted(self.egress, key=EGRESS.index),
+                "principal": self.principal}
+
+    def narrowed_by_scope(self, scope: str, principal: str | None = None) -> "Policy":
+        """This policy as a token of `scope` may use it: narrower, never wider.
+
+        `read` allows no writes at all; `write` (and `bridge`, the same policy
+        for another application) allows the product's own reversible state but
+        no source-file writes or deletes; `admin` leaves the server's policy as
+        it is. An unknown scope is treated as `read`.
+        """
+        if scope == "admin":
+            return dataclasses.replace(self, principal=principal)
+        if scope in ("write", "bridge"):
+            # `bridge`: another application's token. It writes the product's
+            # own reversible state like `write`, never the user's source files
+            # -- a peer may hold the same file open, and a source write under
+            # it is the one thing it must never have done.
+            return dataclasses.replace(self, allow_source_writes=False,
+                                       allow_destructive=False, principal=principal)
+        return dataclasses.replace(self, allow_writes=False, allow_source_writes=False,
+                                   allow_destructive=False, principal=principal)
+
+
+def permitted(capability, policy: Policy) -> bool:
+    """Whether a call COULD run under this policy, given confirmation.
+    `capability` is anything with an `egress` and a `permission`."""
+    if capability.egress not in policy.egress:
+        return False
+    if capability.permission != "read" and not policy.allow_writes:
+        return False
+    if capability.permission == "source_file_write":
+        return policy.allow_source_writes
+    if capability.permission == "destructive":
+        return policy.allow_destructive
+    return True
+
+
+def elevated(policy: Policy, permission: str) -> Policy:
+    """`policy` with the one flag an approved call of `permission` needs."""
+    if permission == "source_file_write":
+        return dataclasses.replace(policy, allow_source_writes=True)
+    if permission == "destructive":
+        return dataclasses.replace(policy, allow_destructive=True)
+    return policy
+
+
+def policy_from(described: dict | None) -> Policy:
+    """The policy a record's `Policy.describe()` wrote down."""
+    d = described or {}
+    return Policy(allow_source_writes=bool(d.get("allow_source_writes")),
+                  allow_destructive=bool(d.get("allow_destructive")),
+                  egress=frozenset(d.get("egress") or DEFAULT_EGRESS),
+                  allow_writes=d.get("allow_writes", True) is not False, principal=d.get("principal"))

spatialagents/prefix.py

@@ -0,0 +1,79 @@
+"""The cached prefix a conversation starts from: the mechanism, not the words.
+
+A prompt cache pays only while the prefix is byte-identical, so the system
+prompt of a conversation is built once, from parts that are the same for
+every conversation of one build, policy and plugin set, and frozen in the
+conversation's record:
+
+    [identity + house rules]  [SKILL <name>: one short skill]  [tool catalog, cache breakpoint]
+
+Nothing volatile may enter it -- no conversation, dataset, project or account
+id, no time, no path (a product that interpolates its session root into its
+rules breaks the cache for everyone). What each part says is the product's:
+Plexora's identity and house rules, SCIMAP Pro's `RULES` block and its
+`dataset-triage` skill; each product pins its own prefix's fingerprint in a
+test. The tool catalog is `tools.catalog_text`.
+
+A sub-agent starts from its parent's exact prefix (the fork rule: same tools,
+same system, so it reads the parent's cache) and gets its brief as its first
+user turn (`subagent_brief`).
+"""
+
+from __future__ import annotations
+
+from spatialagents.wire import canonical, text_block
+
+#: The identity of a conversation whose product gave none: neutral, for tests and tools.
+DEFAULT_IDENTITY = (
+    "You are the assistant inside a scientific application. You answer the user's questions about "
+    "their data by calling the application's tools, and you change things only when the user asked "
+    "for the change."
+)
+
+DEFAULT_RULES = (
+    "HOUSE RULES\n"
+    "1. Start from the user's question, not from a tool name.\n"
+    "2. The tool catalog below lists every tool you may use by name and purpose. To use one, call "
+    "load_tool with its name (several at once if you will need several): it returns each tool's full "
+    "definition. Then run the tool with call_tool, giving its name and arguments that match that "
+    "definition. Load only what you need.\n"
+    "3. Claim only what a tool returned. Say which sentences are a result, which are your reading of it "
+    "and which are background knowledge.\n"
+    "4. A tool that writes into the user's source files or cannot be undone waits for the user's "
+    "approval; if the user declines, do not try another way round.\n"
+    "5. A large result arrives as a stub with an artifact_id, a head and a tail; read_artifact returns "
+    "the slices you need.\n"
+    "6. Be brief. The output is AI-generated and the user verifies it before relying on it."
+)
+
+
+def build_prefix(identity: str, rules: str, skill_text: str, catalog_text: str, *,
+                 skill: str = "dataset-triage") -> list:
+    """The system prompt of a conversation: identity and house rules, one short
+    skill, then the frozen tool catalog, with the only breakpoint last.
+    Byte-stable for one build, policy and plugin set; nothing per-conversation."""
+    return [text_block(identity + "\n\n" + rules),
+            text_block(f"SKILL {skill}\n" + (skill_text or "")),
+            text_block(catalog_text, cache=True)]
+
+
+def default_prefix(catalog_text: str) -> list:
+    """`build_prefix` with the neutral identity and rules, and no skill text."""
+    return build_prefix(DEFAULT_IDENTITY, DEFAULT_RULES, "", catalog_text)
+
+
+def subagent_brief(role: str, brief: str, tools: list, inputs: dict | None = None, *,
+                   parent: str = "the main conversation") -> str:
+    """The first user turn of a sub-agent, after the parent's exact prefix (the
+    fork rule: same tools, same system, so the sub-agent reads the parent's
+    cache). `parent` is how the product names the conversation it works for
+    ("the main Plexora AI conversation")."""
+    lines = [f"You are a sub-agent ({role}) working for {parent}. Do only this:",
+             brief.strip(),
+             "Tools you may call: " + (", ".join(tools) if tools else "the read-only tools") + ".",
+             "When you are done, reply with ONE JSON object and nothing else: "
+             '{"summary": "<two or three sentences>", "findings": ["..."], "operation_ids": ["..."], '
+             '"artifact_ids": ["..."]}.']
+    if inputs:
+        lines.insert(2, "Inputs: " + canonical(inputs))
+    return "\n".join(lines)