nexusx 2.0.0__py3-none-any.whl

nexusx/__init__.py

@@ -0,0 +1,117 @@
+"""nexusx - GraphQL SDL generation and Core API response building.
+
+This package provides:
+- Automatic GraphQL SDL generation from SQLModel classes
+- @query/@mutation decorators for defining GraphQL operations
+- DataLoader-based relationship resolution
+- Per-relationship pagination support
+- DefineSubset for creating independent DTO models from SQLModel entities
+- ErManager for entity-relationship management and Resolver creation
+
+Example (GraphQL mode):
+    ```python
+    from sqlmodel import SQLModel, Field, Relationship, select
+    from nexusx import query, mutation, GraphQLHandler
+
+    class User(SQLModel, table=True):
+        id: int = Field(primary_key=True)
+        name: str
+        posts: list["Post"] = Relationship(back_populates="author", order_by="id")
+
+        @query
+        async def get_users(cls, limit: int = 10) -> list['User']:
+            stmt = select(cls).limit(limit)
+            result = await session.exec(stmt)
+            return list(result.all())
+
+    handler = GraphQLHandler(
+        base=User,
+        session_factory=async_session,
+        enable_pagination=True,
+    )
+    ```
+
+Example (Core API mode):
+    ```python
+    from sqlmodel import SQLModel
+    from nexusx import DefineSubset, ErManager, Loader
+
+    class UserDTO(DefineSubset):
+        __subset__ = (User, ('id', 'name'))
+
+    class PostDTO(DefineSubset):
+        __subset__ = (Post, ('id', 'title', 'author_id'))
+        author: UserDTO | None = None
+
+        def resolve_author(self, loader=Loader('author')):
+            return loader.load(self.author_id)
+
+    er = ErManager(base=SQLModel, session_factory=async_session)
+    Resolver = er.create_resolver()
+    result = await Resolver().resolve([PostDTO(...) for p in posts])
+    ```
+"""
+
+from __future__ import annotations
+
+__version__ = "1.9.0"
+
+from nexusx.context import Collector, ExposeAs, SendTo
+from nexusx.decorator import mutation, query
+from nexusx.er_diagram import ErDiagram
+from nexusx.handler import GraphQLHandler
+from nexusx.loader import ErManager
+from nexusx.query_parser import FieldSelection, QueryParser
+from nexusx.relationship import Relationship
+from nexusx.resolver import Loader
+from nexusx.sdl_generator import SDLGenerator
+from nexusx.standard_queries import AutoQueryConfig, add_standard_queries
+from nexusx.subset import DefineSubset, SubsetConfig, build_dto_select
+from nexusx.use_case import (
+    FromContext,
+    UseCaseAppConfig,
+    UseCaseService,
+    create_use_case_mcp_server,
+)
+from nexusx.use_case import (
+    create_router as create_use_case_router,
+)
+from nexusx.voyager import create_use_case_voyager
+
+__all__ = [
+    # Version
+    "__version__",
+    # Decorators
+    "query",
+    "mutation",
+    # Core classes
+    "SDLGenerator",
+    "QueryParser",
+    "GraphQLHandler",
+    "ErManager",
+    # Types
+    "FieldSelection",
+    # Standard queries
+    "AutoQueryConfig",
+    "add_standard_queries",
+    # Core API mode (use case response building)
+    "DefineSubset",
+    "SubsetConfig",
+    "Loader",
+    "ExposeAs",
+    "SendTo",
+    "Collector",
+    # Custom relationships
+    "Relationship",
+    "ErDiagram",
+    # Query builder
+    "build_dto_select",
+    # UseCase MCP mode
+    "UseCaseService",
+    "UseCaseAppConfig",
+    "FromContext",
+    "create_use_case_mcp_server",
+    "create_use_case_router",
+    # Voyager visualization
+    "create_use_case_voyager",
+]

nexusx/context.py

@@ -0,0 +1,212 @@
+"""Cross-layer data flow: ExposeAs, SendTo, Collector.
+
+Enables parent nodes to pass context down to descendants (ExposeAs)
+and descendants to aggregate values up to ancestors (SendTo + Collector).
+
+Usage:
+    from typing import Annotated
+    from nexusx import ExposeAs, SendTo, Collector
+
+    class SprintDTO(DefineSubset):
+        __subset__ = (Sprint, ('id', 'name'))
+        name: Annotated[str, ExposeAs('sprint_name')]
+        tasks: list[TaskDTO] = []
+        contributors: list[UserDTO] = []
+
+        def post_contributors(self, collector=Collector('contributors')):
+            return collector.values()
+
+    class TaskDTO(DefineSubset):
+        __subset__ = (Task, ('id', 'title'))
+        full_title: str = ""
+        owner: Annotated[UserDTO | None, SendTo('contributors')] = None
+
+        def post_full_title(self, ancestor_context):
+            return f"{ancestor_context['sprint_name']} / {self.title}"
+"""
+
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel
+
+# ──────────────────────────────────────────────────────────
+# ExposeAs — expose field value to descendant nodes
+# ──────────────────────────────────────────────────────────
+
+@dataclass
+class ExposeInfo:
+    """Metadata for ExposeAs annotation."""
+    alias: str
+
+
+def ExposeAs(alias: str) -> ExposeInfo:
+    """Mark a field to be exposed to descendant nodes via ancestor_context.
+
+    Args:
+        alias: The key name under which the value appears in ancestor_context.
+
+    Example:
+        name: Annotated[str, ExposeAs('sprint_name')]
+
+        # In descendant:
+        def post_full_title(self, ancestor_context):
+            return ancestor_context['sprint_name']
+    """
+    return ExposeInfo(alias=alias)
+
+
+# ──────────────────────────────────────────────────────────
+# SendTo — send field value to ancestor's Collector
+# ──────────────────────────────────────────────────────────
+
+@dataclass
+class SendToInfo:
+    """Metadata for SendTo annotation."""
+    collector_name: str | tuple[str, ...]
+
+
+def SendTo(name: str | tuple[str, ...]) -> SendToInfo:
+    """Mark a field to be collected by an ancestor's Collector.
+
+    Args:
+        name: Collector alias name (or tuple of names for multi-collector).
+
+    Example:
+        owner: Annotated[UserDTO | None, SendTo('contributors')]
+    """
+    return SendToInfo(collector_name=name)
+
+
+# ──────────────────────────────────────────────────────────
+# Collector — aggregate values from descendants
+# ──────────────────────────────────────────────────────────
+
+class ICollector(metaclass=abc.ABCMeta):
+    """Abstract base class for collectors."""
+
+    @abc.abstractmethod
+    def __init__(self, alias: str):
+        self.alias = alias
+
+    @abc.abstractmethod
+    def add(self, val: Any) -> None:
+        """Add a value to the collection."""
+
+    @abc.abstractmethod
+    def values(self) -> Any:
+        """Get collected values."""
+
+
+class Collector(ICollector):
+    """Collect values from descendant nodes marked with SendTo.
+
+    Used as a parameter in post_* methods:
+
+        def post_contributors(self, collector=Collector('contributors')):
+            return collector.values()
+
+    Args:
+        alias: The collector name, matching SendTo's target.
+        flat: If True, flatten list values (for list fields with SendTo).
+    """
+
+    def __init__(self, alias: str, flat: bool = False):
+        super().__init__(alias)
+        self.flat = flat
+        self.val: list[Any] = []
+
+    def add(self, val: Any | list[Any]) -> None:
+        if self.flat:
+            if isinstance(val, list):
+                self.val.extend(val)
+            else:
+                raise TypeError("flat mode requires list values")
+        else:
+            self.val.append(val)
+
+    def values(self) -> list[Any]:
+        return self.val
+
+
+# ──────────────────────────────────────────────────────────
+# Metadata scanning helpers (cached per class)
+# ──────────────────────────────────────────────────────────
+
+_expose_cache: dict[type, dict[str, str]] = {}
+_send_to_cache: dict[type, dict[str, str | tuple[str, ...]]] = {}
+
+
+def scan_expose_fields(kls: type[BaseModel]) -> dict[str, str]:
+    """Scan a class for fields with ExposeAs annotation.
+
+    Results are cached per class since field metadata doesn't change.
+
+    Returns:
+        Dict mapping field_name -> alias for all ExposeAs-annotated fields.
+    """
+    cached = _expose_cache.get(kls)
+    if cached is not None:
+        return cached
+    result: dict[str, str] = {}
+    for field_name, field_info in kls.model_fields.items():
+        for meta in field_info.metadata:
+            if isinstance(meta, ExposeInfo):
+                result[field_name] = meta.alias
+                break
+    _expose_cache[kls] = result
+    return result
+
+
+def scan_send_to_fields(kls: type[BaseModel]) -> dict[str, str | tuple[str, ...]]:
+    """Scan a class for fields with SendTo annotation.
+
+    Results are cached per class since field metadata doesn't change.
+
+    Returns:
+        Dict mapping field_name -> collector_name(s).
+    """
+    cached = _send_to_cache.get(kls)
+    if cached is not None:
+        return cached
+    result: dict[str, str | tuple[str, ...]] = {}
+    for field_name, field_info in kls.model_fields.items():
+        for meta in field_info.metadata:
+            if isinstance(meta, SendToInfo):
+                result[field_name] = meta.collector_name
+                break
+    _send_to_cache[kls] = result
+    return result
+
+
+# ──────────────────────────────────────────────────────────
+# AutoLoad — automatic relationship loading
+# ──────────────────────────────────────────────────────────
+
+@dataclass
+class AutoLoadInfo:
+    """Metadata for AutoLoad annotation."""
+    origin: str | None = None  # Override relationship name, defaults to field name
+
+
+def AutoLoad(origin: str | None = None) -> AutoLoadInfo:
+    """Mark a field for automatic relationship loading via LoaderRegistry.
+
+    When used in a DefineSubset DTO, the Resolver will automatically:
+    1. Look up the relationship in the LoaderRegistry
+    2. Load the data via DataLoader
+    3. Convert ORM results to the annotated DTO type
+
+    Args:
+        origin: Override relationship name. Defaults to the field name.
+
+    Example::
+
+        class TaskSummary(DefineSubset):
+            __subset__ = (Task, ('id', 'title', 'owner_id'))
+            owner: Annotated[UserSummary | None, AutoLoad()] = None
+    """
+    return AutoLoadInfo(origin=origin)

nexusx/decorator.py

@@ -0,0 +1,102 @@
+"""Decorators for marking SQLModel methods as GraphQL queries and mutations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+
+def query(func: Callable) -> classmethod:
+    """Mark a method as a GraphQL query.
+
+    This decorator automatically converts the method to a classmethod.
+    The GraphQL field name is generated as: `{entityName}{methodName}`.
+    The description is taken from the method's docstring.
+
+    Args:
+        func: The method to decorate.
+
+    Returns:
+        A classmethod decorator.
+
+    Example:
+        ```python
+        from sqlmodel import SQLModel
+        from nexusx import query
+
+        class User(SQLModel, table=True):
+            id: int
+            name: str
+
+            @query
+            async def get_all(cls, limit: int = 10) -> list['User']:
+                \"\"\"Get all users with optional limit.\"\"\"
+                return await fetch_users(limit)
+
+            @query
+            async def get_by_id(cls, id: int) -> Optional['User']:
+                \"\"\"Get a user by ID.\"\"\"
+                return await fetch_user(id)
+        ```
+
+    This generates the following GraphQL Schema:
+        ```graphql
+        type Query {
+            \"\"\"Get all users with optional limit.\"\"\"
+            userGetAll(limit: Int): [User!]!
+            \"\"\"Get a user by ID.\"\"\"
+            userGetById(id: Int!): User
+        }
+        ```
+    """
+    func._graphql_query = True  # type: ignore[attr-defined]
+    func._graphql_query_description = (func.__doc__.strip() if func.__doc__ else "")  # type: ignore[attr-defined]
+    return classmethod(func)
+
+
+def mutation(func: Callable) -> classmethod:
+    """Mark a method as a GraphQL mutation.
+
+    This decorator automatically converts the method to a classmethod.
+    The GraphQL field name is generated as: `{entityName}{methodName}`.
+    The description is taken from the method's docstring.
+
+    Args:
+        func: The method to decorate.
+
+    Returns:
+        A classmethod decorator.
+
+    Example:
+        ```python
+        from sqlmodel import SQLModel
+        from nexusx import mutation
+
+        class User(SQLModel, table=True):
+            id: int
+            name: str
+            email: str
+
+            @mutation
+            async def create(cls, name: str, email: str) -> 'User':
+                \"\"\"Create a new user.\"\"\"
+                return await create_user(name, email)
+
+            @mutation
+            async def update_email(cls, id: int, email: str) -> 'User':
+                \"\"\"Update user's email.\"\"\"
+                return await update_user_email(id, email)
+        ```
+
+    This generates the following GraphQL Schema:
+        ```graphql
+        type Mutation {
+            \"\"\"Create a new user.\"\"\"
+            userCreate(name: String!, email: String!): User!
+            \"\"\"Update user's email.\"\"\"
+            userUpdateEmail(id: Int!, email: String!): User!
+        }
+        ```
+    """
+    func._graphql_mutation = True  # type: ignore[attr-defined]
+    func._graphql_mutation_description = (func.__doc__.strip() if func.__doc__ else "")  # type: ignore[attr-defined]
+    return classmethod(func)

nexusx/discovery/__init__.py

@@ -0,0 +1,5 @@
+"""Entity discovery module."""
+
+from nexusx.discovery.entity_discovery import EntityDiscovery
+
+__all__ = ["EntityDiscovery"]

nexusx/discovery/entity_discovery.py

@@ -0,0 +1,112 @@
+"""Entity discovery module for GraphQL handlers.
+
+This module provides functionality to discover SQLModel entities
+that have @query/@mutation decorators, and traverse relationships to find related entities.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import TYPE_CHECKING
+
+from nexusx.response_builder import (
+    get_relation_entity,
+    get_relationship_names,
+)
+
+if TYPE_CHECKING:
+    pass
+
+
+class EntityDiscovery:
+    """Discovers SQLModel entities with @query/@mutation decorators.
+
+    Traverses relationships to include related entities even without decorators.
+    """
+
+    def __init__(self, base: type):
+        """Initialize the entity discovery.
+
+        Args:
+            base: The base class to scan for subclasses.
+        """
+        self._base = base
+        self._all_subclasses = self._collect_all_subclasses(base)
+
+    def discover(self, include_all: bool = False) -> list[type]:
+        """Discover all entities with decorators and their related entities.
+
+        Args:
+            include_all: If True, return all subclasses of the base entity.
+
+        Returns:
+            List of discovered entity classes.
+        """
+        if include_all:
+            return list(self._all_subclasses)
+
+        root_entities = self._find_root_entities()
+        return self._traverse_relationships(root_entities)
+
+    def _collect_all_subclasses(self, base: type) -> set[type]:
+        """Collect all subclasses recursively."""
+        discovered: set[type] = set()
+        queue = deque(base.__subclasses__())
+
+        while queue:
+            subclass = queue.popleft()
+            if subclass in discovered:
+                continue
+
+            discovered.add(subclass)
+            queue.extend(subclass.__subclasses__())
+
+        return discovered
+
+    def _find_root_entities(self) -> set[type]:
+        """Find entities with @query/@mutation decorators.
+
+        Returns:
+            Set of entities that have decorators.
+        """
+        root_entities: set[type] = set()
+
+        for subclass in self._all_subclasses:
+            for name in dir(subclass):
+                attr = getattr(subclass, name, None)
+                if hasattr(attr, "_graphql_query") or hasattr(attr, "_graphql_mutation"):
+                    root_entities.add(subclass)
+                    break
+
+        return root_entities
+
+    def _traverse_relationships(self, root_entities: set[type]) -> list[type]:
+        """Traverse relationships to find all related entities.
+
+        Uses BFS to discover entities connected through relationships.
+
+        Args:
+            root_entities: Starting entities with decorators.
+
+        Returns:
+            List of all discovered entities (roots + related).
+        """
+        discovered: set[type] = set()
+        queue = deque(root_entities)
+
+        while queue:
+            current = queue.popleft()
+            if current in discovered:
+                continue
+            discovered.add(current)
+
+            # Traverse all relationships of current entity
+            for rel_name in get_relationship_names(current):
+                target_entity = get_relation_entity(
+                    current, rel_name, self._all_subclasses
+                )
+                if target_entity and target_entity not in discovered:
+                    if target_entity in self._all_subclasses:
+                        queue.append(target_entity)
+
+        return list(discovered)