aethergraph 0.1.0a3__py3-none-any.whl → 0.1.0a4__py3-none-any.whl

aethergraph/services/planning/planner_service.py

@@ -0,0 +1,369 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import inspect
+from typing import TYPE_CHECKING, Any
+
+from aethergraph.api.v1.deps import RequestIdentity
+from aethergraph.contracts.services.llm import LLMClientProtocol
+from aethergraph.core.runtime.run_types import (
+    RunImportance,
+    RunOrigin,
+    RunVisibility,
+)
+
+if TYPE_CHECKING:
+    from aethergraph.core.runtime.run_manager import RunManager
+
+from .action_catalog import ActionCatalog
+from .input_parser import InputParser, ParsedInputs
+from .plan_executor import (
+    BackgroundExecutionHandle,
+    ExecutionResult,
+    OnCompleteCallback,
+    PlanExecutor,
+)
+from .plan_types import (
+    CandidatePlan,
+    ExecutionEventCallback,
+    PlanningContext,
+    PlanningEvent,
+    PlanningEventCallback,
+    PlanResult,
+    ValidationResult,
+)
+from .planner import ActionPlanner
+
+
+@dataclass
+class PlannerService:
+    """
+    High-level planning facade exposed as `context.planner()`.
+
+    Internally composes:
+      - ActionCatalog
+      - ActionPlanner
+      - PlanExecutor
+      - InputParser
+    """
+
+    catalog: ActionCatalog
+    llm: LLMClientProtocol
+    validator: Any  # FlowValidator
+    run_manager: RunManager | None = None  # for executing plans
+
+    # Lazily initialized components
+    _planner: ActionPlanner | None = None
+    _executor: PlanExecutor | None = None
+    _input_parser: InputParser | None = None
+
+    @property
+    def planner_core(self) -> ActionPlanner:
+        if self._planner is None:
+            self._planner = ActionPlanner(
+                catalog=self.catalog,
+                validator=self.validator,
+                llm=self.llm,
+            )
+        return self._planner
+
+    @property
+    def executor(self) -> PlanExecutor:
+        if self._executor is None:
+            self._executor = PlanExecutor(catalog=self.catalog, run_manager=self.run_manager)
+        return self._executor
+
+    @property
+    def input_parser(self) -> InputParser:
+        if self._input_parser is None:
+            self._input_parser = InputParser(llm=self.llm)
+        return self._input_parser
+
+    # ------------- Planning API -------------
+    async def plan(
+        self,
+        *,
+        goal: str,
+        user_inputs: dict[str, Any] | None = None,
+        external_slots: dict[str, Any] | None = None,  # advanced use with IO slots
+        flow_ids: list[str] | None = None,
+        instruction: str | None = None,
+        allow_partial: bool = True,
+        preferred_external_keys: list[str] | None = None,
+        memory_snippets: list[str] | None = None,
+        artifact_snippets: list[str] | None = None,
+        on_event: PlanningEventCallback | None = None,
+    ) -> PlanResult:
+        """
+        Ergonomic entrypoint: build a PlanningContext and delegate to plan_with_context().
+        """
+        ctx = PlanningContext(
+            goal=goal,
+            user_inputs=user_inputs or {},
+            external_slots=external_slots or {},
+            memory_snippets=list(memory_snippets or []),
+            artifact_snippets=list(artifact_snippets or []),
+            flow_ids=list(flow_ids) if flow_ids is not None else None,
+            instruction=instruction,
+            allow_partial_plans=allow_partial,
+            preferred_external_keys=list(preferred_external_keys or []),
+        )
+        return await self.plan_with_context(ctx, on_event=on_event)
+
+    async def plan_with_context(
+        self,
+        ctx: PlanningContext,
+        *,
+        on_event: PlanningEventCallback | None = None,
+    ) -> PlanResult:
+        """
+        Plan towards the goal in the given context.
+        Emits PlanningEvents via on_event callback.
+        """
+        events: list[PlanningEvent] = []
+
+        async def _capture(ev: PlanningEvent) -> None:
+            # Always record locally
+            events.append(ev)
+
+            # Forward to caller if provided
+            if on_event:
+                result = on_event(ev)
+                if inspect.isawaitable(result):
+                    await result
+
+        plan, history = await self.planner_core.plan_with_loop(
+            ctx,
+            on_event=_capture,
+        )
+
+        validation: ValidationResult | None
+        validation = history[-1] if history else None
+
+        return PlanResult(plan=plan, validation=validation, events=events)
+
+    # ------------- input parsing API -------------
+    async def parse_inputs(
+        self,
+        *,
+        message: str,
+        missing_keys: list[str],
+        instruction: str | None = None,  # currently unused, keep for future use
+    ) -> ParsedInputs:
+        """
+        Parse user message into structured inputs for the given inputs.
+        """
+        # For now we ignore `instruction` and rely on meta,
+        # We can thread it into the system prompt later.
+        return await self.input_parser.parse_message_for_fields(
+            message=message,
+            missing_keys=missing_keys,
+            instruction=instruction,
+        )
+
+    async def execute_plan(
+        self,
+        plan: CandidatePlan,
+        *,
+        user_inputs: dict[str, Any] | None = None,
+        on_event: ExecutionEventCallback | None = None,
+        identity: RequestIdentity | None = None,
+        visibility: RunVisibility = RunVisibility.normal,
+        importance: RunImportance = RunImportance.normal,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        tags: list[str] | None = None,
+        origin: RunOrigin | None = None,
+    ) -> ExecutionResult:
+        return await self.executor.execute(
+            plan,
+            user_inputs=user_inputs,
+            on_event=on_event,
+            identity=identity,
+            visibility=visibility,
+            importance=importance,
+            session_id=session_id,
+            agent_id=agent_id,
+            app_id=app_id,
+            tags=tags,
+            origin=origin,
+        )
+
+    async def execute_background(
+        self,
+        plan: CandidatePlan,
+        *,
+        user_inputs: dict[str, Any] | None = None,
+        on_event: ExecutionEventCallback | None = None,
+        identity: RequestIdentity | None = None,
+        visibility: RunVisibility = RunVisibility.normal,
+        importance: RunImportance = RunImportance.normal,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        tags: list[str] | None = None,
+        origin: RunOrigin | None = None,
+        on_complete: OnCompleteCallback | None = None,
+        exec_id: str | None = None,
+    ) -> BackgroundExecutionHandle:
+        """
+        Schedule plan execution in the background and return a handle.
+
+        This is async only for API consistency with other services;
+        it returns as soon as the background task is scheduled.
+        """
+        handle = self.executor.execute_background(
+            plan,
+            user_inputs=user_inputs,
+            on_event=on_event,
+            identity=identity,
+            visibility=visibility,
+            importance=importance,
+            session_id=session_id,
+            agent_id=agent_id,
+            app_id=app_id,
+            tags=tags,
+            origin=origin,
+            on_complete=on_complete,
+            exec_id=exec_id,
+        )
+        return handle
+
+    async def plan_and_execute(
+        self,
+        *,
+        goal: str,
+        user_inputs: dict[str, Any] | None = None,
+        external_slots: dict[str, Any] | None = None,
+        flow_ids: list[str] | None = None,
+        instruction: str | None = None,
+        allow_partial: bool = False,
+        preferred_external_keys: list[str] | None = None,
+        memory_snippets: list[str] | None = None,
+        artifact_snippets: list[str] | None = None,
+        planning_events_cb: PlanningEventCallback | None = None,
+        execution_events_cb: ExecutionEventCallback | None = None,
+        identity: RequestIdentity | None = None,
+        visibility: RunVisibility | None = RunVisibility.normal,
+        importance: RunImportance | None = RunImportance.normal,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        tags: list[str] | None = None,
+        origin: RunOrigin | None = None,
+    ) -> tuple[PlanResult, ExecutionResult | None]:
+        """
+        Convenience: plan first, then execute if plan is acceptable.
+        """
+        plan_result = await self.plan(
+            goal=goal,
+            user_inputs=user_inputs,
+            external_slots=external_slots,
+            flow_ids=flow_ids,
+            instruction=instruction,
+            allow_partial=allow_partial,
+            preferred_external_keys=preferred_external_keys,
+            memory_snippets=memory_snippets,
+            artifact_snippets=artifact_snippets,
+            on_event=planning_events_cb,
+        )
+
+        plan = plan_result.plan
+        validation = plan_result.validation
+
+        if plan is None or validation is None:
+            return plan_result, None
+
+        accept_partial = allow_partial and validation.is_partial_ok()
+        if not validation.ok and not accept_partial:
+            # Invalid plan and partial not allowed → do not execute
+            return plan_result, None
+
+        exec_result = await self.execute_plan(
+            plan,
+            user_inputs=user_inputs,
+            on_event=execution_events_cb,
+            identity=identity,
+            visibility=visibility,
+            importance=importance,
+            session_id=session_id,
+            agent_id=agent_id,
+            app_id=app_id,
+            tags=tags,
+            origin=origin,
+        )
+
+        return plan_result, exec_result
+
+    async def plan_and_execute_background(
+        self,
+        *,
+        goal: str,
+        user_inputs: dict[str, Any] | None = None,
+        external_slots: dict[str, Any] | None = None,
+        flow_ids: list[str] | None = None,
+        instruction: str | None = None,
+        allow_partial: bool = False,
+        preferred_external_keys: list[str] | None = None,
+        memory_snippets: list[str] | None = None,
+        artifact_snippets: list[str] | None = None,
+        planning_events_cb: PlanningEventCallback | None = None,
+        execution_events_cb: ExecutionEventCallback | None = None,
+        identity: RequestIdentity | None = None,
+        visibility: RunVisibility | None = RunVisibility.normal,
+        importance: RunImportance | None = RunImportance.normal,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        tags: list[str] | None = None,
+        origin: RunOrigin | None = None,
+        on_complete: OnCompleteCallback | None = None,
+        exec_id: str | None = None,
+    ) -> tuple[PlanResult, BackgroundExecutionHandle | None]:
+        """
+        Plan first, then execute the plan in the background if acceptable.
+
+        Returns:
+          (PlanResult, BackgroundExecutionHandle | None)
+        """
+        plan_result = await self.plan(
+            goal=goal,
+            user_inputs=user_inputs,
+            external_slots=external_slots,
+            flow_ids=flow_ids,
+            instruction=instruction,
+            allow_partial=allow_partial,
+            preferred_external_keys=preferred_external_keys,
+            memory_snippets=memory_snippets,
+            artifact_snippets=artifact_snippets,
+            on_event=planning_events_cb,
+        )
+
+        plan = plan_result.plan
+        validation = plan_result.validation
+
+        if plan is None or validation is None:
+            return plan_result, None
+
+        accept_partial = allow_partial and validation.is_partial_ok()
+        if not validation.ok and not accept_partial:
+            return plan_result, None
+
+        handle = await self.execute_background(
+            plan,
+            user_inputs=user_inputs,
+            on_event=execution_events_cb,
+            identity=identity,
+            visibility=visibility,
+            importance=importance,
+            session_id=session_id,
+            agent_id=agent_id,
+            app_id=app_id,
+            tags=tags,
+            origin=origin,
+            on_complete=on_complete,
+            exec_id=exec_id,
+        )
+
+        return plan_result, handle

aethergraph/services/planning/planning_context_builder.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from aethergraph.contracts.services.planning import (
+    PlanningContextBuilderProtocol,
+    RoutedIntent,
+    SessionState,
+)
+from aethergraph.services.planning.planner import PlanningContext
+
+
+@dataclass
+class SimplePlanningContextBuilder(PlanningContextBuilderProtocol):
+    """
+    Baseline builder: treat the raw user message as goal and
+    pass through user_inputs as-is (you can enrich with RAG later).
+    """
+
+    def _extract_user_inputs(self, user_message: str) -> dict[str, Any]:
+        # For now: rely on external caller to provide user_inputs;
+        # later add LLM-based extraction or explicit forms.
+        return {}
+
+    async def build(
+        self,
+        *,
+        user_message: str,
+        routed: RoutedIntent,
+        session_state: SessionState,
+    ) -> PlanningContext:
+        goal = user_message.strip()
+        user_inputs = self._extract_user_inputs(user_message)
+
+        return PlanningContext(
+            goal=goal,
+            user_inputs=user_inputs,
+            external_slots={},  # you can thread structured external inputs later
+            memory_snippets=[],  # future: fetch from ctx.memory()
+            artifact_snippets=[],  # future: fetch from indices/artifacts
+            flow_ids=routed.flow_ids,
+        )

aethergraph/services/planning/quick_actions.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass
+class QuickActionSpec:
+    id: str
+    description: str
+    # e.g. `list_recent_runs`, `open_notebook`, `answer_with_rag`
+    requires_confirmation: bool = False
+    action_ref: str | None = None  # optional link to ActionSpec.ref
+
+
+class QuickActionHandler(Protocol):
+    async def __call__(self, *, context: Any) -> Any: ...
+
+
+@dataclass
+class QuickActionRegistry:
+    actions: dict[str, QuickActionSpec]
+    handlers: dict[str, QuickActionHandler]
+
+    def get_spec(self, action_id: str) -> QuickActionSpec | None:
+        return self.actions.get(action_id)
+
+    def get_handler(self, action_id: str) -> QuickActionHandler | None:
+        return self.handlers.get(action_id)

aethergraph/services/planning/routers/simple_router.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from aethergraph.contracts.services.planning import IntentRouter, RoutedIntent, SessionState
+
+
+@dataclass
+class SimpleIntentRouter(IntentRouter):
+    """
+    Docstring for SimpleIntentRouter
+    """
+
+    async def route(
+        self,
+        *,
+        user_message: str,
+        session_state: SessionState,
+    ) -> RoutedIntent:
+        # Simple routing logic: always plan and execute with no specific flows
+        return RoutedIntent(
+            mode="plan_and_execute",
+            flow_ids=None,
+            quick_action_id=None,
+            metadata={},
+        )

aethergraph/services/rag/facade.py

@@ -439,9 +439,6 @@ class RAGFacade:
             k: Number of top results to return.
             rerank: Whether to rerank results using hybrid scoring.
         """
-        print(
-            f"🍏 RAGFacade.retrieve: corpus_id={corpus_id}, query={query}, k={k}, rerank={rerank}"
-        )
         # For now, rerank flag is ignored; fused hybrid already sorts reasonably.
         return await self.search(corpus_id, query, k=k, mode="hybrid")
 

aethergraph/services/scope/scope.py

@@ -14,6 +14,7 @@ class Scope:
 
     # App / execution context
     app_id: str | None = None
+    agent_id: str | None = None
     session_id: str | None = None
     run_id: str | None = None
     graph_id: str | None = None
@@ -36,10 +37,13 @@ class Scope:
     def get(self, key: str, default: Any = None) -> Any:
         return getattr(self, key, default)
 
-    def artifact_scope_labels(self) -> dict[str, str]:
+    def _base_identity_labels(self) -> dict[str, str]:
         """
-        Labels to attach to every artifact for this scope.
-        These will be mirrored both into Artifact.labels and the index.
+        Docstring for _base_identity_labels
+
+        :param self: Description
+        :return: Description
+        :rtype: dict[str, str]
         """
         out: dict[str, str] = {}
         if self.org_id:
@@ -50,6 +54,8 @@ class Scope:
             out["client_id"] = self.client_id
         if self.app_id:
             out["app_id"] = self.app_id
+        if self.agent_id:
+            out["agent_id"] = self.agent_id
         if self.session_id:
             out["session_id"] = self.session_id
         if self.run_id:
@@ -58,16 +64,21 @@ class Scope:
             out["graph_id"] = self.graph_id
         if self.node_id:
             out["node_id"] = self.node_id
+        if self.flow_id:
+            out["flow_id"] = self.flow_id
+        return out
 
-        # canonicial scope ids
-        if self.session_id:
-            out["scope_id"] = self.session_id  # session-centric
-        elif self.run_id:
-            out["scope_id"] = self.run_id  # run-centric for non-session runs
-        elif self.graph_id:
-            out["scope_id"] = f"graph:{self.graph_id}"  # graph-centric for non-run artifacts
-        elif self.node_id:
-            out["scope_id"] = f"node:{self.node_id}"  # node-centric for non-graph artifacts
+    def artifact_scope_labels(self) -> dict[str, str]:
+        """
+        Labels to attach to every artifact for this scope.
+        These will be mirrored both into Artifact.labels and the index.
+        """
+        out: dict[str, str] = {}
+        out.update(self._base_identity_labels())
+
+        # Cononical scope id for artifacts == memory scope id
+        # So filter the memory + artifacts by the same value
+        out["scope_id"] = self.memory_scope_id()
         return out
 
     def metering_dimensions(self) -> dict[str, Any]:
@@ -123,22 +134,7 @@ class Scope:
         but can be any logical scope key.
         """
         out: dict[str, Any] = {}
-        if self.user_id:
-            out["user_id"] = self.user_id
-        if self.org_id:
-            out["org_id"] = self.org_id
-        if self.client_id:
-            out["client_id"] = self.client_id
-        if self.app_id:
-            out["app_id"] = self.app_id
-        if self.session_id:
-            out["session_id"] = self.session_id
-        if self.run_id:
-            out["run_id"] = self.run_id
-        if self.graph_id:
-            out["graph_id"] = self.graph_id
-        if self.node_id:
-            out["node_id"] = self.node_id
+        out.update(self._base_identity_labels())
         if scope_id:
             out["scope_id"] = scope_id
         return out
@@ -146,14 +142,18 @@ class Scope:
     def rag_filter(self, *, scope_id: str | None = None) -> dict[str, Any]:
         """
         Default filter for RAG search based on identity.
-        You can adjust strictness (e.g., ignore run_id for per-user corpora).
+
+        By default we isolate on:
+        - org_id (tenant)
+        - user_id (actor within tenant)
+        - scope_id (memory bucket, usually memory_scope_id)
         """
         out: dict[str, Any] = {}
         if self.user_id:
             out["user_id"] = self.user_id
         if self.org_id:
             out["org_id"] = self.org_id
+        # scope_id is usually memory_scope_id() (e.g. session:, user:, run:, org:, app:)
         if scope_id:
             out["scope_id"] = scope_id
-        # you can choose to include session_id / run_id only for very strict isolation
         return out

aethergraph/services/scope/scope_factory.py

@@ -63,12 +63,19 @@ class ScopeFactory:
         session_id: str | None = None,
         flow_id: str | None = None,
     ) -> Scope:
-        s = self.base_from_identity(identity)
-        s.run_id = run_id
-        s.graph_id = graph_id
-        s.session_id = session_id
-        s.flow_id = flow_id
-        return s
+        base = self.base_from_identity(identity)
+        return Scope(
+            org_id=base.org_id,
+            user_id=base.user_id,
+            client_id=base.client_id,
+            mode=base.mode,
+            app_id=base.app_id,
+            session_id=session_id,
+            run_id=run_id,
+            graph_id=graph_id,
+            node_id=None,
+            flow_id=flow_id,
+        )
 
     def for_memory_custom_override(
         self,
@@ -148,8 +155,9 @@ class ScopeFactory:
             base = session_id or run_id
             root = f"session:{base}"
         elif level == "user":
+            o = s.org_id or "orgless"
             u = s.user_id or s.client_id or "anon"
-            root = f"user:{u}"
+            root = f"org:{o}:user:{u}"
         elif level == "run":
             root = f"run:{run_id}"
         elif level == "org":