nl2sql-adapter-sdk 0.1.0__tar.gz

nl2sql_adapter_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: nl2sql-adapter-sdk
+Version: 0.1.0
+Summary: Shared adapter contracts for NL2SQL
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=1.10

nl2sql_adapter_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nl2sql-adapter-sdk"
+version = "0.1.0" # x-release-please-version
+description = "Shared adapter contracts for NL2SQL"
+requires-python = ">=3.9"
+dependencies = [
+    "pydantic>=1.10",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["nl2sql_adapter_sdk*"]

nl2sql_adapter_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk/__init__.py

@@ -0,0 +1,37 @@
+"""Adapter SDK: shared contracts for core and adapters."""
+
+from .capabilities import DatasourceCapability
+from .contracts import AdapterRequest, ResultError, ResultFrame
+from .protocols import DatasourceAdapterProtocol
+from .schema import (
+    TableRef,
+    ColumnStatistics,
+    ColumnMetadata,
+    ColumnContract,
+    ForeignKeyContract,
+    TableContract,
+    TableMetadata,
+    SchemaContract,
+    SchemaMetadata,
+    SchemaSnapshot,
+    ColumnRef   
+)
+
+__all__ = [
+    "DatasourceCapability",
+    "AdapterRequest",
+    "ResultError",
+    "ResultFrame",
+    "DatasourceAdapterProtocol",
+    "TableRef",
+    "ColumnStatistics",
+    "ColumnMetadata",
+    "ColumnContract",
+    "ForeignKeyContract",
+    "TableContract",
+    "TableMetadata",
+    "SchemaContract",
+    "SchemaMetadata",
+    "SchemaSnapshot",
+    "ColumnRef",
+]

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk/capabilities.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class DatasourceCapability(str, Enum):
+    """Capability flags for datasource adapters."""
+
+    SUPPORTS_SQL = "supports_sql"
+    SUPPORTS_REST = "supports_rest"
+    SUPPORTS_GRAPHQL = "supports_graphql"
+    SUPPORTS_LAKE = "supports_lake"
+    SUPPORTS_SCHEMA_INTROSPECTION = "supports_schema_introspection"
+    SUPPORTS_DRY_RUN = "supports_dry_run"
+    SUPPORTS_COST_ESTIMATE = "supports_cost_estimate"

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk/contracts.py

@@ -0,0 +1,87 @@
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AdapterRequest(BaseModel):
+    """Generic adapter request for subgraph execution."""
+
+    plan_type: str = Field(
+        ..., description="Execution plan type (e.g., 'sql', 'rest', 'nosql')."
+    )
+    payload: Dict[str, Any] = Field(
+        default_factory=dict, description="Plan-specific request payload."
+    )
+    parameters: Dict[str, Any] = Field(
+        default_factory=dict, description="Optional parameter bindings."
+    )
+    limits: Dict[str, int] = Field(
+        default_factory=dict,
+        description="Execution limits (row_limit, timeout_ms, max_bytes).",
+    )
+    trace_id: Optional[str] = Field(
+        default=None, description="Optional trace id for observability."
+    )
+
+    model_config = ConfigDict(extra="ignore")
+
+
+
+class ResultError(BaseModel):
+    """Standardized error envelope for adapter results."""
+
+    error_code: str
+    safe_message: str
+    severity: str = Field(default="ERROR")
+    retryable: bool = Field(default=False)
+    stage: Optional[str] = None
+    datasource_id: Optional[str] = None
+    error_id: Optional[str] = None
+
+
+class ResultFrame(BaseModel):
+    """Adapter-agnostic, DataFrame-like result contract."""
+
+    success: bool = Field(default=True)
+    columns: List[str] = Field(default_factory=list)
+    rows: List[List[Any]] = Field(default_factory=list)
+    row_count: int = Field(default=0)
+    truncated: bool = Field(default=False)
+    bytes: Optional[int] = Field(default=None)
+    datasource_id: Optional[str] = Field(default=None)
+    tenant_id: Optional[str] = Field(default=None)
+    execution_stats: Dict[str, Any] = Field(default_factory=dict)
+    error: Optional[ResultError] = Field(default=None)
+
+    model_config = ConfigDict(extra="ignore")
+
+    @classmethod
+    def from_row_dicts(
+        cls,
+        rows: List[Dict[str, Any]],
+        columns: Optional[List[str]] = None,
+        *,
+        row_count: Optional[int] = None,
+        **kwargs: Any,
+    ) -> "ResultFrame":
+        """Create a ResultFrame from list-of-dict rows."""
+
+        if columns is None:
+            columns = list(rows[0].keys()) if rows else []
+
+        row_values = [[row.get(col) for col in columns] for row in rows]
+
+        return cls(
+            columns=columns,
+            rows=row_values,
+            row_count=row_count if row_count is not None else len(row_values),
+            **kwargs,
+        )
+
+    def to_row_dicts(self) -> List[Dict[str, Any]]:
+        """Convert row values to list-of-dict rows using column order."""
+
+        if not self.rows or not self.columns:
+            return []
+        names = self.columns
+        return [dict(zip(names, row)) for row in self.rows]

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk/protocols.py

@@ -0,0 +1,41 @@
+from typing import Any, Dict, Optional, Protocol, Set, runtime_checkable
+
+from .capabilities import DatasourceCapability
+from .contracts import AdapterRequest, ResultFrame
+
+
+@runtime_checkable
+class DatasourceAdapterProtocol(Protocol):
+    """Contract for adapter implementations."""
+
+    datasource_id: str
+    datasource_engine_type: str
+    connection_args: Dict[str, Any]
+    statement_timeout_ms: Optional[int]
+    row_limit: Optional[int]
+    max_bytes: Optional[int]
+
+    def capabilities(self) -> Set[DatasourceCapability]:
+        """Returns supported capabilities for this adapter."""
+        ...
+
+    def connect(self) -> None:
+        """Initialize connections / clients based on config."""
+        ...
+
+    def fetch_schema_snapshot(self) -> Any:
+        """Return a structured schema snapshot if supported."""
+        ...
+
+    def execute(self, request: AdapterRequest) -> ResultFrame:
+        """Execute a plan-specific request and return a ResultFrame."""
+        ...
+
+    def get_dialect(self) -> str:
+        """Return the normalized dialect string (SQL adapters)."""
+        ...
+
+
+    def test_connection(self) -> bool:
+        """Test if the connection to the datasource can be established."""
+        ...

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk/schema.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Union, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Scalar = Union[str, int, float, bool, None]
+JsonValue = Union[Scalar, List[Scalar], Dict[str, Scalar]]
+
+
+class ColumnRef(BaseModel):
+    table: TableRef
+    column_name: str
+
+
+
+class TableRef(BaseModel):
+    schema_name: str
+    table_name: str
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    @property
+    def full_name(self) -> str:
+        return f"[{self.schema_name}].[{self.table_name}]"
+
+
+class ColumnStatistics(BaseModel):
+    null_percentage: float
+    distinct_count: int
+    min_value: Optional[Scalar] = None
+    max_value: Optional[Scalar] = None
+    sample_values: List[JsonValue] = Field(default_factory=list)
+
+    def __str__(self) -> str:
+        return (
+            "null_percentage: "
+            f"{self.null_percentage}, distinct_count: {self.distinct_count}, "
+            f"min_value: {self.min_value}, max_value: {self.max_value}, "
+            f"sample_values: {self.sample_values}"
+        )
+
+
+class ColumnMetadata(BaseModel):
+    description: Optional[str] = None
+    statistics: Optional[ColumnStatistics] = None
+    synonyms: Optional[List[str]] = None
+    pii: bool = False
+
+
+class ColumnContract(BaseModel):
+    name: str
+    data_type: str
+    is_nullable: bool = True
+    is_primary_key: bool = False
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+
+class ForeignKeyContract(BaseModel):
+    constrained_columns: List[str]
+    referred_table: TableRef
+    referred_columns: List[str]
+    cardinality: Literal[
+        "one-to-one",
+        "one-to-many",
+        "many-to-one",
+        "many-to-many",
+        "unknown",
+    ] = "unknown"
+    business_meaning: Optional[str] = None
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+
+class TableContract(BaseModel):
+    table: TableRef
+    columns: Dict[str, ColumnContract] = Field(default_factory=dict)
+    foreign_keys: List[ForeignKeyContract] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    @property
+    def full_name(self) -> str:
+        return f"[{self.table.schema_name}].[{self.table.table_name}]"
+
+
+class TableMetadata(BaseModel):
+    table: TableRef
+    columns: Dict[str, ColumnMetadata] = Field(default_factory=dict)
+    row_count: Optional[int] = None
+    description: Optional[str] = None
+
+    @property
+    def full_name(self) -> str:
+        return f"[{self.table.schema_name}].[{self.table.table_name}]"
+
+
+class SchemaContract(BaseModel):
+    datasource_id: str
+    engine_type: str
+    tables: Dict[str, TableContract] = Field(default_factory=dict)
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+
+class SchemaMetadata(BaseModel):
+    datasource_id: str
+    engine_type: str
+    description: Optional[str] = None
+    domains: Optional[List[str]] = None
+    tables: Dict[str, TableMetadata] = Field(default_factory=dict)
+
+
+class SchemaSnapshot(BaseModel):
+    contract: SchemaContract
+    metadata: SchemaMetadata

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk.egg-info/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: nl2sql-adapter-sdk
+Version: 0.1.0
+Summary: Shared adapter contracts for NL2SQL
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=1.10

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+pyproject.toml
+src/nl2sql_adapter_sdk/__init__.py
+src/nl2sql_adapter_sdk/capabilities.py
+src/nl2sql_adapter_sdk/contracts.py
+src/nl2sql_adapter_sdk/protocols.py
+src/nl2sql_adapter_sdk/schema.py
+src/nl2sql_adapter_sdk.egg-info/PKG-INFO
+src/nl2sql_adapter_sdk.egg-info/SOURCES.txt
+src/nl2sql_adapter_sdk.egg-info/dependency_links.txt
+src/nl2sql_adapter_sdk.egg-info/requires.txt
+src/nl2sql_adapter_sdk.egg-info/top_level.txt

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic>=1.10

nl2sql_adapter_sdk-0.1.0/src/nl2sql_adapter_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+nl2sql_adapter_sdk