talktodb-api-connector 0.1.0__tar.gz

talktodb_api_connector-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+# Build talktodb-api-connector and upload wheel + sdist to PyPI.
+name: Publish talktodb-api-connector
+
+on:
+  push:
+    # branches:
+    #   - main
+    #   - master
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          packages-dir: dist

talktodb_api_connector-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Build outputs
+dist/
+build/
+*.egg-info/
+
+# Bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Local virtual environments
+.venv/
+venv/
+git-personal-config.sh
+# Test / coverage caches (local only)
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.ruff_cache/

talktodb_api_connector-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

talktodb_api_connector-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: talktodb-api-connector
+Version: 0.1.0
+Summary: FastAPI app: configurable SQL backend, read-only mode, access controls
+Author-email: Biman Kumar Das <daskumarbiman2020@gmail.com>
+Requires-Python: >=3.12
+Requires-Dist: asyncpg>=0.32.0
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: typer>=0.28.0
+Requires-Dist: uvicorn>=0.52.4
+Description-Content-Type: text/markdown
+
+# talktodb-api-connector
+
+Runs a small HTTP API on your machine that reads database settings from a local config file and executes SQL you send it. A command-line tool creates and edits that config, starts or stops the API, and on Windows can register the API as a system service. Nothing in the package ships your data off the machine except SQL you choose to run against your own database.
+
+## Install
+
+Install from PyPI with ```pip install talktodb-api-connector```. The talktodb command is added to your PATH.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| talktodb config set | Set one setting using a dotted name and a value (for example database.host and localhost). |
+| talktodb config ls | Show the current config as JSON; the database password is never printed. |
+| talktodb api start | Check config and database driver, print the config, then start the API in a background process and remember its process id. |
+| talktodb api stop | Stop the API using the saved process id. |
+| talktodb service install | Windows only. Register the API as a Windows service using WinSW; the service is not started automatically. |
+| talktodb service remove | Windows only. Unregister that service and remove the WinSW service definition file. |
+
+### Manual run vs Windows service
+
+- **talktodb api start** — Run the API yourself as a background process in your user session.
+- **talktodb service install** — Register the same API with Windows so it can start at boot or from Services; each time the service starts, it reads the config file again from disk.
+
+## Configuration
+
+Settings live in a JSON file in your home directory named .talktodb.config. Use talktodb config set with paths such as server.port or database.host. talktodb config ls shows everything except the database password.
+
+### Server (HTTP API)
+
+- **server.port** — TCP port the API listens on (default 2026).
+- **server.allowed_origins** — Browser Origin values allowed for cross-origin requests (CORS); default empty list. An empty list means browsers on other sites cannot call the API.
+
+The API always binds to 127.0.0.1 on your machine. That address is not stored in the config file.
+
+### Database
+
+- **database.dialect** — Database kind and async driver (see supported values below); default postgresql.
+- **database.host** — Database server hostname or IP; default 127.0.0.1.
+- **database.port** — Database server port; default 5432.
+- **database.username** — Login user name; default empty.
+- **database.password** — Login password; default empty.
+- **database.database** — Database name to connect to; default empty.
+- **database.read_only** — When true, only read-style SQL (SELECT and similar) is allowed; writes are rejected before they run; default false.
+
+#### Supported dialect values
+
+The CLI maps these names to async SQLAlchemy drivers:
+
+- postgresql or postgres
+- mysql or mariadb
+- sqlite
+- mssql or sqlserver
+- oracle
+
+You may also set dialect to a full driver string that already includes a plus sign (for example postgresql+asyncpg). Install the matching Python driver package (such as asyncpg for PostgreSQL) before starting the API.
+
+### Example Commands
+```bash
+talktodb config set database.dialect postgresql
+talktodb config set database.host localhost
+talktodb config set database.port 5432
+talktodb config set database.username <csv_user>
+talktodb config set database.password <password>
+talktodb config set database.database talktodb
+talktodb config set database.read_only false
+talktodb config set server.port 2026
+talktodb config set server.allowed_origins []
+```

talktodb_api_connector-0.1.0/README.md

@@ -0,0 +1,69 @@
+# talktodb-api-connector
+
+Runs a small HTTP API on your machine that reads database settings from a local config file and executes SQL you send it. A command-line tool creates and edits that config, starts or stops the API, and on Windows can register the API as a system service. Nothing in the package ships your data off the machine except SQL you choose to run against your own database.
+
+## Install
+
+Install from PyPI with ```pip install talktodb-api-connector```. The talktodb command is added to your PATH.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| talktodb config set | Set one setting using a dotted name and a value (for example database.host and localhost). |
+| talktodb config ls | Show the current config as JSON; the database password is never printed. |
+| talktodb api start | Check config and database driver, print the config, then start the API in a background process and remember its process id. |
+| talktodb api stop | Stop the API using the saved process id. |
+| talktodb service install | Windows only. Register the API as a Windows service using WinSW; the service is not started automatically. |
+| talktodb service remove | Windows only. Unregister that service and remove the WinSW service definition file. |
+
+### Manual run vs Windows service
+
+- **talktodb api start** — Run the API yourself as a background process in your user session.
+- **talktodb service install** — Register the same API with Windows so it can start at boot or from Services; each time the service starts, it reads the config file again from disk.
+
+## Configuration
+
+Settings live in a JSON file in your home directory named .talktodb.config. Use talktodb config set with paths such as server.port or database.host. talktodb config ls shows everything except the database password.
+
+### Server (HTTP API)
+
+- **server.port** — TCP port the API listens on (default 2026).
+- **server.allowed_origins** — Browser Origin values allowed for cross-origin requests (CORS); default empty list. An empty list means browsers on other sites cannot call the API.
+
+The API always binds to 127.0.0.1 on your machine. That address is not stored in the config file.
+
+### Database
+
+- **database.dialect** — Database kind and async driver (see supported values below); default postgresql.
+- **database.host** — Database server hostname or IP; default 127.0.0.1.
+- **database.port** — Database server port; default 5432.
+- **database.username** — Login user name; default empty.
+- **database.password** — Login password; default empty.
+- **database.database** — Database name to connect to; default empty.
+- **database.read_only** — When true, only read-style SQL (SELECT and similar) is allowed; writes are rejected before they run; default false.
+
+#### Supported dialect values
+
+The CLI maps these names to async SQLAlchemy drivers:
+
+- postgresql or postgres
+- mysql or mariadb
+- sqlite
+- mssql or sqlserver
+- oracle
+
+You may also set dialect to a full driver string that already includes a plus sign (for example postgresql+asyncpg). Install the matching Python driver package (such as asyncpg for PostgreSQL) before starting the API.
+
+### Example Commands
+```bash
+talktodb config set database.dialect postgresql
+talktodb config set database.host localhost
+talktodb config set database.port 5432
+talktodb config set database.username <csv_user>
+talktodb config set database.password <password>
+talktodb config set database.database talktodb
+talktodb config set database.read_only false
+talktodb config set server.port 2026
+talktodb config set server.allowed_origins []
+```

talktodb_api_connector-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "talktodb-api-connector"
+version = "0.1.0"
+description = "FastAPI app: configurable SQL backend, read-only mode, access controls"
+readme = "README.md"
+authors = [
+    { name = "Biman Kumar Das", email = "daskumarbiman2020@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "asyncpg>=0.32.0",
+    "fastapi>=0.141.1",
+    "pydantic>=2.13.4",
+    "sqlalchemy[asyncio]>=2.0",
+    "typer>=0.28.0",
+    "uvicorn>=0.52.4",
+]
+
+[project.scripts]
+talktodb = "talktodb_api_connector.cli.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/talktodb_api_connector"]

talktodb_api_connector-0.1.0/src/talktodb_api_connector/__init__.py

@@ -0,0 +1,5 @@
+"""talktodb-api-connector: configurable SQL API (skeleton)."""
+
+from talktodb_api_connector.api.main import app
+
+__all__ = ["app"]

talktodb_api_connector-0.1.0/src/talktodb_api_connector/api/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP API: FastAPI app, routes, and request/response schemas."""
+
+from talktodb_api_connector.api.main import app
+
+__all__ = ["app"]

talktodb_api_connector-0.1.0/src/talktodb_api_connector/api/main.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import logging
+import sys
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from starlette.middleware.cors import CORSMiddleware
+
+from talktodb_api_connector.api.routes import router as api_router
+from talktodb_api_connector.config import load_settings
+from talktodb_api_connector.database_registry import DatabaseConnectionRegistry
+
+
+def _ensure_app_logging() -> None:
+    """Configure root logging to stderr when nothing else (e.g. uvicorn) configured it."""
+    root = logging.getLogger()
+    if root.handlers:
+        return
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    _ensure_app_logging()
+    settings = load_settings()
+    app.state.settings = settings
+    DatabaseConnectionRegistry.initialize(settings)
+    # CORS ingress: only attach middleware when origins are configured. With an
+    # empty allowlist we skip CORSMiddleware so browsers receive no
+    # Access-Control-Allow-Origin for cross-origin requests (same-origin still works).
+    if settings.server.allowed_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=list(settings.server.allowed_origins),
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+    yield
+    await DatabaseConnectionRegistry.close()
+
+
+app = FastAPI(title="talktodb-api-connector", lifespan=lifespan)
+app.include_router(api_router)
+
+
+@app.get("/")
+def root(request: Request) -> dict[str, str]:
+    """Health-style root endpoint."""
+    settings = request.app.state.settings
+    if settings.server.allowed_origins:
+        cors_note = (
+            f"CORS enabled for {len(settings.server.allowed_origins)} browser origin(s) "
+            "(not database access control)"
+        )
+    else:
+        cors_note = (
+            "CORS off (allowed_origins empty; no CORSMiddleware — "
+            "cross-origin browser requests blocked)"
+        )
+    return {
+        "status": "ok",
+        "message": "talktodb-api-connector",
+        "bind_host": "127.0.0.1",
+        "settings": ("loaded from ~/.talktodb.config (JSON only)"),
+        "cors": cors_note,
+    }

talktodb_api_connector-0.1.0/src/talktodb_api_connector/api/routes.py

@@ -0,0 +1,48 @@
+"""HTTP routes for talktodb-api-connector."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Request
+
+from talktodb_api_connector.api.schemas import (
+    RunDbQueryOutput,
+    RunDbQueryRequest,
+    SettingsPublic,
+)
+from talktodb_api_connector.service import QueryService
+from talktodb_api_connector.unit_of_work import UnitOfWork
+
+router = APIRouter()
+
+
+async def get_unit_of_work():
+    """Request-scoped unit of work: session + repository; closes on exit."""
+    async with UnitOfWork() as uow:
+        yield uow
+
+
+def get_query_service(
+    request: Request,
+    uow: Annotated[UnitOfWork, Depends(get_unit_of_work)],
+) -> QueryService:
+    """Build :class:`QueryService` from app settings and the request-scoped unit of work."""
+    return QueryService(uow, request.app.state.settings)
+
+
+@router.get("/settings", response_model=SettingsPublic)
+async def get_settings(request: Request) -> SettingsPublic:
+    """Return loaded application settings without the database password."""
+    return SettingsPublic.model_validate(
+        request.app.state.settings.model_dump(exclude={"database": {"password": True}})
+    )
+
+
+@router.post("/query", response_model=RunDbQueryOutput)
+async def post_query(
+    body: RunDbQueryRequest,
+    service: Annotated[QueryService, Depends(get_query_service)],
+) -> RunDbQueryOutput:
+    """Execute SQL; delegates to :class:`QueryService`."""
+    return await service.run_query(body.sql, body.params)

talktodb_api_connector-0.1.0/src/talktodb_api_connector/api/schemas.py

@@ -0,0 +1,77 @@
+"""API response models aligned with the agent server tool contracts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ServerConfigPublic(BaseModel):
+    """Server subsection returned by ``GET /settings``."""
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    port: int = Field(default=2026, description="HTTP API bind port (uvicorn; default 2026).")
+    allowed_origins: list[str] = Field(
+        default_factory=list,
+        description="CORS allowlisted browser origins.",
+    )
+
+
+class DatabaseConfigPublic(BaseModel):
+    """Database subsection returned by ``GET /settings`` (password never included)."""
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    dialect: str
+    host: str = Field(default="127.0.0.1", description="Database server hostname (SQLAlchemy URL).")
+    port: int = Field(default=5432, description="Database server port (SQLAlchemy URL).")
+    username: str
+    database: str
+    read_only: bool = Field(default=False, description="When true, only read-style SQL is allowed.")
+
+
+class SettingsPublic(BaseModel):
+    """Configuration returned by ``GET /settings`` (nested shape; database password omitted)."""
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    server: ServerConfigPublic
+    database: DatabaseConfigPublic
+
+
+class RunDbQueryRequest(BaseModel):
+    """Body for ``POST /query`` — raw SQL and optional bind parameters."""
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    sql: str = Field(..., description="SQL statement to execute.")
+    params: dict[str, Any] | None = Field(
+        default=None,
+        description="Optional named parameters for bound placeholders in ``sql``.",
+    )
+
+
+class RunDbQueryOutput(BaseModel):
+    """Structured result for ``run_db_query``-style tooling (matches agent_server shape)."""
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    success: bool = Field(..., description="Whether the query completed successfully.")
+    error: str | None = Field(
+        default=None,
+        description="Error message when ``success`` is false.",
+    )
+    columns: list[str] | None = Field(
+        default=None,
+        description="Column names in order for row-returning queries.",
+    )
+    rows: list[list[Any]] | None = Field(
+        default=None,
+        description="Row values aligned with ``columns`` (list of lists).",
+    )
+    row_count: int | None = Field(
+        default=None,
+        description="Number of rows returned or affected, depending on query type.",
+    )

talktodb_api_connector-0.1.0/src/talktodb_api_connector/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface for talktodb-api-connector."""