nexaql 0.1.1__py3-none-any.whl

nexaql/__main__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""Allow running nexaql as ``python -m nexaql``."""
+
+from nexaql.cli import main
+
+main()

nexaql/adapters/__init__.py

@@ -0,0 +1,90 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""Adapter registry — maps datasource configs to concrete QueryAdapter instances."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+from nexaql.adapters.base import AdapterResult, QueryAdapter
+
+# Lazy imports to avoid pulling in heavy optional dependencies (asyncpg, duckdb)
+# at module-load time.
+
+_ADAPTER_REGISTRY: Dict[str, str] = {
+    "postgresql": "nexaql.adapters.postgresql.PostgreSQLAdapter",
+    "duckdb": "nexaql.adapters.duckdb_adapter.DuckDBAdapter",
+}
+
+
+def _import_class(dotted_path: str) -> Type[QueryAdapter]:
+    """Import a class from a fully qualified dotted path."""
+    module_path, class_name = dotted_path.rsplit(".", 1)
+    import importlib
+
+    module = importlib.import_module(module_path)
+    return getattr(module, class_name)
+
+
+def get_adapter(datasource_config: Any) -> QueryAdapter:
+    """Instantiate the appropriate :class:`QueryAdapter` for *datasource_config*.
+
+    Parameters
+    ----------
+    datasource_config:
+        A datasource configuration object (e.g. from ``nexaql.yaml`` or the
+        ontology models).  Must expose a ``type`` attribute (``str``) and may
+        carry adapter-specific fields such as ``url`` or ``path``.
+
+    Returns
+    -------
+    QueryAdapter
+        A ready-to-use adapter instance.
+
+    Raises
+    ------
+    ValueError
+        If the datasource type is not supported.
+    """
+    ds_type: str = getattr(datasource_config, "type", None) or (
+        datasource_config.get("type") if isinstance(datasource_config, dict) else None
+    )
+
+    if ds_type is None:
+        raise ValueError("Datasource config must have a 'type' field")
+
+    dotted_path = _ADAPTER_REGISTRY.get(ds_type)
+    if dotted_path is None:
+        raise ValueError(
+            f"Unsupported datasource type '{ds_type}'. "
+            f"Supported types: {', '.join(sorted(_ADAPTER_REGISTRY))}"
+        )
+
+    adapter_cls = _import_class(dotted_path)
+
+    # Build constructor kwargs from the config
+    if ds_type == "postgresql":
+        url = getattr(datasource_config, "url", None) or (
+            datasource_config.get("url") if isinstance(datasource_config, dict) else None
+        )
+        if not url:
+            raise ValueError("PostgreSQL datasource requires a 'url' field")
+        return adapter_cls(connection_url=url)
+
+    if ds_type == "duckdb":
+        path = getattr(datasource_config, "path", None) or (
+            datasource_config.get("path") if isinstance(datasource_config, dict) else None
+        )
+        seed_file = getattr(datasource_config, "seed_file", None) or (
+            datasource_config.get("seed_file") if isinstance(datasource_config, dict) else None
+        )
+        return adapter_cls(path=path or ":memory:", seed_file=seed_file)
+
+    # Generic fallback (should not be reached given the registry check above)
+    return adapter_cls()
+
+
+__all__ = [
+    "AdapterResult",
+    "QueryAdapter",
+    "get_adapter",
+]

nexaql/adapters/base.py

@@ -0,0 +1,47 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""Abstract base class and shared types for database adapters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from nexaql.engine.types import ColumnMeta, NodeShape, QueryAST
+
+
+@dataclass
+class AdapterResult:
+    """Result returned by a QueryAdapter after executing a query."""
+
+    rows: List[Dict[str, Any]]
+    columns: List[ColumnMeta]
+    row_count: int
+    shape: NodeShape
+    query_preview: str
+    adapter_type: str
+
+
+class QueryAdapter(ABC):
+    """Interface that every database adapter must implement."""
+
+    @property
+    @abstractmethod
+    def adapter_type(self) -> str:
+        """Short identifier for this adapter (e.g. ``'postgresql'``, ``'duckdb'``)."""
+        ...
+
+    @abstractmethod
+    async def execute(self, ast: QueryAST, ontology: Any) -> AdapterResult:
+        """Translate *ast* to SQL using *ontology*, run it, and return the result."""
+        ...
+
+    @abstractmethod
+    def describe(self, ast: QueryAST, ontology: Any) -> str:
+        """Translate *ast* to SQL and return the SQL string without executing."""
+        ...
+
+    @abstractmethod
+    async def healthcheck(self) -> bool:
+        """Return ``True`` if the underlying datasource is reachable."""
+        ...

nexaql/adapters/duckdb_adapter.py

@@ -0,0 +1,138 @@
+"""DuckDB adapter — executes NexaQL queries against a DuckDB database."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Dict, List
+
+import duckdb
+
+from nexaql.adapters.base import AdapterResult, QueryAdapter
+from nexaql.engine.translator import translate
+from nexaql.engine.types import ColumnMeta, QueryAST
+
+# DuckDB Python type name -> friendly type name
+_DUCKDB_TYPE_MAP: Dict[str, str] = {
+    "BOOLEAN": "boolean",
+    "TINYINT": "integer",
+    "SMALLINT": "integer",
+    "INTEGER": "integer",
+    "BIGINT": "integer",
+    "HUGEINT": "integer",
+    "FLOAT": "numeric",
+    "DOUBLE": "numeric",
+    "DECIMAL": "numeric",
+    "VARCHAR": "string",
+    "DATE": "date",
+    "TIMESTAMP": "date",
+    "TIMESTAMP WITH TIME ZONE": "date",
+}
+
+
+def _duckdb_type_to_str(type_name: Any) -> str:
+    # DuckDB returns DuckDBPyType objects, not plain strings — convert first
+    name = str(type_name).upper()
+    return _DUCKDB_TYPE_MAP.get(name, "string")
+
+
+class DuckDBAdapter(QueryAdapter):
+    """In-process adapter for DuckDB.
+
+    Uses a persistent connection so :memory: databases retain data across queries.
+    Supports auto-seeding via a SQL file on first connect.
+    """
+
+    def __init__(self, path: str = ":memory:", seed_file: str | None = None) -> None:
+        self._path = path
+        self._seed_file = seed_file
+        self._conn: duckdb.DuckDBPyConnection | None = None
+
+    def _get_conn(self) -> duckdb.DuckDBPyConnection:
+        if self._conn is None:
+            self._conn = duckdb.connect(self._path)
+            self._maybe_seed()
+        return self._conn
+
+    def _maybe_seed(self) -> None:
+        """Run the seed SQL file if the database has no tables."""
+        if not self._seed_file or not self._conn:
+            return
+
+        # Check if tables already exist
+        tables = self._conn.execute(
+            "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'main'"
+        ).fetchone()
+        if tables and tables[0] > 0:
+            return
+
+        # Resolve seed file path relative to config file location
+        seed_path = self._seed_file
+        if not os.path.isabs(seed_path):
+            # Try relative to CWD
+            if not os.path.exists(seed_path):
+                return
+
+        if os.path.exists(seed_path):
+            with open(seed_path) as f:
+                sql = f.read()
+            self._conn.execute(sql)
+            table_count = self._conn.execute(
+                "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'main'"
+            ).fetchone()
+            print(f"  Seeded DuckDB with {table_count[0] if table_count else 0} tables from {seed_path}")
+
+    # -- QueryAdapter interface ------------------------------------------------
+
+    @property
+    def adapter_type(self) -> str:
+        return "duckdb"
+
+    def describe(self, ast: QueryAST, ontology: Any) -> str:
+        result = translate(ast, ontology)
+        return result.sql
+
+    async def execute(self, ast: QueryAST, ontology: Any) -> AdapterResult:
+        result = translate(ast, ontology)
+        sql = result.sql
+
+        loop = asyncio.get_running_loop()
+        rows, columns = await loop.run_in_executor(None, self._run_query, sql)
+
+        return AdapterResult(
+            rows=rows,
+            columns=columns,
+            row_count=len(rows),
+            shape=result.shape,
+            query_preview=sql,
+            adapter_type=self.adapter_type,
+        )
+
+    async def healthcheck(self) -> bool:
+        try:
+            loop = asyncio.get_running_loop()
+            await loop.run_in_executor(None, self._ping)
+            return True
+        except Exception:
+            return False
+
+    # -- internal helpers ------------------------------------------------------
+
+    def _run_query(self, sql: str) -> tuple[List[Dict[str, Any]], List[ColumnMeta]]:
+        conn = self._get_conn()
+        rel = conn.execute(sql)
+        description = rel.description
+        raw_rows = rel.fetchall()
+
+        columns: List[ColumnMeta] = []
+        col_names: List[str] = []
+        for col_name, col_type, *_ in description:
+            columns.append(ColumnMeta(name=col_name, type=_duckdb_type_to_str(col_type)))
+            col_names.append(col_name)
+
+        rows: List[Dict[str, Any]] = [dict(zip(col_names, row)) for row in raw_rows]
+        return rows, columns
+
+    def _ping(self) -> None:
+        conn = self._get_conn()
+        conn.execute("SELECT 1").fetchone()

nexaql/adapters/postgresql.py

@@ -0,0 +1,106 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""PostgreSQL adapter — executes NexaQL queries against a PostgreSQL database."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+import asyncpg
+
+from nexaql.adapters.base import AdapterResult, QueryAdapter
+from nexaql.engine.translator import translate
+from nexaql.engine.types import ColumnMeta, QueryAST
+
+# asyncpg OID -> friendly type name (covers the most common types)
+_PG_TYPE_MAP: Dict[int, str] = {
+    16: "boolean",
+    20: "integer",
+    21: "integer",
+    23: "integer",
+    25: "string",
+    700: "numeric",
+    701: "numeric",
+    1042: "string",
+    1043: "string",
+    1082: "date",
+    1114: "date",
+    1184: "date",
+    1700: "numeric",
+}
+
+
+def _pg_oid_to_type(oid: int) -> str:
+    return _PG_TYPE_MAP.get(oid, "string")
+
+
+class PostgreSQLAdapter(QueryAdapter):
+    """Async adapter backed by an ``asyncpg`` connection pool."""
+
+    def __init__(self, connection_url: str) -> None:
+        self._url = connection_url
+        self._pool: Optional[asyncpg.Pool] = None
+        self._lock = asyncio.Lock()
+
+    # -- pool management -------------------------------------------------------
+
+    async def _get_pool(self) -> asyncpg.Pool:
+        if self._pool is None or self._pool._closed:
+            async with self._lock:
+                if self._pool is None or self._pool._closed:
+                    self._pool = await asyncpg.create_pool(self._url, min_size=1, max_size=5)
+        return self._pool
+
+    async def close(self) -> None:
+        if self._pool is not None and not self._pool._closed:
+            await self._pool.close()
+            self._pool = None
+
+    # -- QueryAdapter interface ------------------------------------------------
+
+    @property
+    def adapter_type(self) -> str:
+        return "postgresql"
+
+    def describe(self, ast: QueryAST, ontology: Any) -> str:
+        result = translate(ast, ontology)
+        return result.sql
+
+    async def execute(self, ast: QueryAST, ontology: Any) -> AdapterResult:
+        result = translate(ast, ontology)
+        sql = result.sql
+
+        pool = await self._get_pool()
+        async with pool.acquire() as conn:
+            stmt = await conn.prepare(sql)
+            records = await stmt.fetch()
+
+            # Infer column metadata from the prepared statement attributes
+            columns: List[ColumnMeta] = []
+            for attr in stmt.get_attributes():
+                columns.append(
+                    ColumnMeta(
+                        name=attr.name,
+                        type=_pg_oid_to_type(attr.type.oid),
+                    )
+                )
+
+            rows: List[Dict[str, Any]] = [dict(r) for r in records]
+
+        return AdapterResult(
+            rows=rows,
+            columns=columns,
+            row_count=len(rows),
+            shape=result.shape,
+            query_preview=sql,
+            adapter_type=self.adapter_type,
+        )
+
+    async def healthcheck(self) -> bool:
+        try:
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                await conn.fetchval("SELECT 1")
+            return True
+        except Exception:
+            return False

nexaql/api/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""NexaQL FastAPI application package."""

nexaql/api/app.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""FastAPI application factory for NexaQL."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from nexaql.api.deps import get_config
+from nexaql.api.routes import chat, execute, ontology, suggest, validate
+
+
+def create_app() -> FastAPI:
+    """Build and return the FastAPI application instance."""
+    cfg = get_config()
+
+    app = FastAPI(
+        title="NexaQL",
+        description="A GraphQL-inspired query language for any structured data",
+        version="0.1.0",
+    )
+
+    # ── CORS ────────────────────────────────────────────────────────────────
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cfg.server.cors_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # ── API routes ──────────────────────────────────────────────────────────
+    app.include_router(execute.router, prefix="/api")
+    app.include_router(validate.router, prefix="/api")
+    app.include_router(ontology.router, prefix="/api")
+    app.include_router(suggest.router, prefix="/api")
+    app.include_router(chat.router, prefix="/api")
+
+    # ── Health check ────────────────────────────────────────────────────────
+    @app.get("/api/health")
+    async def health() -> JSONResponse:
+        return JSONResponse({"status": "ok"})
+
+    # ── Serve frontend static files ───────────────────────────────────────
+    # Check bundled static dir first (pip install), then local frontend/dist (dev)
+    bundled_static = Path(__file__).parent.parent / "static"
+    local_dist = Path(os.getcwd()) / "frontend" / "dist"
+
+    static_dir = bundled_static if bundled_static.is_dir() else local_dist
+    if static_dir.is_dir():
+        app.mount("/", StaticFiles(directory=str(static_dir), html=True), name="frontend")
+
+    return app

nexaql/api/deps.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""FastAPI dependencies for NexaQL API routes."""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from typing import Any
+
+from nexaql.adapters import get_adapter as _get_adapter
+from nexaql.adapters.base import QueryAdapter
+from nexaql.config import NexaQLConfig, load_config
+from nexaql.ontology import Ontology, load_ontology
+
+
+# ── Cached config loader ────────────────────────────────────────────────────
+
+
+@lru_cache(maxsize=1)
+def get_config() -> NexaQLConfig:
+    """Load and cache the ``nexaql.yaml`` configuration.
+
+    The config path is resolved from the ``NEXAQL_CONFIG`` environment
+    variable, falling back to ``nexaql.yaml`` in the current directory.
+    """
+    path = os.environ.get("NEXAQL_CONFIG", "nexaql.yaml")
+    return load_config(path)
+
+
+# ── Cached ontology loader ──────────────────────────────────────────────────
+
+
+def get_ontology() -> Ontology:
+    """Load the ontology specified in the config.
+
+    Uses the file-mtime cache built into :func:`nexaql.ontology.load_ontology`
+    so the ontology is automatically reloaded when the YAML file changes.
+    """
+    cfg = get_config()
+    return load_ontology(cfg.ontology.path)
+
+
+# ── Adapter factory ─────────────────────────────────────────────────────────
+
+
+_adapter_cache: dict[str, QueryAdapter] = {}
+
+
+def get_adapter_for_datasource(datasource_name: str | None = None) -> QueryAdapter:
+    """Get or create a :class:`QueryAdapter` from the config's datasource entry.
+
+    Adapters are cached so in-memory DuckDB databases retain seeded data.
+    If *datasource_name* is ``None`` the first datasource in the config is used.
+    """
+    cfg = get_config()
+
+    if not cfg.datasources:
+        raise ValueError("No datasources configured in nexaql.yaml")
+
+    if datasource_name is None:
+        datasource_name = next(iter(cfg.datasources))
+
+    if datasource_name in _adapter_cache:
+        return _adapter_cache[datasource_name]
+
+    ds_entry = cfg.datasources.get(datasource_name)
+    if ds_entry is None:
+        available = ", ".join(cfg.datasources.keys())
+        raise ValueError(
+            f"Datasource '{datasource_name}' not found. Available: {available}"
+        )
+
+    adapter = _get_adapter(ds_entry)
+    _adapter_cache[datasource_name] = adapter
+    return adapter

nexaql/api/middleware.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""FastAPI dependency that extracts UserContext from the request."""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from fastapi import Request
+
+from nexaql.policy.context import ANONYMOUS, UserContext
+
+logger = logging.getLogger(__name__)
+
+
+async def get_user_context(request: Request) -> UserContext:
+    """Extract a :class:`UserContext` from the incoming request.
+
+    Dev mode (default):
+    - Check the ``X-User-Context`` header.  If present, parse it as JSON
+      into a :class:`UserContext`.
+    - If the header is absent, return :data:`ANONYMOUS` (full access,
+      ``roles=["*"]``).
+
+    Malformed JSON is handled gracefully: a warning is logged and
+    :data:`ANONYMOUS` is returned so the request is not blocked by a
+    bad header.
+    """
+    header_value = request.headers.get("X-User-Context")
+    if not header_value:
+        return ANONYMOUS
+
+    try:
+        data = json.loads(header_value)
+        return UserContext(
+            user_id=data.get("user_id", "anonymous"),
+            roles=data.get("roles", []),
+            attributes=data.get("attributes", {}),
+        )
+    except (json.JSONDecodeError, TypeError, KeyError) as exc:
+        logger.warning(
+            "Malformed X-User-Context header, falling back to ANONYMOUS: %s", exc
+        )
+        return ANONYMOUS

nexaql/api/routes/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""NexaQL API route modules."""

nexaql/api/routes/chat.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2026-present NexaQL Contributors
+"""POST /api/chat -- NL -> NexaQL -> execute -> summarize pipeline."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from nexaql.adapters import get_adapter
+from nexaql.api.deps import get_config, get_ontology
+from nexaql.chat.agent import ChatResponse, ask
+
+router = APIRouter()
+
+
+class ChatMessage(BaseModel):
+    role: str  # "user" | "assistant"
+    content: str
+
+
+class ChatRequest(BaseModel):
+    question: str
+    history: list[ChatMessage] = []
+
+
+class ChatResponseBody(BaseModel):
+    explanation: str | None = None
+    nexaqlQuery: str | None = None
+    queryPreview: str | None = None
+    adapterType: str | None = None
+    rows: list[dict[str, Any]] = []
+    columns: list[dict[str, str]] = []
+    rowCount: int = 0
+    shape: Any | None = None
+    summary: str | None = None
+    error: str | None = None
+
+
+@router.post("/chat")
+async def chat_endpoint(body: ChatRequest) -> ChatResponseBody:
+    if not body.question.strip():
+        raise HTTPException(status_code=400, detail="Question is required")
+
+    cfg = get_config()
+
+    # Check LLM API key before doing anything
+    if not cfg.llm.api_key:
+        return ChatResponseBody(
+            error=(
+                "Agent Chat requires an LLM API key. "
+                "Set ANTHROPIC_API_KEY in your environment, or add it to nexaql.yaml under llm.api_key."
+            ),
+        )
+
+    ontology = get_ontology()
+
+    # Resolve the default adapter
+    try:
+        if cfg.datasources:
+            adapter = get_adapter(next(iter(cfg.datasources.values())))
+        else:
+            adapter = None
+    except Exception:
+        adapter = None
+
+    history = [{"role": m.role, "content": m.content} for m in body.history]
+
+    try:
+        result: ChatResponse = await ask(
+            question=body.question,
+            history=history,
+            ontology=ontology,
+            adapter=adapter,
+            llm_config=cfg.llm,
+        )
+    except Exception as e:
+        return ChatResponseBody(error=str(e))
+
+    return ChatResponseBody(
+        explanation=result.explanation,
+        nexaqlQuery=result.nexaql_query,
+        queryPreview=result.query_preview,
+        adapterType=result.adapter_type,
+        rows=result.rows,
+        columns=[{"name": c.name, "type": c.type} for c in result.columns] if result.columns else [],
+        rowCount=result.row_count,
+        shape=result.shape,
+        summary=result.summary,
+        error=result.error,
+    )