genxai-framework 0.1.0__py3-none-any.whl

genxai/__init__.py

@@ -0,0 +1,81 @@
+"""
+GenXAI - Advanced Agentic AI Framework
+
+A powerful framework for building multi-agent AI systems with graph-based orchestration,
+advanced memory systems, and enterprise-grade features.
+"""
+
+__version__ = "0.1.0"
+__author__ = "GenXAI Team"
+__license__ = "MIT"
+
+from genxai.core.agent import (
+    Agent,
+    AgentConfig,
+    AgentFactory,
+    AgentRegistry,
+    AgentRuntime,
+    AgentType,
+)
+from genxai.core.graph import (
+    Edge,
+    EnhancedGraph,
+    Graph,
+    Node,
+    NodeType,
+    TriggerWorkflowRunner,
+    WorkflowExecutor,
+    execute_workflow_sync,
+)
+from genxai.core.memory.manager import MemorySystem
+from genxai.tools import (
+    DynamicTool,
+    Tool,
+    ToolCategory,
+    ToolMetadata,
+    ToolParameter,
+    ToolRegistry,
+    ToolResult,
+)
+from genxai.triggers import (
+    BaseTrigger,
+    TriggerEvent,
+    TriggerRegistry,
+    TriggerStatus,
+    WebhookTrigger,
+    ScheduleTrigger,
+    QueueTrigger,
+)
+
+__all__ = [
+    "__version__",
+    "Agent",
+    "AgentConfig",
+    "AgentFactory",
+    "AgentRegistry",
+    "AgentRuntime",
+    "AgentType",
+    "Graph",
+    "EnhancedGraph",
+    "WorkflowExecutor",
+    "execute_workflow_sync",
+    "TriggerWorkflowRunner",
+    "Node",
+    "NodeType",
+    "Edge",
+    "Tool",
+    "ToolCategory",
+    "ToolMetadata",
+    "ToolParameter",
+    "ToolRegistry",
+    "ToolResult",
+    "DynamicTool",
+    "MemorySystem",
+    "BaseTrigger",
+    "TriggerEvent",
+    "TriggerRegistry",
+    "TriggerStatus",
+    "WebhookTrigger",
+    "ScheduleTrigger",
+    "QueueTrigger",
+]

genxai/api/__init__.py

@@ -0,0 +1,5 @@
+"""API utilities for GenXAI (non-Studio)."""
+
+from genxai.api.app import create_app
+
+__all__ = ["create_app"]

genxai/api/app.py

@@ -0,0 +1,21 @@
+"""Minimal FastAPI app for GenXAI observability endpoints."""
+
+from fastapi import FastAPI, Response
+
+from genxai.observability.metrics import get_prometheus_metrics
+
+
+def create_app() -> FastAPI:
+    """Create a FastAPI app exposing observability endpoints.
+
+    Returns:
+        Configured FastAPI application
+    """
+    app = FastAPI(title="GenXAI Observability API", version="0.1.0")
+
+    @app.get("/metrics", response_class=Response)
+    async def metrics() -> Response:
+        """Expose Prometheus metrics."""
+        return Response(content=get_prometheus_metrics(), media_type="text/plain")
+
+    return app

genxai/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration helpers for GenXAI."""
+
+from genxai.config.settings import GenXAISettings, get_settings
+
+__all__ = ["GenXAISettings", "get_settings"]

genxai/config/settings.py

@@ -0,0 +1,37 @@
+"""Central configuration for GenXAI runtime."""
+
+from __future__ import annotations
+
+from typing import List, Set
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class GenXAISettings(BaseSettings):
+    """Global settings for GenXAI.
+
+    Environment variables use the GENXAI_ prefix.
+    """
+
+    model_config = SettingsConfigDict(env_prefix="GENXAI_", case_sensitive=False)
+
+    tool_allowlist: List[str] = Field(default_factory=list)
+    tool_denylist: List[str] = Field(default_factory=list)
+
+    def allowlist_set(self) -> Set[str]:
+        return {name.strip() for name in self.tool_allowlist if name.strip()}
+
+    def denylist_set(self) -> Set[str]:
+        return {name.strip() for name in self.tool_denylist if name.strip()}
+
+
+_settings: GenXAISettings | None = None
+
+
+def get_settings() -> GenXAISettings:
+    """Get cached settings instance."""
+    global _settings
+    if _settings is None:
+        _settings = GenXAISettings()
+    return _settings

genxai/connectors/__init__.py

@@ -0,0 +1,19 @@
+"""Connector SDK for GenXAI integrations."""
+
+from genxai.connectors.base import Connector, ConnectorEvent, ConnectorStatus
+from genxai.connectors.registry import ConnectorRegistry
+from genxai.connectors.webhook import WebhookConnector
+from genxai.connectors.kafka import KafkaConnector
+from genxai.connectors.sqs import SQSConnector
+from genxai.connectors.postgres_cdc import PostgresCDCConnector
+
+__all__ = [
+    "Connector",
+    "ConnectorEvent",
+    "ConnectorStatus",
+    "ConnectorRegistry",
+    "WebhookConnector",
+    "KafkaConnector",
+    "SQSConnector",
+    "PostgresCDCConnector",
+]

genxai/connectors/base.py

@@ -0,0 +1,122 @@
+"""Base connector abstractions for GenXAI."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Awaitable, Callable, Dict, Optional
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectorStatus(str, Enum):
+    """Lifecycle status for connectors."""
+
+    STOPPED = "stopped"
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    ERROR = "error"
+
+
+@dataclass
+class ConnectorEvent:
+    """Event emitted by connectors."""
+
+    connector_id: str
+    payload: Dict[str, Any]
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class Connector(ABC):
+    """Abstract base class for connector integrations."""
+
+    def __init__(self, connector_id: str, name: Optional[str] = None) -> None:
+        self.connector_id = connector_id
+        self.name = name or connector_id
+        self.status: ConnectorStatus = ConnectorStatus.STOPPED
+        self._callbacks: list[Callable[[ConnectorEvent], Awaitable[None]]] = []
+        self._lock = asyncio.Lock()
+        self._last_error: Optional[str] = None
+        self._last_healthcheck: Optional[str] = None
+
+    def on_event(self, callback: Callable[[ConnectorEvent], Awaitable[None]]) -> None:
+        """Register a callback to receive connector events."""
+        self._callbacks.append(callback)
+
+    async def emit(self, payload: Dict[str, Any], metadata: Optional[Dict[str, Any]] = None) -> None:
+        """Emit connector event to subscribers."""
+        event = ConnectorEvent(
+            connector_id=self.connector_id,
+            payload=payload,
+            metadata=metadata or {},
+        )
+        if not self._callbacks:
+            logger.warning("Connector %s emitted event with no subscribers", self.connector_id)
+            return
+
+        await asyncio.gather(*[callback(event) for callback in self._callbacks])
+
+    async def start(self) -> None:
+        """Start the connector."""
+        async with self._lock:
+            if self.status in {ConnectorStatus.RUNNING, ConnectorStatus.STARTING}:
+                return
+            self.status = ConnectorStatus.STARTING
+            try:
+                await self.validate_config()
+                await self._start()
+                self.status = ConnectorStatus.RUNNING
+                self._last_error = None
+                logger.info("Connector started: %s", self.connector_id)
+            except Exception as exc:
+                self.status = ConnectorStatus.ERROR
+                self._last_error = str(exc)
+                logger.error("Failed to start connector %s: %s", self.connector_id, exc)
+                raise
+
+    async def stop(self) -> None:
+        """Stop the connector."""
+        async with self._lock:
+            if self.status in {ConnectorStatus.STOPPED, ConnectorStatus.STOPPING}:
+                return
+            self.status = ConnectorStatus.STOPPING
+            try:
+                await self._stop()
+                self.status = ConnectorStatus.STOPPED
+                self._last_error = None
+                logger.info("Connector stopped: %s", self.connector_id)
+            except Exception as exc:
+                self.status = ConnectorStatus.ERROR
+                self._last_error = str(exc)
+                logger.error("Failed to stop connector %s: %s", self.connector_id, exc)
+                raise
+
+    async def health_check(self) -> Dict[str, Any]:
+        """Return a health payload for the connector."""
+        status = "ok" if self.status == ConnectorStatus.RUNNING else "not_running"
+        payload = {
+            "connector_id": self.connector_id,
+            "status": status,
+            "lifecycle": self.status.value,
+            "last_error": self._last_error,
+        }
+        self._last_healthcheck = datetime.utcnow().isoformat()
+        return payload
+
+    async def validate_config(self) -> None:
+        """Validate connector configuration before start."""
+        return None
+
+    @abstractmethod
+    async def _start(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def _stop(self) -> None:
+        raise NotImplementedError

genxai/connectors/kafka.py

@@ -0,0 +1,92 @@
+"""Kafka connector implementation."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Callable
+import asyncio
+import json
+import logging
+
+from genxai.connectors.base import Connector
+
+logger = logging.getLogger(__name__)
+
+
+class KafkaConnector(Connector):
+    """Kafka connector using aiokafka."""
+
+    def __init__(
+        self,
+        connector_id: str,
+        topic: str,
+        bootstrap_servers: str,
+        group_id: Optional[str] = None,
+        name: Optional[str] = None,
+        value_deserializer: Optional[Callable[[bytes], Any]] = None,
+        poll_interval: float = 0.1,
+    ) -> None:
+        super().__init__(connector_id=connector_id, name=name)
+        self.topic = topic
+        self.bootstrap_servers = bootstrap_servers
+        self.group_id = group_id
+        self.value_deserializer = value_deserializer or self._default_deserializer
+        self.poll_interval = poll_interval
+        self._consumer: Any = None
+        self._task: Optional[asyncio.Task[None]] = None
+
+    async def _start(self) -> None:
+        from aiokafka import AIOKafkaConsumer
+
+        self._consumer = AIOKafkaConsumer(
+            self.topic,
+            bootstrap_servers=self.bootstrap_servers,
+            group_id=self.group_id,
+            enable_auto_commit=True,
+            value_deserializer=self.value_deserializer,
+        )
+        await self._consumer.start()
+        self._task = asyncio.create_task(self._consume_loop())
+
+    async def _stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
+        if self._consumer:
+            await self._consumer.stop()
+            self._consumer = None
+
+    async def validate_config(self) -> None:
+        if not self.topic:
+            raise ValueError("Kafka topic must be provided")
+        if not self.bootstrap_servers:
+            raise ValueError("Kafka bootstrap_servers must be provided")
+
+    async def _consume_loop(self) -> None:
+        while True:
+            try:
+                msg = await self._consumer.getone()
+                payload = msg.value
+                await self.emit(
+                    payload=payload,
+                    metadata={
+                        "topic": msg.topic,
+                        "partition": msg.partition,
+                        "offset": msg.offset,
+                        "timestamp": msg.timestamp,
+                    },
+                )
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                logger.error("Kafka consumer error: %s", exc)
+                await asyncio.sleep(self.poll_interval)
+
+    def _default_deserializer(self, raw: bytes) -> Any:
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except Exception:
+            return raw
+
+    async def handle_message(self, payload: Dict[str, Any]) -> None:
+        await self.emit(payload=payload)

genxai/connectors/postgres_cdc.py

@@ -0,0 +1,95 @@
+"""Postgres CDC connector implementation (wal2json)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+import asyncio
+import json
+import logging
+
+
+from genxai.connectors.base import Connector
+
+logger = logging.getLogger(__name__)
+
+
+class PostgresCDCConnector(Connector):
+    """Postgres CDC connector using wal2json output plugin."""
+
+    def __init__(
+        self,
+        connector_id: str,
+        dsn: str,
+        slot_name: str,
+        publication: str,
+        name: Optional[str] = None,
+        poll_interval: float = 1.0,
+    ) -> None:
+        super().__init__(connector_id=connector_id, name=name)
+        self.dsn = dsn
+        self.slot_name = slot_name
+        self.publication = publication
+        self.poll_interval = poll_interval
+        self._conn: Optional[Any] = None
+        self._task: Optional[asyncio.Task[None]] = None
+
+    async def _start(self) -> None:
+        import asyncpg
+
+        self._conn = await asyncpg.connect(self.dsn)
+        await self._ensure_slot()
+        self._task = asyncio.create_task(self._consume_loop())
+
+    async def _stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
+        if self._conn:
+            await self._conn.close()
+            self._conn = None
+
+    async def validate_config(self) -> None:
+        if not self.dsn:
+            raise ValueError("Postgres CDC dsn must be provided")
+        if not self.slot_name:
+            raise ValueError("Postgres CDC slot_name must be provided")
+        if not self.publication:
+            raise ValueError("Postgres CDC publication must be provided")
+
+    async def _ensure_slot(self) -> None:
+        assert self._conn is not None
+        await self._conn.execute(
+            "SELECT * FROM pg_create_logical_replication_slot($1, 'wal2json') "
+            "ON CONFLICT DO NOTHING;",
+            self.slot_name,
+        )
+
+    async def _consume_loop(self) -> None:
+        while True:
+            try:
+                assert self._conn is not None
+                rows = await self._conn.fetch(
+                    "SELECT data FROM pg_logical_slot_get_changes($1, NULL, NULL, 'pretty-print', '1')",
+                    self.slot_name,
+                )
+                for row in rows:
+                    payload = self._deserialize(row["data"])
+                    await self.emit(payload=payload)
+                await asyncio.sleep(self.poll_interval)
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                logger.error("Postgres CDC error: %s", exc)
+                await asyncio.sleep(self.poll_interval)
+
+    def _deserialize(self, raw: Optional[str]) -> Any:
+        if raw is None:
+            return None
+        try:
+            return json.loads(raw)
+        except Exception:
+            return raw
+
+    async def handle_change(self, payload: Dict[str, Any]) -> None:
+        await self.emit(payload=payload)

genxai/connectors/registry.py

@@ -0,0 +1,44 @@
+"""Connector registry for GenXAI integrations."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+import logging
+
+from genxai.connectors.base import Connector
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectorRegistry:
+    """Registry for connectors."""
+
+    _connectors: Dict[str, Connector] = {}
+
+    @classmethod
+    def register(cls, connector: Connector) -> None:
+        if connector.connector_id in cls._connectors:
+            logger.warning("Connector %s already registered", connector.connector_id)
+        cls._connectors[connector.connector_id] = connector
+
+    @classmethod
+    def unregister(cls, connector_id: str) -> None:
+        cls._connectors.pop(connector_id, None)
+
+    @classmethod
+    def get(cls, connector_id: str) -> Optional[Connector]:
+        return cls._connectors.get(connector_id)
+
+    @classmethod
+    def list_all(cls) -> List[Connector]:
+        return list(cls._connectors.values())
+
+    @classmethod
+    async def start_all(cls) -> None:
+        for connector in cls._connectors.values():
+            await connector.start()
+
+    @classmethod
+    async def stop_all(cls) -> None:
+        for connector in cls._connectors.values():
+            await connector.stop()

genxai/connectors/sqs.py

@@ -0,0 +1,94 @@
+"""AWS SQS connector implementation."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+import asyncio
+import json
+import logging
+
+
+from genxai.connectors.base import Connector
+
+logger = logging.getLogger(__name__)
+
+
+class SQSConnector(Connector):
+    """SQS connector using aioboto3."""
+
+    def __init__(
+        self,
+        connector_id: str,
+        queue_url: str,
+        region: Optional[str] = None,
+        name: Optional[str] = None,
+        poll_interval: float = 1.0,
+        wait_time_seconds: int = 10,
+        max_messages: int = 10,
+    ) -> None:
+        super().__init__(connector_id=connector_id, name=name)
+        self.queue_url = queue_url
+        self.region = region
+        self.poll_interval = poll_interval
+        self.wait_time_seconds = wait_time_seconds
+        self.max_messages = max_messages
+        self._task: Optional[asyncio.Task[None]] = None
+        self._session = None
+
+    async def _start(self) -> None:
+        self._task = asyncio.create_task(self._poll_loop())
+
+    async def _stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
+
+    async def validate_config(self) -> None:
+        if not self.queue_url:
+            raise ValueError("SQS queue_url must be provided")
+
+    async def _poll_loop(self) -> None:
+        while True:
+            try:
+                if self._session is None:
+                    import aioboto3
+
+                    self._session = aioboto3.Session()
+                async with self._session.client("sqs", region_name=self.region) as client:
+                    response = await client.receive_message(
+                        QueueUrl=self.queue_url,
+                        MaxNumberOfMessages=self.max_messages,
+                        WaitTimeSeconds=self.wait_time_seconds,
+                    )
+                    messages = response.get("Messages", [])
+                    for message in messages:
+                        body = message.get("Body")
+                        payload = self._deserialize(body)
+                        await self.emit(
+                            payload=payload,
+                            metadata={
+                                "message_id": message.get("MessageId"),
+                                "receipt_handle": message.get("ReceiptHandle"),
+                            },
+                        )
+                        await client.delete_message(
+                            QueueUrl=self.queue_url,
+                            ReceiptHandle=message.get("ReceiptHandle"),
+                        )
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                logger.error("SQS poll error: %s", exc)
+                await asyncio.sleep(self.poll_interval)
+
+    def _deserialize(self, body: Optional[str]) -> Any:
+        if body is None:
+            return None
+        try:
+            return json.loads(body)
+        except Exception:
+            return body
+
+    async def handle_message(self, payload: Dict[str, Any]) -> None:
+        await self.emit(payload=payload)

genxai/connectors/webhook.py

@@ -0,0 +1,73 @@
+"""Webhook connector implementation."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+import hmac
+import hashlib
+import logging
+
+from genxai.connectors.base import Connector
+
+logger = logging.getLogger(__name__)
+
+
+class WebhookConnector(Connector):
+    """HTTP webhook connector.
+
+    Provides a handler that can be mounted in FastAPI or other ASGI frameworks.
+    """
+
+    def __init__(
+        self,
+        connector_id: str,
+        secret: Optional[str] = None,
+        name: Optional[str] = None,
+        header_name: str = "X-GenXAI-Signature",
+        hash_alg: str = "sha256",
+    ) -> None:
+        super().__init__(connector_id=connector_id, name=name)
+        self.secret = secret
+        self.header_name = header_name
+        self.hash_alg = hash_alg
+
+    async def _start(self) -> None:
+        logger.debug("Webhook connector %s ready for requests", self.connector_id)
+
+    async def _stop(self) -> None:
+        logger.debug("Webhook connector %s stopped", self.connector_id)
+
+    async def validate_config(self) -> None:
+        if self.secret is not None and not isinstance(self.secret, str):
+            raise ValueError("Webhook secret must be a string")
+        if not self.header_name:
+            raise ValueError("Webhook header_name must be set")
+        if not hasattr(hashlib, self.hash_alg):
+            raise ValueError(f"Unsupported hash algorithm: {self.hash_alg}")
+
+    def validate_signature(self, payload: bytes, signature: Optional[str]) -> bool:
+        if not self.secret:
+            return True
+        if not signature:
+            return False
+
+        digest = hmac.new(self.secret.encode(), payload, getattr(hashlib, self.hash_alg)).hexdigest()
+        expected = f"{self.hash_alg}={digest}"
+        return hmac.compare_digest(expected, signature)
+
+    async def handle_request(
+        self,
+        payload: Dict[str, Any],
+        raw_body: Optional[bytes] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        headers = headers or {}
+        signature = headers.get(self.header_name)
+
+        if self.secret and raw_body is not None:
+            if not self.validate_signature(raw_body, signature):
+                logger.warning("Webhook signature validation failed for %s", self.connector_id)
+                return {"status": "rejected", "reason": "invalid signature"}
+
+        await self.emit(payload=payload, metadata={"headers": headers})
+        return {"status": "accepted", "connector_id": self.connector_id}