sfm-core 0.1.0__py3-none-any.whl

api/__init__.py

@@ -0,0 +1,19 @@
+"""
+API layer module for SFM Core.
+
+Provides the service facade for Beta unified model operations.
+"""
+
+from api.sfm_service import (
+    SFMService,
+    SFMServiceConfig,
+    ServiceHealth,
+    GraphStatistics,
+)
+
+__all__ = [
+    "SFMService",
+    "SFMServiceConfig",
+    "ServiceHealth",
+    "GraphStatistics",
+]

api/rest/__init__.py

@@ -0,0 +1 @@
+"""REST API module for SFM Core."""

api/rest/app.py

@@ -0,0 +1,87 @@
+"""FastAPI application factory for SFM Core REST API."""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.exceptions import RequestValidationError
+
+from api.rest.config import settings
+from api.rest.exceptions import (
+    sfm_exception_handler,
+    validation_exception_handler,
+    generic_exception_handler,
+)
+from models.exceptions import SFMError
+
+# Import routers
+from api.rest.routers import health, nodes, relationships, query, evaluate, import_export
+
+
+def create_app() -> FastAPI:
+    """
+    Create and configure FastAPI application.
+
+    Returns:
+        Configured FastAPI application instance
+    """
+    app = FastAPI(
+        title=settings.PROJECT_NAME,
+        version=settings.PROJECT_VERSION,
+        debug=settings.DEBUG,
+        docs_url=f"{settings.API_V1_PREFIX}/docs",
+        openapi_url=f"{settings.API_V1_PREFIX}/openapi.json",
+        redoc_url=f"{settings.API_V1_PREFIX}/redoc",
+        description="REST API for Social Fabric Matrix (SFM) Core framework - "
+                    "modeling, analyzing, and querying complex socio-economic systems",
+    )
+
+    # CORS middleware
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.CORS_ORIGINS,
+        allow_credentials=settings.CORS_ALLOW_CREDENTIALS,
+        allow_methods=settings.CORS_ALLOW_METHODS,
+        allow_headers=settings.CORS_ALLOW_HEADERS,
+    )
+
+    # Exception handlers
+    app.add_exception_handler(SFMError, sfm_exception_handler)  # type: ignore[arg-type]
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)  # type: ignore[arg-type]
+    app.add_exception_handler(Exception, generic_exception_handler)
+
+    # Include routers
+    app.include_router(
+        health.router,
+        prefix=settings.API_V1_PREFIX,
+        tags=["Health & Diagnostics"]
+    )
+    app.include_router(
+        nodes.router,
+        prefix=f"{settings.API_V1_PREFIX}/nodes",
+        tags=["Nodes"]
+    )
+    app.include_router(
+        relationships.router,
+        prefix=f"{settings.API_V1_PREFIX}/relationships",
+        tags=["Relationships"]
+    )
+    app.include_router(
+        query.router,
+        prefix=f"{settings.API_V1_PREFIX}/query",
+        tags=["Query Analysis"]
+    )
+    app.include_router(
+        evaluate.router,
+        prefix=f"{settings.API_V1_PREFIX}/evaluate",
+        tags=["Evaluation"]
+    )
+    app.include_router(
+        import_export.router,
+        prefix=f"{settings.API_V1_PREFIX}/import",
+        tags=["Import/Export"]
+    )
+
+    return app
+
+
+# Create application instance
+app = create_app()

api/rest/config.py

@@ -0,0 +1,39 @@
+"""Configuration settings for SFM REST API."""
+
+from typing import List
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class APISettings(BaseSettings):
+    """API configuration settings loaded from environment variables."""
+
+    # API Settings
+    API_V1_PREFIX: str = "/api/v1"
+    PROJECT_NAME: str = "SFM Core REST API"
+    PROJECT_VERSION: str = "1.0.0"
+    DEBUG: bool = False
+
+    # CORS
+    CORS_ORIGINS: List[str] = ["*"]
+    CORS_ALLOW_CREDENTIALS: bool = True
+    CORS_ALLOW_METHODS: List[str] = ["*"]
+    CORS_ALLOW_HEADERS: List[str] = ["*"]
+
+    # Service Configuration
+    STORAGE_TYPE: str = "networkx"
+    GRAPH_SIZE_LIMIT: int = 10000
+
+    # Neo4j (optional, for production)
+    NEO4J_URI: str = "bolt://localhost:7687"
+    NEO4J_USERNAME: str = "neo4j"
+    NEO4J_PASSWORD: str = "password"
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=True
+    )
+
+
+# Global settings instance
+settings = APISettings()

api/rest/dependencies.py

@@ -0,0 +1,24 @@
+"""Dependency injection for REST API."""
+
+from functools import lru_cache
+from api.sfm_service import SFMService, SFMServiceConfig
+from api.rest.config import settings
+
+
+@lru_cache()
+def get_sfm_service() -> SFMService:
+    """
+    Get or create singleton SFMService instance.
+
+    Uses lru_cache to ensure one instance per worker process.
+    Safe for NetworkX backend (thread-safe reads).
+    For Neo4j backend, connection pooling handles concurrency.
+
+    Returns:
+        SFMService instance configured from environment settings.
+    """
+    config = SFMServiceConfig(
+        storage_type=settings.STORAGE_TYPE,
+        graph_size_limit=settings.GRAPH_SIZE_LIMIT,
+    )
+    return SFMService(config=config)

api/rest/exceptions.py

@@ -0,0 +1,126 @@
+"""HTTP exception handlers for REST API.
+
+Note: Some status codes use raw integers (422, 413) instead of named constants
+to avoid deprecation warnings. The new constant names (HTTP_422_UNPROCESSABLE_CONTENT,
+HTTP_413_CONTENT_TOO_LARGE) are not yet available in Starlette 1.1.0.
+"""
+
+from datetime import datetime, timezone
+from fastapi import Request, status
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+
+from models.exceptions import (
+    SFMError,
+    ErrorCode,
+)
+
+
+# HTTP status code mapping for SFM error codes
+ERROR_CODE_HTTP_STATUS = {
+    ErrorCode.NOT_FOUND_ERROR: status.HTTP_404_NOT_FOUND,
+    ErrorCode.VALIDATION_ERROR: status.HTTP_400_BAD_REQUEST,
+    ErrorCode.NODE_CREATION_ERROR: status.HTTP_400_BAD_REQUEST,
+    ErrorCode.NODE_UPDATE_ERROR: status.HTTP_400_BAD_REQUEST,
+    ErrorCode.NODE_DELETE_ERROR: status.HTTP_400_BAD_REQUEST,
+    ErrorCode.RELATIONSHIP_ERROR: status.HTTP_400_BAD_REQUEST,
+    ErrorCode.INTEGRITY_ERROR: status.HTTP_409_CONFLICT,
+    ErrorCode.QUERY_EXECUTION_ERROR: status.HTTP_500_INTERNAL_SERVER_ERROR,
+    ErrorCode.QUERY_TIMEOUT_ERROR: status.HTTP_504_GATEWAY_TIMEOUT,
+    ErrorCode.QUERY_SYNTAX_ERROR: status.HTTP_400_BAD_REQUEST,
+    ErrorCode.DATABASE_CONNECTION_ERROR: status.HTTP_503_SERVICE_UNAVAILABLE,
+    ErrorCode.DATABASE_TRANSACTION_ERROR: status.HTTP_500_INTERNAL_SERVER_ERROR,
+    ErrorCode.DATABASE_PERSISTENCE_ERROR: status.HTTP_500_INTERNAL_SERVER_ERROR,
+    ErrorCode.PERMISSION_DENIED_ERROR: status.HTTP_403_FORBIDDEN,
+    ErrorCode.SECURITY_VALIDATION_ERROR: status.HTTP_403_FORBIDDEN,
+    ErrorCode.GRAPH_SIZE_EXCEEDED: 413,  # Raw int avoids deprecation (HTTP_413_CONTENT_TOO_LARGE not yet available)
+    ErrorCode.GRAPH_OPERATION_ERROR: status.HTTP_500_INTERNAL_SERVER_ERROR,
+}
+
+
+async def sfm_exception_handler(request: Request, exc: SFMError) -> JSONResponse:
+    """
+    Handle SFMError exceptions and convert to HTTP responses.
+
+    Maps SFM error codes to appropriate HTTP status codes and
+    returns structured error response.
+
+    Args:
+        request: FastAPI request object
+        exc: SFMError exception instance
+
+    Returns:
+        JSONResponse with error details and appropriate status code
+    """
+    # Get HTTP status code from error code, default to 500
+    http_status = ERROR_CODE_HTTP_STATUS.get(
+        exc.error_code,
+        status.HTTP_500_INTERNAL_SERVER_ERROR
+    )
+
+    # Build error response
+    error_response = {
+        "error": exc.error_code.value if hasattr(exc.error_code, "value") else str(exc.error_code),
+        "message": exc.message,
+        "context": exc.context.to_dict() if hasattr(exc.context, "to_dict") else {},
+        "remediation": exc.remediation,
+        "details": exc.details if hasattr(exc, "details") else None,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+    return JSONResponse(
+        status_code=http_status,
+        content=error_response
+    )
+
+
+async def validation_exception_handler(
+    request: Request,
+    exc: RequestValidationError
+) -> JSONResponse:
+    """
+    Handle Pydantic validation errors.
+
+    Args:
+        request: FastAPI request object
+        exc: RequestValidationError exception
+
+    Returns:
+        JSONResponse with validation error details
+    """
+    return JSONResponse(
+        status_code=422,  # Raw int avoids deprecation (HTTP_422_UNPROCESSABLE_CONTENT not yet available)
+        content={
+            "error": "VALIDATION_ERROR",
+            "message": "Request validation failed",
+            "context": {
+                "errors": exc.errors(),
+                "body": exc.body if hasattr(exc, "body") else None,
+            },
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+    )
+
+
+async def generic_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """
+    Handle unexpected exceptions.
+
+    Args:
+        request: FastAPI request object
+        exc: Generic exception
+
+    Returns:
+        JSONResponse with generic error message
+    """
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={
+            "error": "INTERNAL_SERVER_ERROR",
+            "message": "An unexpected error occurred",
+            "context": {
+                "exception_type": type(exc).__name__,
+            },
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+    )

api/rest/node_registry.py

@@ -0,0 +1,120 @@
+"""Node type registry for API validation.
+
+This module provides a centralized registry of all available SFM node types,
+enabling validation and documentation of node_type parameters in API endpoints.
+"""
+
+from typing import Set, Dict
+
+# Complete registry of all Node subclasses from models/
+# Organized by domain module for maintainability
+NODE_TYPES: Dict[str, Set[str]] = {
+    "base": {
+        "Node",  # Base class from models/base_nodes.py
+    },
+    "complex_analysis": {
+        "DigraphAnalysis",
+        "CircularCausationProcess",
+        "ConflictDetection",
+    },
+    "cultural_analysis": {
+        "CeremonialInstrumentalClassification",
+        "ValueSystem",
+        "SocialBelief",
+        "CulturalAttitude",
+    },
+    "economic_analysis": {
+        "TransactionCost",
+        "CoordinationMechanism",
+        "CommonsGovernance",
+    },
+    "institutional_analysis": {
+        "InstitutionalStructure",
+        "PathDependencyAnalysis",
+    },
+    "matrix_components": {
+        "MatrixCell",
+        "SFMCriteria",
+        "SFMMatrix",
+    },
+    "meta_entities": {
+        "Scenario",
+        "ScenarioSet",
+        "ScenarioPath",
+    },
+    "methodological_framework": {
+        "InstrumentalistInquiryFramework",
+        "NormativeSystemsAnalysis",
+        "PolicyRelevanceIntegration",
+        "DatabaseIntegrationCapability",
+    },
+    "network_analysis": {
+        "CrossImpactAnalysis",
+        "DeliveryRelationship",
+        "MatrixDeliveryNetwork",
+    },
+    "policy_framework": {
+        "PolicyInstrument",
+        "ValueJudgment",
+        "ProblemSolvingSequence",
+    },
+    "social_assessment": {
+        "SocialValueAssessment",
+        "SocialFabricIndicator",
+        "SocialCost",
+    },
+    "specialized_components": {
+        "SocialIndicatorSystem",
+        "EvolutionaryPathway",
+        "SocialProvisioningMatrix",
+    },
+    "system_analysis": {
+        "SystemProperty",
+        "SystemLevelAnalysis",
+        "InstitutionalHolarchy",
+    },
+    "technology_integration": {
+        "ToolSkillTechnologyComplex",
+        "EcologicalSystem",
+    },
+}
+
+
+def get_all_node_types() -> Set[str]:
+    """
+    Get set of all valid node type names.
+
+    Returns:
+        Set of all node type class names
+    """
+    all_types = set()
+    for types in NODE_TYPES.values():
+        all_types.update(types)
+    return all_types
+
+
+def is_valid_node_type(node_type: str) -> bool:
+    """
+    Check if a node type is valid.
+
+    Args:
+        node_type: Node type name to validate
+
+    Returns:
+        True if node_type is in the registry
+    """
+    return node_type in get_all_node_types()
+
+
+def get_node_types_by_domain() -> Dict[str, Set[str]]:
+    """
+    Get node types organized by domain module.
+
+    Returns:
+        Dictionary mapping domain module names to sets of node types
+    """
+    return NODE_TYPES.copy()
+
+
+# Pre-computed set for fast validation
+ALL_NODE_TYPES = get_all_node_types()

api/rest/routers/__init__.py

@@ -0,0 +1 @@
+"""REST API routers."""