activegraph 1.0.0rc2__py3-none-any.whl

activegraph/packs/scaffold.py

@@ -0,0 +1,317 @@
+"""`activegraph pack new <name>` scaffolding. CONTRACT v0.9 #14.
+
+Generates a runnable Python package layout that:
+  - declares activegraph as a dependency
+  - registers itself under the activegraph.packs entry point
+  - has stubs for object types, behaviors, tools, settings
+  - has a smoke test that imports the pack and verifies no global
+    registry side effects, then loads it into a fresh runtime
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+_PACK_NAME_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+def normalize_pack_name(raw: str) -> tuple[str, str]:
+    """Return `(directory_name, python_module_name)`.
+
+    - kebab → snake for the module name (Python package directories
+      can be kebab-case for distribution but the import name is the
+      snake form, per packaging conventions).
+    - lowercases and validates.
+    """
+    name = raw.strip().lower()
+    if not _PACK_NAME_RE.match(name):
+        raise ValueError(
+            f"pack name {raw!r} must match [a-z][a-z0-9-]* (lowercase, ASCII)"
+        )
+    return name, name.replace("-", "_")
+
+
+def scaffold_pack(target_dir: Path, raw_name: str) -> Path:
+    """Generate the pack at `target_dir / pack_name`. Returns the
+    created path. Raises FileExistsError if the directory already
+    exists.
+    """
+    pack_name, module_name = normalize_pack_name(raw_name)
+    root = target_dir / pack_name
+    if root.exists():
+        raise FileExistsError(f"{root} already exists")
+    root.mkdir(parents=True)
+    (root / module_name).mkdir()
+    (root / module_name / "prompts").mkdir()
+    (root / "tests").mkdir()
+
+    files = {
+        root / "pyproject.toml": _PYPROJECT_TEMPLATE.format(
+            pack_name=pack_name, module_name=module_name
+        ),
+        root / "README.md": _README_TEMPLATE.format(pack_name=pack_name, module_name=module_name),
+        root / module_name / "__init__.py": _render_init(pack_name, module_name),
+        root / module_name / "object_types.py": _OBJECT_TYPES_TEMPLATE,
+        root / module_name / "behaviors.py": _BEHAVIORS_TEMPLATE.format(
+            module_name=module_name
+        ),
+        root / module_name / "tools.py": _TOOLS_TEMPLATE,
+        root / module_name / "settings.py": _SETTINGS_TEMPLATE.format(
+            pack_name_title=_title(module_name)
+        ),
+        root / module_name / "prompts" / "example_prompt.md": _PROMPT_TEMPLATE,
+        root / "tests" / "test_pack_loads.py": _SMOKE_TEST_TEMPLATE.format(
+            module_name=module_name, pack_name=pack_name
+        ),
+    }
+    for path, content in files.items():
+        path.write_text(content, encoding="utf-8")
+    return root
+
+
+# ---------------------------------------------------- templates
+
+
+_PYPROJECT_TEMPLATE = """\
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "{pack_name}"
+version = "0.1.0"
+description = "An activegraph pack."
+requires-python = ">=3.11"
+dependencies = ["activegraph>=0.9", "pydantic>=2"]
+
+[project.entry-points."activegraph.packs"]
+{pack_name} = "{module_name}:pack"
+
+[tool.setuptools.packages.find]
+include = ["{module_name}*"]
+"""
+
+
+_README_TEMPLATE = """\
+# {pack_name}
+
+An [activegraph](https://github.com/yoheinakajima/activegraph) pack.
+
+## Install
+
+```sh
+pip install -e .
+```
+
+## Use
+
+```python
+from activegraph import Runtime, Graph
+from activegraph.packs import load_by_name
+
+rt = Runtime(Graph(), llm_provider=...)
+rt.load_pack(load_by_name("{pack_name}"))
+rt.run_goal("...")
+```
+
+## Develop
+
+```sh
+pip install -e .[dev]
+pytest
+```
+
+Pack authoring guide:
+<https://github.com/yoheinakajima/activegraph/blob/main/docs/pack_authoring.md>
+"""
+
+
+_PACK_INIT_TEMPLATE = '''\
+"""{module_name} — an activegraph pack."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from activegraph.packs import Pack, load_prompts_from_dir
+
+from {module_name}.behaviors import BEHAVIORS
+from {module_name}.object_types import OBJECT_TYPES, RELATION_TYPES
+from {module_name}.settings import {pack_name_title}Settings
+from {module_name}.tools import TOOLS
+
+
+_PROMPTS_DIR = Path(__file__).parent / "prompts"
+
+
+pack = Pack(
+    name="{module_name}",
+    version="0.1.0",
+    description="An activegraph pack.",
+    object_types=OBJECT_TYPES,
+    relation_types=RELATION_TYPES,
+    behaviors=BEHAVIORS,
+    tools=TOOLS,
+    prompts=load_prompts_from_dir(_PROMPTS_DIR),
+    settings_schema={pack_name_title}Settings,
+)
+
+
+__all__ = ["pack", "{pack_name_title}Settings"]
+'''
+
+
+def _title(name: str) -> str:
+    return "".join(p.capitalize() for p in name.split("_"))
+
+
+# Patch the template generation to insert the titled class name
+def _render_init(pack_name: str, module_name: str) -> str:
+    return _PACK_INIT_TEMPLATE.format(
+        pack_name=pack_name,
+        module_name=module_name,
+        pack_name_title=_title(module_name),
+    )
+
+
+_OBJECT_TYPES_TEMPLATE = '''\
+"""Object types and relation types declared by this pack."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from activegraph.packs import ObjectType, RelationType
+
+
+class Item(BaseModel):
+    name: str
+    notes: str = ""
+
+
+OBJECT_TYPES = [
+    ObjectType(name="item", schema=Item, description="An example item."),
+]
+
+
+RELATION_TYPES = [
+    # RelationType(name="...", source_types=("item",), target_types=("item",)),
+]
+'''
+
+
+_BEHAVIORS_TEMPLATE = '''\
+"""Pack behaviors. Decorators imported from `activegraph.packs` so
+they do NOT register globally (CONTRACT v0.9 #3)."""
+
+from __future__ import annotations
+
+from activegraph.packs import behavior
+
+
+@behavior(name="hello", on=["goal.created"])
+def hello(event, graph, ctx):
+    """Example behavior. Replace with your own."""
+    graph.add_object("item", {{"name": "hello world"}})
+
+
+BEHAVIORS = [hello]
+'''
+
+
+_TOOLS_TEMPLATE = '''\
+"""Pack-scoped tools. CONTRACT v0.9 #9.
+
+Tools declared here are registered with the `{pack}.{name}` canonical
+form when the pack loads. Pass `export_globally=True` to ALSO register
+the short form globally.
+"""
+
+from __future__ import annotations
+
+from activegraph.packs import tool
+
+
+# Add your tools here, e.g.:
+# from pydantic import BaseModel
+#
+# class FooIn(BaseModel):
+#     x: str
+#
+# class FooOut(BaseModel):
+#     y: str
+#
+# @tool(name="foo", input_schema=FooIn, output_schema=FooOut)
+# def foo(args: FooIn, ctx) -> FooOut:
+#     return FooOut(y=args.x.upper())
+
+
+TOOLS: list = []
+'''
+
+
+_SETTINGS_TEMPLATE = '''\
+"""Settings model for the pack. Accessed by behaviors via typed
+parameter injection or `ctx.settings`."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class {pack_name_title}Settings(BaseModel):
+    """Pack settings. Add fields as needed. All fields should have
+    defaults so `runtime.load_pack(pack)` works without explicit
+    `settings=`.
+    """
+
+    threshold: float = 0.5
+'''
+
+
+_PROMPT_TEMPLATE = """---
+version = "1.0.0"
+---
+You are an example behavior. Replace this prompt with your own.
+
+When wired to an `@llm_behavior` with the same `name=`, this body
+becomes part of the behavior's system prompt. The runtime
+auto-injects view and triggering-event blocks into the user message.
+
+Content is hashed for replay determinism — if you edit this prompt,
+the hash changes, even if you forget to bump the declared version.
+"""
+
+
+_SMOKE_TEST_TEMPLATE = '''\
+"""Smoke test: the pack imports without side effects and loads cleanly."""
+
+from __future__ import annotations
+
+from activegraph import Graph, Runtime, clear_registry, clear_tool_registry, get_registry, get_tool_registry
+
+
+def test_import_has_no_global_side_effects():
+    """CONTRACT v0.9 #3: pack-aware decorators don't register globally."""
+    clear_registry()
+    clear_tool_registry()
+    import {module_name}  # noqa: F401
+    assert get_registry() == [], (
+        "importing the pack registered behaviors globally — pack code must "
+        "use activegraph.packs decorators, not activegraph decorators"
+    )
+    assert get_tool_registry() == [], (
+        "importing the pack registered tools globally"
+    )
+
+
+def test_pack_loads_into_fresh_runtime():
+    from {module_name} import pack
+    rt = Runtime(Graph())
+    rt.load_pack(pack)
+    pack_loaded_events = [e for e in rt.graph.events if e.type == "pack.loaded"]
+    assert len(pack_loaded_events) == 1
+    assert pack_loaded_events[0].payload["name"] == "{module_name}"
+'''

activegraph/policy.py

@@ -0,0 +1,20 @@
+"""Per-behavior policy. v0 is permissive — fields are recorded but not enforced
+beyond a couple of obvious checks. Hardening lands in v0.6 alongside LLM
+behaviors, where unbounded tool/cost spend is the real risk.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Policy:
+    behavior: Optional[str] = None
+    can_create: list[str] = field(default_factory=list)
+    can_create_relation: list[str] = field(default_factory=list)
+    can_propose: list[str] = field(default_factory=list)
+    can_apply: list[str] = field(default_factory=list)
+    can_call_tool: list[str] = field(default_factory=list)
+    requires_approval: list[str] = field(default_factory=list)

activegraph/runtime/__init__.py

@@ -0,0 +1 @@
+"""Runtime layer. Imports core/ and behaviors/."""

activegraph/runtime/behavior_graph.py

@@ -0,0 +1,151 @@
+"""Constrained graph wrapper passed to behaviors. CONTRACT #7.
+
+Allowed methods: add_object, add_relation, patch_object, propose_patch, emit.
+The wrapper stamps actor / caused_by / frame_id automatically (CONTRACT #5)
+and counts mutations so the runtime can report them in behavior.completed.
+
+Behaviors get this object as their `graph` argument — never the raw Graph.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from activegraph.core.event import Event
+from activegraph.core.graph import Graph, Object, Relation
+from activegraph.core.patch import Patch
+
+
+class Counters:
+    __slots__ = ("objects_created", "relations_created", "patches_applied", "patches_proposed", "events_emitted")
+
+    def __init__(self) -> None:
+        self.objects_created = 0
+        self.relations_created = 0
+        self.patches_applied = 0
+        self.patches_proposed = 0
+        self.events_emitted = 0  # user-emitted via emit(), not graph mutations
+
+
+class BehaviorGraph:
+    def __init__(
+        self,
+        graph: Graph,
+        *,
+        actor: str,
+        caused_by: Optional[str],
+        frame_id: Optional[str],
+        llm_request_event_id: Optional[str] = None,
+        tool_request_event_ids: Optional[list[str]] = None,
+    ) -> None:
+        self._graph = graph
+        self._actor = actor
+        self._caused_by = caused_by
+        self._frame_id = frame_id
+        # CONTRACT v0.6 #15: when this BehaviorGraph was created for an
+        # @llm_behavior handler, every object/relation/patch it creates
+        # carries the originating llm.requested event id in provenance.
+        self._llm_request_event_id = llm_request_event_id
+        # CONTRACT v0.7 #19: when the LLM behavior's turn loop invoked
+        # tools, the tool.requested event ids are stamped into the
+        # provenance of every object/relation/patch the handler
+        # creates. Causal-chain walks can then enumerate every tool
+        # call that contributed to a claim.
+        self._tool_request_event_ids: list[str] = list(
+            tool_request_event_ids or []
+        )
+        self.counters = Counters()
+
+    # ---- mutators ----
+
+    def add_object(self, type: str, data: dict[str, Any]) -> Object:
+        obj = self._graph.add_object(
+            type=type,
+            data=data,
+            actor=self._actor,
+            caused_by=self._caused_by,
+            frame_id=self._frame_id,
+            llm_request_event_id=self._llm_request_event_id,
+            tool_request_event_ids=self._tool_request_event_ids,
+        )
+        self.counters.objects_created += 1
+        return obj
+
+    def add_relation(
+        self,
+        source: str,
+        target: str,
+        type: str,
+        data: Optional[dict[str, Any]] = None,
+    ) -> Relation:
+        rel = self._graph.add_relation(
+            source=source,
+            target=target,
+            type=type,
+            data=data,
+            actor=self._actor,
+            caused_by=self._caused_by,
+            frame_id=self._frame_id,
+            llm_request_event_id=self._llm_request_event_id,
+            tool_request_event_ids=self._tool_request_event_ids,
+        )
+        self.counters.relations_created += 1
+        return rel
+
+    def patch_object(self, target: str, updates: dict[str, Any]) -> Patch:
+        patch = self._graph.patch_object(
+            target=target,
+            updates=updates,
+            actor=self._actor,
+            caused_by=self._caused_by,
+            frame_id=self._frame_id,
+            llm_request_event_id=self._llm_request_event_id,
+            tool_request_event_ids=self._tool_request_event_ids,
+        )
+        self.counters.patches_applied += 1
+        return patch
+
+    def propose_patch(
+        self,
+        target: str,
+        op: str = "update",
+        value: Optional[dict[str, Any]] = None,
+        rationale: Optional[str] = None,
+        evidence: Optional[list[str]] = None,
+    ) -> Patch:
+        patch = self._graph.propose_patch(
+            target=target,
+            op=op,
+            value=value or {},
+            proposed_by=self._actor,
+            rationale=rationale,
+            evidence=evidence,
+            caused_by=self._caused_by,
+            frame_id=self._frame_id,
+            llm_request_event_id=self._llm_request_event_id,
+            tool_request_event_ids=self._tool_request_event_ids,
+        )
+        self.counters.patches_proposed += 1
+        return patch
+
+    def emit(self, event_type: str, payload: dict[str, Any]) -> Event:
+        ev = Event(
+            id=self._graph.ids.event(),
+            type=event_type,
+            payload=dict(payload),
+            actor=self._actor,
+            frame_id=self._frame_id,
+            caused_by=self._caused_by,
+            timestamp=self._graph.clock.now(),
+        )
+        self._graph.emit(ev)
+        self.counters.events_emitted += 1
+        return ev
+
+    # ---- read passthroughs (not iteration; that goes through ctx.view) ----
+
+    def get_object(self, id_: str) -> Optional[Object]:
+        return self._graph.get_object(id_)
+
+    def get_relation(self, id_: str) -> Optional[Relation]:
+        return self._graph.get_relation(id_)

activegraph/runtime/budget.py

@@ -0,0 +1,120 @@
+"""Hard limits on a run. When any limit is hit the runtime stops gracefully
+and emits runtime.budget_exhausted.
+
+CONTRACT v0.6 #9: `max_cost_usd` is tracked in `Decimal` so cents don't
+drift across thousands of LLM calls. The rest of the dimensions stay
+float — they're integer-shaped (event counts, behavior calls). The
+pre-call cost check is conservative (uses `max_tokens` as the output
+estimate) and is *only* performed when `max_cost_usd` is finite AND no
+cached response was found (decision-4 adjustment).
+"""
+
+from __future__ import annotations
+
+import time
+from decimal import Decimal
+from typing import Any, Optional
+
+
+KNOWN_LIMITS = (
+    "max_events",
+    "max_behavior_calls",
+    "max_llm_calls",
+    "max_tool_calls",
+    "max_patches",
+    "max_depth",
+    "max_seconds",
+    "max_cost_usd",
+)
+
+
+def _as_decimal(v: Any) -> Decimal:
+    if isinstance(v, Decimal):
+        return v
+    return Decimal(str(v))
+
+
+class Budget:
+    def __init__(self, limits: Optional[dict[str, Any]] = None) -> None:
+        self.limits: dict[str, float] = {}
+        self.cost_limit: Optional[Decimal] = None
+        for k in KNOWN_LIMITS:
+            v = (limits or {}).get(k)
+            if k == "max_cost_usd":
+                # Track cost as a Decimal so per-call sub-cent costs add
+                # up cleanly. None / missing → no cost ceiling.
+                self.cost_limit = _as_decimal(v) if v is not None else None
+                # Mirror as float for snapshot / has-it semantics.
+                self.limits[k] = (
+                    float(self.cost_limit) if self.cost_limit is not None else float("inf")
+                )
+            else:
+                self.limits[k] = float(v) if v is not None else float("inf")
+        self.used: dict[str, float] = {k: 0.0 for k in self.limits}
+        self.cost_used: Decimal = Decimal("0")
+        self._start: Optional[float] = None
+        self._exhausted_by: Optional[str] = None
+
+    # ---- generic counter dimensions ----
+
+    def start(self) -> None:
+        self._start = time.monotonic()
+
+    def consume(self, key: str, amount: float = 1.0) -> None:
+        self.used[key] = self.used.get(key, 0.0) + amount
+
+    def exhausted_by(self) -> Optional[str]:
+        return self._exhausted_by
+
+    def remaining(self) -> bool:
+        for k, limit in self.limits.items():
+            if k == "max_seconds":
+                if self._start is None:
+                    continue
+                if time.monotonic() - self._start >= limit:
+                    self._exhausted_by = k
+                    return False
+                continue
+            if k == "max_cost_usd":
+                if self.cost_limit is not None and self.cost_used >= self.cost_limit:
+                    self._exhausted_by = k
+                    return False
+                continue
+            if self.used.get(k, 0.0) >= limit:
+                self._exhausted_by = k
+                return False
+        return True
+
+    # ---- cost dimension (Decimal) ----
+
+    def has_cost_limit(self) -> bool:
+        return self.cost_limit is not None
+
+    def add_cost(self, amount: Decimal) -> None:
+        self.cost_used += _as_decimal(amount)
+        # Mirror to the float snapshot view so existing readers see it.
+        self.used["max_cost_usd"] = float(self.cost_used)
+
+    def cost_remaining(self, prospective_cost: Decimal) -> bool:
+        """Would `prospective_cost` push us past the ceiling? Returns
+        True if it's safe to spend, False if it would exceed."""
+        if self.cost_limit is None:
+            return True
+        return (self.cost_used + _as_decimal(prospective_cost)) <= self.cost_limit
+
+    def cost_remaining_amount(self) -> Optional[Decimal]:
+        if self.cost_limit is None:
+            return None
+        remaining = self.cost_limit - self.cost_used
+        return remaining if remaining > 0 else Decimal("0")
+
+    def snapshot(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"used": dict(self.used), "limits": {}}
+        for k, v in self.limits.items():
+            out["limits"][k] = None if v == float("inf") else v
+        # Expose cost as Decimal-string too so consumers can choose precision.
+        out["cost_used_usd"] = str(self.cost_used)
+        out["cost_limit_usd"] = (
+            str(self.cost_limit) if self.cost_limit is not None else None
+        )
+        return out