agentic-notify 0.1.0__tar.gz

agentic_notify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil Kanamadi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_notify-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: agentic-notify
+Version: 0.1.0
+Summary: A Python library for building agentic, notification-driven workflows with pluggable adapters, policy-aware handlers, and scalable integration interfaces.
+License-File: LICENSE
+Author: Your Name
+Author-email: you@example.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: fastapi
+Provides-Extra: mcp
+Provides-Extra: observability
+Provides-Extra: redis
+Requires-Dist: pydantic (>=2.0.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# agentic-notify
+
+A Python library for building **agentic, notification-driven workflows** with pluggable adapters, policy-aware handlers, and scalable integration interfaces for cross-native applications.
+
+## Overview
+
+`agentic-notify` gives you a **backend-first orchestration SDK** with clear extension points:
+
+- **Ingestion & Normalization:** Accept notifications from Android/React Native bridges and convert them to a canonical schema.
+- **Agentic Routing:** Send notifications to workflows based on LLM decisions or rules.
+- **Workflow Orchestration:** Execute steps safely, handle retries, and check execution policies.
+- **Adapters:** Connect your workflow engine to device boundaries (Reminders, Summaries, Local DBs).
+
+## Architecture Approach
+
+- **Schemas define contracts** (via Pydantic)
+- **Normalizers unify platforms**
+- **Routers decide**
+- **Workflows orchestrate**
+- **Handlers transform**
+- **Adapters act**
+- **Integrations connect**
+- **Policies constrain**
+
+## Installation
+
+```bash
+# Core package
+pip install agentic-notify
+
+# Install with FastAPI and Redis support
+pip install agentic-notify[fastapi,redis]
+```
+

agentic_notify-0.1.0/README.md

@@ -0,0 +1,33 @@
+# agentic-notify
+
+A Python library for building **agentic, notification-driven workflows** with pluggable adapters, policy-aware handlers, and scalable integration interfaces for cross-native applications.
+
+## Overview
+
+`agentic-notify` gives you a **backend-first orchestration SDK** with clear extension points:
+
+- **Ingestion & Normalization:** Accept notifications from Android/React Native bridges and convert them to a canonical schema.
+- **Agentic Routing:** Send notifications to workflows based on LLM decisions or rules.
+- **Workflow Orchestration:** Execute steps safely, handle retries, and check execution policies.
+- **Adapters:** Connect your workflow engine to device boundaries (Reminders, Summaries, Local DBs).
+
+## Architecture Approach
+
+- **Schemas define contracts** (via Pydantic)
+- **Normalizers unify platforms**
+- **Routers decide**
+- **Workflows orchestrate**
+- **Handlers transform**
+- **Adapters act**
+- **Integrations connect**
+- **Policies constrain**
+
+## Installation
+
+```bash
+# Core package
+pip install agentic-notify
+
+# Install with FastAPI and Redis support
+pip install agentic-notify[fastapi,redis]
+```

agentic_notify-0.1.0/agentic_notify/__init__.py

@@ -0,0 +1,4 @@
+"""
+agentic_notify - A Python library for building agentic, notification-driven workflows
+"""
+__version__ = "0.1.0"

agentic_notify-0.1.0/agentic_notify/adapters/__init__.py

@@ -0,0 +1,3 @@
+from agentic_notify.adapters.base import BaseAdapter
+
+__all__ = ["BaseAdapter"]

agentic_notify-0.1.0/agentic_notify/adapters/base.py

@@ -0,0 +1,23 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+class BaseAdapter(ABC):
+    """
+    An Adapter is responsible for performing a downstream action (e.g., calling an API, 
+    saving to DB, triggering device native modules).
+    This is entirely decoupled from the inbound integrations.
+    """
+    
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The canonical name of the adapter used in workflow definitions."""
+        pass
+
+    @abstractmethod
+    async def execute(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute the business action with the provided payload.
+        Returns the output dict of the execution.
+        """
+        pass

agentic_notify-0.1.0/agentic_notify/adapters/mcp.py

@@ -0,0 +1,36 @@
+from typing import Dict, Any
+import logging
+from agentic_notify.adapters.base import BaseAdapter
+
+logger = logging.getLogger(__name__)
+
+class MCPClientAdapter(BaseAdapter):
+    """
+    Provides a standardized boundary to call out to an external Model Context Protocol (MCP) server.
+    Instead of hardcoding APIs, the workflow can trigger exposed MCP tools.
+    """
+    @property
+    def name(self) -> str:
+        return "call_mcp_tool"
+
+    async def execute(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        server_name = payload.get("server_name")
+        tool_name = payload.get("tool_name")
+        tool_args = payload.get("tool_args", {})
+        
+        if not server_name or not tool_name:
+            raise ValueError("MCPClientAdapter requires 'server_name' and 'tool_name'")
+            
+        logger.info(f"MCP Action: Delegating to server '{server_name}' to run tool '{tool_name}' with args {tool_args}")
+        
+        # Placeholder for actual MCP SDK invocation:
+        # e.g., result = await mcp_client_sessions[server_name].call_tool(tool_name, tool_args)
+        
+        mock_result_payload = {"tool_status": "executed", "echo": tool_args}
+        
+        return {
+            "status": "success",
+            "server_id": server_name,
+            "tool_id": tool_name,
+            "mcp_result": mock_result_payload
+        }

agentic_notify-0.1.0/agentic_notify/adapters/mock_reminder.py

@@ -0,0 +1,17 @@
+from typing import Dict, Any
+import logging
+from agentic_notify.adapters.base import BaseAdapter
+
+logger = logging.getLogger(__name__)
+
+class MockReminderAdapter(BaseAdapter):
+    """
+    A mock adapter to simulate creating a reminder on a user's device.
+    """
+    @property
+    def name(self) -> str:
+        return "create_reminder"
+
+    async def execute(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        logger.info(f"*** Action Executed: MockReminderAdapter received {payload} ***")
+        return {"status": "success", "reminder_id": "rem_test_001", "echo_payload": payload}

agentic_notify-0.1.0/agentic_notify/adapters/notes.py

@@ -0,0 +1,25 @@
+from typing import Dict, Any
+import logging
+from agentic_notify.adapters.base import BaseAdapter
+
+logger = logging.getLogger(__name__)
+
+class NotesAdapter(BaseAdapter):
+    """
+    Simulates saving content to a local notes app or document store.
+    """
+    @property
+    def name(self) -> str:
+        return "save_note"
+
+    async def execute(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        title = payload.get("title", "Untitled Note")
+        content = payload.get("content", "")
+        
+        logger.info(f"Action Executed: Saved Note => Title: '{title}', Content Length: {len(content)}")
+        
+        return {
+            "status": "success",
+            "note_id": "note_1001",
+            "saved_title": title
+        }

agentic_notify-0.1.0/agentic_notify/adapters/webhook.py

@@ -0,0 +1,44 @@
+from typing import Dict, Any
+import logging
+import json
+import urllib.request
+import urllib.error
+from agentic_notify.adapters.base import BaseAdapter
+
+logger = logging.getLogger(__name__)
+
+class WebhookAdapter(BaseAdapter):
+    """
+    Adapter that fires an HTTP POST to an external webhook URL.
+    """
+    @property
+    def name(self) -> str:
+        return "trigger_webhook"
+
+    async def execute(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        url = payload.get("url")
+        data = payload.get("data", {})
+        
+        if not url:
+            raise ValueError("WebhookAdapter requires a 'url' in the payload.")
+            
+        logger.info(f"Action Executed: Firing Webhook to {url}")
+        
+        req = urllib.request.Request(
+            url, 
+            data=json.dumps(data).encode('utf-8'),
+            headers={'Content-Type': 'application/json'},
+            method='POST'
+        )
+        
+        try:
+            # Note: Minimal blocking sync call for demonstration.
+            # In production asyncio, use aiohttp or httpx.
+            with urllib.request.urlopen(req, timeout=10) as response:
+                return {
+                    "status": "success",
+                    "http_code": response.getcode()
+                }
+        except urllib.error.URLError as e:
+            logger.error(f"Webhook failed: {e}")
+            raise RuntimeError(f"Webhook call failed: {e}")

agentic_notify-0.1.0/agentic_notify/examples/__init__.py

@@ -0,0 +1 @@
+"""Examples directory"""

agentic_notify-0.1.0/agentic_notify/examples/app.py

@@ -0,0 +1,49 @@
+import logging
+from fastapi import FastAPI
+
+from agentic_notify.orchestrator import NotificationOrchestrator
+from agentic_notify.storage.memory import InMemoryStore
+from agentic_notify.integrations.fastapi_integration import FastAPIIntegration
+from agentic_notify.adapters.mock_reminder import MockReminderAdapter
+from agentic_notify.schemas.workflow import WorkflowDefinition, WorkflowTrigger, WorkflowStep
+
+logging.basicConfig(level=logging.INFO)
+
+# 1. Setup Core dependencies
+storage = InMemoryStore()
+
+# 2. Setup Orchestrator
+orchestrator = NotificationOrchestrator(storage=storage)
+
+# 3. Register our mock adapter
+orchestrator.register_adapter(MockReminderAdapter())
+
+# 4. Define and Register Workflow
+workflow = WorkflowDefinition(
+    workflow_id="wf_important_reminders",
+    workflow_name="Important Notification Reminders",
+    trigger=WorkflowTrigger(type="notification"),
+    steps=[
+        WorkflowStep(
+            id="step_create_reminder",
+            kind="adapter",
+            name="create_reminder",
+            # We map the inputs using standard dot notation to pull from the normalized event
+            input_from={
+                "task_text": "event.body", 
+                "task_title": "event.title"
+            }
+        )
+    ]
+)
+orchestrator.register_workflow(workflow)
+
+# 5. Add deterministic routing rule (Route all events to our test workflow)
+orchestrator.router.add_rule(lambda e: True, "wf_important_reminders")
+
+# 6. Initialize FastAPI Integration
+app = FastAPI()
+integration = FastAPIIntegration(orchestrator, app)
+
+# To run this example locally:
+# python -m uvicorn agentic_notify.examples.app:app --reload

agentic_notify-0.1.0/agentic_notify/handlers/__init__.py

@@ -0,0 +1,3 @@
+from agentic_notify.handlers.base import BaseHandler
+
+__all__ = ["BaseHandler"]

agentic_notify-0.1.0/agentic_notify/handlers/approval.py

@@ -0,0 +1,32 @@
+from typing import Dict, Any, List
+import logging
+from agentic_notify.handlers.base import BaseHandler
+from agentic_notify.schemas.notification import NotificationEvent
+
+logger = logging.getLogger(__name__)
+
+class ApprovalHandler(BaseHandler):
+    """
+    Human-in-the-Loop Handler. 
+    When a workflow executes this step, it halts execution and returns 'awaiting_approval'.
+    The orchestrator pauses the run state until a human explicitly resumes it.
+    """
+    @property
+    def name(self) -> str:
+        return "request_human_approval"
+
+    async def handle(self, event: NotificationEvent, context: Dict[str, Any]) -> Dict[str, Any]:
+        reason = context.get("reason", "Action requires explicit user approval.")
+        action_payload = context.get("action_payload", {})
+        
+        logger.info(f"⏸️ WORKFLOW HALTED: Requesting Human Approval for: {reason}")
+        
+        # In a real system, you would trigger an outbound push notification or email here
+        # telling the user to click an "Approve" button.
+        
+        return {
+            "status": "awaiting_approval",
+            "approval_ticket_id": f"ticket_{event.event_id}",
+            "reason": reason,
+            "pending_action": action_payload
+        }

agentic_notify-0.1.0/agentic_notify/handlers/base.py

@@ -0,0 +1,25 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+from agentic_notify.schemas.notification import NotificationEvent
+
+class BaseHandler(ABC):
+    """
+    A Handler is responsible for processing a step logic in memory.
+    It does not necessarily perform a permanent external action (like an Adapter),
+    but typically manipulates, routes, or transforms data (e.g., classification, summarization).
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The canonical name of the handler used in workflow definitions."""
+        pass
+
+    @abstractmethod
+    async def handle(self, event: NotificationEvent, context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process the notification event and context.
+        Returns the mutated context or result of the handling.
+        """
+        pass

agentic_notify-0.1.0/agentic_notify/integrations/__init__.py

@@ -0,0 +1,3 @@
+from agentic_notify.integrations.base import BaseIntegration
+
+__all__ = ["BaseIntegration"]

agentic_notify-0.1.0/agentic_notify/integrations/base.py

@@ -0,0 +1,19 @@
+from typing import Any, Dict
+from abc import ABC, abstractmethod
+from agentic_notify.schemas.notification import NotificationEvent
+
+class BaseIntegration(ABC):
+    """
+    An Integration receives raw events from an external host system
+    (e.g., FastAPI route, background worker, Webhook, RN Bridge).
+    """
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start the integration listener or service."""
+        pass
+
+    @abstractmethod
+    def stop(self) -> None:
+        """Stop the integration."""
+        pass

agentic_notify-0.1.0/agentic_notify/integrations/fastapi_integration.py

@@ -0,0 +1,30 @@
+from fastapi import FastAPI, Request
+from typing import Any, Dict
+from agentic_notify.integrations.base import BaseIntegration
+import logging
+
+logger = logging.getLogger(__name__)
+
+class FastAPIIntegration(BaseIntegration):
+    """
+    Exposes a REST API endpoint for ingesting notification events.
+    Requires FastAPI to be installed and passed in.
+    """
+    def __init__(self, orchestrator, app: FastAPI):
+        self.orchestrator = orchestrator
+        self.app = app
+        self._register_routes()
+
+    def _register_routes(self):
+        @self.app.post("/events/ingest")
+        async def ingest_event(request: Request):
+            payload = await request.json()
+            logger.info("FastAPI received event payload")
+            result = await self.orchestrator.process_event(payload)
+            return result
+
+    async def start(self) -> None:
+        logger.info("FastAPIIntegration started (managed by external uvicorn/asgi)")
+
+    def stop(self) -> None:
+        pass

agentic_notify-0.1.0/agentic_notify/integrations/queue.py

@@ -0,0 +1,29 @@
+from typing import Any, Dict
+from agentic_notify.integrations.base import BaseIntegration
+import logging
+import asyncio
+
+logger = logging.getLogger(__name__)
+
+class RedisQueueIntegration(BaseIntegration):
+    """
+    Listens to a Redis List/PubSub queue to ingest events continuously.
+    (Stubbed for async ingestion demonstration)
+    """
+    def __init__(self, orchestrator, queue_name: str = "agentic_events"):
+        self.orchestrator = orchestrator
+        self.queue_name = queue_name
+        self._running = False
+
+    async def start(self) -> None:
+        self._running = True
+        logger.info(f"Started RedisQueueIntegration listening on '{self.queue_name}'")
+        
+        # Simulated async polling loop
+        # while self._running:
+        #    raw_event = await redis_client.blpop(self.queue_name)
+        #    asyncio.create_task(self.orchestrator.process_event(raw_event))
+
+    def stop(self) -> None:
+        logger.info(f"Stopping RedisQueueIntegration '{self.queue_name}'")
+        self._running = False

agentic_notify-0.1.0/agentic_notify/observability/__init__.py

@@ -0,0 +1,3 @@
+from agentic_notify.observability.logger import setup_json_logger, trace_span
+
+__all__ = ["setup_json_logger", "trace_span"]

agentic_notify-0.1.0/agentic_notify/observability/logger.py

@@ -0,0 +1,45 @@
+import logging
+import json
+from contextlib import contextmanager
+from datetime import datetime
+import time
+from typing import Dict, Any, Optional
+
+def setup_json_logger(name: str) -> logging.Logger:
+    """Provides a basic structured logger."""
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.INFO)
+    
+    # Simple JSON formatter
+    class JsonFormatter(logging.Formatter):
+        def format(self, record: logging.LogRecord) -> str:
+            log_record = {
+                "timestamp": datetime.utcnow().isoformat(),
+                "level": record.levelname,
+                "name": record.name,
+                "message": record.getMessage()
+            }
+            if hasattr(record, "trace_id"):
+                log_record["trace_id"] = record.trace_id # type: ignore
+            return json.dumps(log_record)
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(JsonFormatter())
+    
+    # Avoid duplicate handlers if setup multiple times
+    if not logger.handlers:
+        logger.addHandler(handler)
+        
+    return logger
+
+@contextmanager
+def trace_span(logger: logging.Logger, span_name: str, trace_id: Optional[str] = None):
+    """
+    Context manager to trace execution duration of a step.
+    Produces structured start/end logs.
+    """
+    start_time = time.time()
+    logger.info(f"SPAN_START: {span_name}", extra={"trace_id": trace_id} if trace_id else {})
+    yield
+    latency_ms = int((time.time() - start_time) * 1000)
+    logger.info(f"SPAN_END: {span_name} ({latency_ms}ms)", extra={"trace_id": trace_id} if trace_id else {})

agentic_notify-0.1.0/agentic_notify/orchestrator.py

@@ -0,0 +1,96 @@
+import uuid
+import logging
+from typing import Any, Dict, Optional
+
+from agentic_notify.adapters.base import BaseAdapter
+from agentic_notify.handlers.base import BaseHandler
+from agentic_notify.schemas.notification import NotificationEvent
+from agentic_notify.schemas.workflow import WorkflowDefinition
+from agentic_notify.schemas.result import WorkflowRunResult
+from agentic_notify.storage.base import BaseStorage
+from agentic_notify.routing.engine import RoutingEngine
+from agentic_notify.workflows.engine import WorkflowExecutor
+from agentic_notify.policies.engine import PolicyEngine
+
+logger = logging.getLogger(__name__)
+
+class NotificationOrchestrator:
+    """
+    The main coordinator. Receives events, routes them to workflows, 
+    evaluates policies, and delegates execution.
+    """
+    def __init__(
+        self,
+        storage: BaseStorage,
+        router: Optional[RoutingEngine] = None,
+        policy_engine: Optional[PolicyEngine] = None,
+        executor: Optional[WorkflowExecutor] = None,
+    ):
+        self.storage = storage
+        self.router = router or RoutingEngine()
+        self.policy_engine = policy_engine or PolicyEngine()
+        self.executor = executor or WorkflowExecutor(storage=self.storage)
+        
+        self.adapters: Dict[str, BaseAdapter] = {}
+        self.handlers: Dict[str, BaseHandler] = {}
+        self.workflows: Dict[str, WorkflowDefinition] = {}
+
+    def register_adapter(self, adapter: BaseAdapter) -> None:
+        self.adapters[adapter.name] = adapter
+        logger.info(f"Registered adapter: {adapter.name}")
+
+    def register_handler(self, handler: BaseHandler) -> None:
+        self.handlers[handler.name] = handler
+        logger.info(f"Registered handler: {handler.name}")
+
+    def register_workflow(self, workflow: WorkflowDefinition) -> None:
+        self.workflows[workflow.workflow_id] = workflow
+        logger.info(f"Registered workflow: {workflow.workflow_id} ({workflow.workflow_name})")
+
+    async def process_event(self, raw_event_payload: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        1. Normalize raw event
+        2. Route
+        3. Execute workflow steps sequentially
+        """
+        # 1. Normalize
+        try:
+            event = NotificationEvent(**raw_event_payload)
+        except Exception as e:
+            logger.error(f"Event normalization failed: {e}")
+            return {"status": "error", "message": "Invalid event schema.", "details": str(e)}
+            
+        logger.info(f"Normalized event: {event.event_id}")
+
+        # 2. Route
+        workflow_id = self.router.route(event)
+        if not workflow_id or workflow_id not in self.workflows:
+            msg = f"No workflow matched or found for event {event.event_id}"
+            logger.info(msg)
+            return {"status": "ignored", "message": msg}
+            
+        workflow = self.workflows[workflow_id]
+        
+        # 3. Policy Execution Check
+        if not self.policy_engine.evaluate("start_workflow", {"workflow_id": workflow_id}, {"event": event.model_dump()}):
+            logger.warning(f"Policy denied workflow {workflow_id}")
+            return {"status": "denied", "message": "Policy check failed."}
+
+        # 4. Execute
+        run_id = f"run_{uuid.uuid4().hex}"
+        logger.info(f"Delegating execution for {workflow_id} as run {run_id}")
+        
+        result: WorkflowRunResult = await self.executor.execute(
+            run_id=run_id,
+            workflow=workflow,
+            event=event,
+            adapters=self.adapters,
+            handlers=self.handlers
+        )
+        
+        return {
+            "status": "processed", 
+            "run_id": run_id, 
+            "workflow_id": workflow_id,
+            "run_status": result.status
+        }

agentic_notify-0.1.0/agentic_notify/planning/__init__.py

@@ -0,0 +1 @@
+"""Planning module"""

agentic_notify-0.1.0/agentic_notify/planning/openai_client.py

@@ -0,0 +1,49 @@
+import json
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+class OpenAIPlannerClient:
+    """
+    A concrete client wrapper for OpenAI's API to be used by the AgenticPlanner.
+    Requires `openai` package to be installed.
+    """
+    def __init__(self, api_key: str, model: str = "gpt-4o"):
+        try:
+            from openai import AsyncOpenAI
+            self.client = AsyncOpenAI(api_key=api_key)
+            self.model = model
+            logger.info(f"Initialized OpenAIPlannerClient with model: {self.model}")
+        except ImportError:
+            raise ImportError("Please install openai package: `pip install openai`")
+
+    async def chat(self, system_prompt: str, user_intent: str) -> Dict[str, Any]:
+        """
+        Sends the prompt to OpenAI and expects a JSON response constrained to the 
+        WorkflowDefinition schema.
+        """
+        logger.info("Calling OpenAI API for workflow generation...")
+        
+        try:
+            # Using response_format={ "type": "json_object" } perfectly aligns with 
+            # our Pydantic validation boundary.
+            response = await self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_intent}
+                ],
+                response_format={"type": "json_object"},
+                temperature=0.2, # Low temperature for deterministic planning
+            )
+            
+            content = response.choices[0].message.content
+            if not content:
+                raise ValueError("OpenAI returned an empty response.")
+                
+            return json.loads(content)
+            
+        except Exception as e:
+            logger.error(f"OpenAI API call failed: {e}")
+            raise

agentic_notify-0.1.0/agentic_notify/planning/planner.py

@@ -0,0 +1,63 @@
+import json
+import uuid
+import logging
+from typing import Dict, Any, Optional
+
+from agentic_notify.schemas.workflow import WorkflowDefinition, WorkflowStep
+from agentic_notify.tools.registry import ToolRegistry
+from agentic_notify.planning.prompts import SYSTEM_PLANNER_PROMPT
+
+logger = logging.getLogger(__name__)
+
+class AgenticPlanner:
+    """
+    Converts natural language user intents into structured WorkflowDefinition schemas.
+    """
+    def __init__(self, tool_registry: ToolRegistry, llm_client: Optional[Any] = None):
+        self.tool_registry = tool_registry
+        self.llm_client = llm_client
+
+    async def plan_workflow(self, intent: str, trigger_type: str = "notification") -> WorkflowDefinition:
+        """
+        Executes a prompt to an LLM to generate the JSON graph, then strictly validates it 
+        through the Pydantic definition.
+        """
+        tools = json.dumps(self.tool_registry.get_all_tool_schemas(), indent=2)
+        system_prompt = SYSTEM_PLANNER_PROMPT.format(tools=tools)
+        
+        logger.info(f"Generating plan for intent: '{intent}' utilizing registered tools.")
+        
+        # Real-world behavior: Wait for LLM
+        # response_text = await self.llm_client.chat(messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": intent}])
+        
+        # Mocked deterministic response for Phase 4 proof-of-concept
+        mock_generated_plan = {
+            "workflow_id": f"wf_llm_{uuid.uuid4().hex[:8]}",
+            "workflow_name": "Generated LLM Plan",
+            "description": f"Automated workflow for: {intent}",
+            "enabled": True,
+            "trigger": {
+                "type": trigger_type
+            },
+            "steps": [
+                {
+                    "id": "step_create_reminder",
+                    "kind": "adapter",
+                    "name": "create_reminder",
+                    "input_from": {
+                        "task_text": "event.body",
+                        "task_title": "event.title"
+                    }
+                }
+            ]
+        }
+        
+        try:
+            # The most crucial step of the backend design: 
+            # Force the untrusted LLM payload through the strict Pydantic `WorkflowDefinition` validator.
+            workflow = WorkflowDefinition(**mock_generated_plan)
+            logger.info(f"Successfully validated LLM plan into WorkflowDefinition: {workflow.workflow_id}")
+            return workflow
+        except Exception as e:
+            logger.error(f"LLM produced invalid workflow schema! Planning failed: {e}")
+            raise ValueError(f"Planner failed schema validation: {e}")

agentic_notify-0.1.0/agentic_notify/planning/prompts.py

@@ -0,0 +1,15 @@
+# Base System Prompts for Agentic Planning
+
+SYSTEM_PLANNER_PROMPT = """
+You are the Agentic Workflow Planner for a mobile companion app.
+Your job is to read user intents and convert them into deterministic JSON workflow graphs.
+
+RULES:
+1. Output MUST be perfectly valid JSON with NO markdown formatting.
+2. The JSON must align with the WorkflowDefinition Pydantic Schema.
+3. You may ONLY use 'steps' that rely on the tools listed below.
+4. Try to construct steps that chain outputs (e.g. input_from: {{ "text": "prev_step_id.content" }}) if multiple steps are needed.
+
+AVAILABLE TOOLS (Adapter schemas):
+{tools}
+"""

agentic_notify-0.1.0/agentic_notify/policies/__init__.py

@@ -0,0 +1,3 @@
+from agentic_notify.policies.engine import PolicyEngine
+
+__all__ = ["PolicyEngine"]

agentic_notify-0.1.0/agentic_notify/policies/engine.py

@@ -0,0 +1,35 @@
+from typing import Dict, Any, List
+import logging
+
+logger = logging.getLogger(__name__)
+
+class PolicyEngine:
+    """
+    Dynamically evaluates risk and permissions by checking user-configured boundaries
+    before an action or workflow is allowed to fire.
+    """
+    def __init__(self):
+        # In production, this would query a DB or a Vector Redis cache per user.
+        self.user_restrictions: Dict[str, List[str]] = {
+            "default_user": ["never_auto_delete", "never_silence_bank"],
+            "vip_mode": ["disable_all_summarization"]
+        }
+
+    def evaluate(self, action: str, payload: Dict[str, Any], context: Dict[str, Any]) -> bool:
+        """
+        Check if an action is allowed based on user restrictions and global rules.
+        """
+        user_id = context.get("event", {}).get("metadata", {}).get("user_id", "default_user")
+        restrictions = self.user_restrictions.get(user_id, [])
+
+        logger.info(f"Evaluating Policy: action '{action}' for user '{user_id}'")
+
+        if action == "summarize" and "disable_all_summarization" in restrictions:
+            logger.warning(f"POLICY BLOCK: User {user_id} has disabled AI summarization.")
+            return False
+            
+        if action == "delete_email" and "never_auto_delete" in restrictions:
+            logger.warning(f"POLICY BLOCK: User {user_id} has forbidden auto-deletion.")
+            return False
+
+        return True

agentic_notify-0.1.0/agentic_notify/routing/__init__.py

@@ -0,0 +1,3 @@
+from agentic_notify.routing.engine import RoutingEngine
+
+__all__ = ["RoutingEngine"]

agentic_notify-0.1.0/agentic_notify/routing/engine.py

@@ -0,0 +1,21 @@
+from typing import Dict, Any, Optional, Callable, Tuple, List
+from agentic_notify.schemas.notification import NotificationEvent
+
+class RoutingEngine:
+    """
+    Determines which workflow to trigger based on the incoming NotificationEvent.
+    """
+    def __init__(self):
+        # List of (rule_function, workflow_id)
+        self.rules: List[Tuple[Callable[[NotificationEvent], bool], str]] = []
+
+    def add_rule(self, rule_fn: Callable[[NotificationEvent], bool], workflow_id: str):
+        """Add a simple deterministic rule."""
+        self.rules.append((rule_fn, workflow_id))
+
+    def route(self, event: NotificationEvent) -> Optional[str]:
+        """Returns the matched workflow_id, or None if no match."""
+        for rule_fn, workflow_id in self.rules:
+            if rule_fn(event):
+                return workflow_id
+        return None

agentic_notify-0.1.0/agentic_notify/schemas/__init__.py

@@ -0,0 +1,12 @@
+from agentic_notify.schemas.notification import NotificationEvent
+from agentic_notify.schemas.workflow import WorkflowDefinition, WorkflowStep, WorkflowTrigger
+from agentic_notify.schemas.result import StepResult, WorkflowRunResult
+
+__all__ = [
+    "NotificationEvent",
+    "WorkflowDefinition",
+    "WorkflowStep", 
+    "WorkflowTrigger",
+    "StepResult",
+    "WorkflowRunResult"
+]

agentic_notify-0.1.0/agentic_notify/schemas/notification.py

@@ -0,0 +1,18 @@
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+class NotificationEvent(BaseModel):
+    """
+    The canonical schema for an incoming platform event (e.g., from Android/iOS/Web).
+    All integrations must parse their raw events into this format.
+    """
+    event_id: str
+    kind: str = "notification"
+    source_platform: str
+    source_app: str
+    title: Optional[str] = None
+    body: Optional[str] = None
+    received_at: datetime = Field(default_factory=datetime.utcnow)
+    priority_hint: str = "unknown"
+    metadata: Dict[str, Any] = Field(default_factory=dict)

agentic_notify-0.1.0/agentic_notify/schemas/result.py

@@ -0,0 +1,18 @@
+from pydantic import BaseModel
+from typing import Any, Dict, Optional
+
+class StepResult(BaseModel):
+    """Result of a single workflow step execution."""
+    status: str  # "success", "failed", "awaiting_approval"
+    output: Optional[Dict[str, Any]] = None
+    error: Optional[Dict[str, Any]] = None
+    started_at: str
+    ended_at: str
+    latency_ms: int
+
+class WorkflowRunResult(BaseModel):
+    """Result of an entire workflow execution."""
+    run_id: str
+    workflow_id: str
+    status: str
+    step_results: Dict[str, StepResult]

agentic_notify-0.1.0/agentic_notify/schemas/workflow.py

@@ -0,0 +1,36 @@
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel, ConfigDict
+
+class WorkflowStep(BaseModel):
+    """
+    A single step in the workflow graph.
+    Can either trigger an internal handler or call an external tool adapter.
+    """
+    id: str
+    kind: str  # typically "tool" or "handler"
+    name: str  # e.g., "summarize_text", "create_reminder"
+    depends_on: List[str] = []
+    input_from: Dict[str, Any] = {}
+    timeout_ms: int = 15000
+    retry_limit: int = 2
+
+class WorkflowTrigger(BaseModel):
+    """
+    Conditions describing how a workflow should be triggered.
+    """
+    type: str  # e.g., "schedule", "notification", "event"
+    schedule: Optional[str] = None
+    event_pattern: Optional[Dict[str, Any]] = None
+
+class WorkflowDefinition(BaseModel):
+    """
+    A deterministic, structured execution graph for an agentic workflow.
+    """
+    model_config = ConfigDict(extra="allow")
+    
+    workflow_id: str
+    workflow_name: str
+    description: Optional[str] = None
+    enabled: bool = True
+    trigger: WorkflowTrigger
+    steps: List[WorkflowStep]

agentic_notify-0.1.0/agentic_notify/storage/__init__.py

@@ -0,0 +1,4 @@
+from agentic_notify.storage.base import BaseStorage
+from agentic_notify.storage.memory import InMemoryStore
+
+__all__ = ["BaseStorage", "InMemoryStore"]

agentic_notify-0.1.0/agentic_notify/storage/base.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+class BaseStorage(ABC):
+    """
+    Storage layer abstraction for runs, step cache, audit trails, and configurations.
+    """
+    
+    @abstractmethod
+    async def save_workflow_run(self, run_id: str, run_data: Dict[str, Any]) -> None:
+        pass
+
+    @abstractmethod
+    async def get_workflow_run(self, run_id: str) -> Optional[Dict[str, Any]]:
+        pass
+        
+    @abstractmethod
+    async def log_audit_event(self, event_type: str, data: Dict[str, Any]) -> None:
+        pass

agentic_notify-0.1.0/agentic_notify/storage/memory.py

@@ -0,0 +1,19 @@
+from typing import Any, Dict, List, Optional
+from agentic_notify.storage.base import BaseStorage
+
+class InMemoryStore(BaseStorage):
+    """
+    A simple dictionary-backed storage for rapid prototyping and testing.
+    """
+    def __init__(self):
+        self.runs: Dict[str, Dict[str, Any]] = {}
+        self.audits: List[Dict[str, Any]] = []
+
+    async def save_workflow_run(self, run_id: str, run_data: Dict[str, Any]) -> None:
+        self.runs[run_id] = run_data
+
+    async def get_workflow_run(self, run_id: str) -> Optional[Dict[str, Any]]:
+        return self.runs.get(run_id)
+
+    async def log_audit_event(self, event_type: str, data: Dict[str, Any]) -> None:
+        self.audits.append({"event_type": event_type, "data": data})

agentic_notify-0.1.0/agentic_notify/storage/postgres.py

@@ -0,0 +1,36 @@
+from typing import Dict, Any, List
+import logging
+from agentic_notify.storage.base import BaseStorage
+
+logger = logging.getLogger(__name__)
+
+class PostgresStore(BaseStorage):
+    """
+    Durable database storage for production multi-tenancy.
+    Requires asyncpg or equivalent async SQL driver.
+    """
+    def __init__(self, connection_pool: Any):
+        # connection_pool would be an asyncpg pool in production
+        self.pool = connection_pool
+        logger.info("Initialized PostgresStore for durable partitioned execution tracking.")
+
+    async def save_workflow_run(self, run_id: str, run_data: Dict[str, Any]) -> None:
+        """Upserts a workflow run into the runs table."""
+        # async with self.pool.acquire() as conn:
+        #     await conn.execute(
+        #         "INSERT INTO workflow_runs (run_id, data) VALUES ($1, $2) ON CONFLICT (run_id) DO UPDATE SET data = $2",
+        #         run_id, json.dumps(run_data)
+        #     )
+        logger.info(f"DS_WRITE: Saved Run {run_id} to Stateful Postgres Database.")
+        pass
+
+    async def get_workflow_run(self, run_id: str) -> Dict[str, Any]:
+        # async with self.pool.acquire() as conn:
+        #     record = await conn.fetchrow("SELECT data FROM workflow_runs WHERE run_id = $1", run_id)
+        #     return json.loads(record['data']) if record else None
+        return {}
+        
+    async def log_audit_event(self, event_type: str, data: Dict[str, Any]) -> None:
+        # async with self.pool.acquire() as conn:
+        #     await conn.execute("INSERT INTO audit_logs (type, payload) VALUES ($1, $2)", event_type, json.dumps(data))
+        pass

agentic_notify-0.1.0/agentic_notify/tools/__init__.py

@@ -0,0 +1 @@
+"""Tools registry module"""

agentic_notify-0.1.0/agentic_notify/tools/registry.py

@@ -0,0 +1,24 @@
+from typing import Dict, Any, List
+from pydantic import BaseModel
+
+class ToolSchema(BaseModel):
+    """
+    Metadata representation of an Adapter or Handler.
+    This is what the LLM planner sees to know what actions it can take.
+    """
+    name: str
+    description: str
+    input_schema: Dict[str, Any]
+    idempotent: bool
+    sensitivity: str = "low"
+
+class ToolRegistry:
+    """Holds metadata for all registered actions globally."""
+    def __init__(self):
+        self._tools: Dict[str, ToolSchema] = {}
+
+    def register_tool(self, schema: ToolSchema):
+        self._tools[schema.name] = schema
+
+    def get_all_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [t.model_dump() for t in self._tools.values()]

agentic_notify-0.1.0/agentic_notify/workflows/__init__.py

@@ -0,0 +1,3 @@
+from agentic_notify.workflows.engine import WorkflowExecutor
+
+__all__ = ["WorkflowExecutor"]

agentic_notify-0.1.0/agentic_notify/workflows/engine.py

@@ -0,0 +1,128 @@
+import logging
+from typing import Dict, Any
+from datetime import datetime
+import time
+
+from agentic_notify.schemas.notification import NotificationEvent
+from agentic_notify.schemas.workflow import WorkflowDefinition
+from agentic_notify.schemas.result import WorkflowRunResult, StepResult
+from agentic_notify.adapters.base import BaseAdapter
+from agentic_notify.handlers.base import BaseHandler
+from agentic_notify.storage.base import BaseStorage
+
+logger = logging.getLogger(__name__)
+
+class WorkflowExecutor:
+    """
+    Iterates over workflow steps and invokes the appropriate handler or adapter,
+    capable of suspending state for Human-in-the-Loop approvals.
+    """
+    def __init__(self, storage: BaseStorage):
+        self.storage = storage
+
+    async def execute(
+        self,
+        run_id: str,
+        workflow: WorkflowDefinition,
+        event: NotificationEvent,
+        adapters: Dict[str, BaseAdapter],
+        handlers: Dict[str, BaseHandler],
+        resume_from_step: str = None
+    ) -> WorkflowRunResult:
+        
+        logger.info(f"Starting/Resuming run {run_id} for workflow {workflow.workflow_id}")
+        # In a real durable engine, we would fetch existing step_results from DB here if resuming.
+        step_results: Dict[str, StepResult] = {}
+        context = {"event": event.model_dump(), "steps": {}}
+
+        run_status = "success"
+
+        for step in workflow.steps:
+            # Skip steps already executed if we are resuming from an approval
+            if resume_from_step and step.id != resume_from_step:
+                continue
+            elif resume_from_step and step.id == resume_from_step:
+                resume_from_step = None # We caught up
+
+            start_time = time.time()
+            started_at = datetime.utcnow().isoformat()
+            
+            try:
+                # Resolve inputs mapping
+                step_input = {}
+                for in_key, in_val in step.input_from.items():
+                    if isinstance(in_val, str) and "." in in_val:
+                        parts = in_val.split(".", 1)
+                        if parts[0] in context["steps"]:
+                            step_input[in_key] = context["steps"][parts[0]].get(parts[1])
+                        elif parts[0] == "event":
+                            step_input[in_key] = context["event"].get(parts[1])
+                        else:
+                            step_input[in_key] = in_val
+                    else:
+                        step_input[in_key] = in_val
+                
+                # Execute step
+                output = None
+                if step.kind == "adapter":
+                    if step.name not in adapters:
+                        raise ValueError(f"Adapter '{step.name}' not registered.")
+                    output = await adapters[step.name].execute(step_input)
+                elif step.kind == "handler":
+                    if step.name not in handlers:
+                        raise ValueError(f"Handler '{step.name}' not registered.")
+                    output = await handlers[step.name].handle(event, step_input) # Pass resolved input
+                else:
+                    raise ValueError(f"Unknown step kind '{step.kind}'")
+                
+                context["steps"][step.id] = output
+                
+                # Handle Human-in-the-loop interruption
+                if output and output.get("status") == "awaiting_approval":
+                    latency = int((time.time() - start_time) * 1000)
+                    step_result = StepResult(
+                        status="awaiting_approval",
+                        output=output,
+                        started_at=started_at,
+                        ended_at=datetime.utcnow().isoformat(),
+                        latency_ms=latency
+                    )
+                    step_results[step.id] = step_result
+                    run_status = "suspended"
+                    break # Halt execution graph immediately
+                
+                latency = int((time.time() - start_time) * 1000)
+                step_result = StepResult(
+                    status="success",
+                    output=output,
+                    started_at=started_at,
+                    ended_at=datetime.utcnow().isoformat(),
+                    latency_ms=latency
+                )
+                
+            except Exception as e:
+                logger.error(f"Step {step.id} failed: {e}")
+                latency = int((time.time() - start_time) * 1000)
+                step_result = StepResult(
+                    status="failed",
+                    error={"message": str(e)},
+                    started_at=started_at,
+                    ended_at=datetime.utcnow().isoformat(),
+                    latency_ms=latency
+                )
+                step_results[step.id] = step_result
+                run_status = "failed"
+                break
+
+            step_results[step.id] = step_result
+
+        run_result = WorkflowRunResult(
+            run_id=run_id,
+            workflow_id=workflow.workflow_id,
+            status=run_status,
+            step_results=step_results
+        )
+        
+        # Persist State explicitly so it can be resumed later if 'suspended'
+        await self.storage.save_workflow_run(run_id, run_result.model_dump())
+        return run_result

agentic_notify-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[tool.poetry]
+name = "agentic-notify"
+version = "0.1.0"
+description = "A Python library for building agentic, notification-driven workflows with pluggable adapters, policy-aware handlers, and scalable integration interfaces."
+authors = ["Your Name <you@example.com>"]
+readme = "README.md"
+packages = [{include = "agentic_notify"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+pydantic = "^2.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+ruff = "^0.3.0"
+black = "^24.2.0"
+mypy = "^1.8.0"
+
+[tool.poetry.extras]
+fastapi = ["fastapi", "uvicorn"]
+redis = ["redis"]
+mcp = ["mcp"] # Assuming standard mcp sdk
+observability = ["opentelemetry-api", "opentelemetry-sdk"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]