nlp2sql 0.2.0rc19__tar.gz → 0.2.0rc21__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.github/workflows/ci.yml +6 -4
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/CHANGELOG.md +143 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/PKG-INFO +24 -6
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/README.md +20 -2
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/SECURITY.md +12 -1
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docs/API.md +31 -3
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docs/CONFIGURATION.md +106 -1
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/advanced/test_multiple_providers.py +2 -2
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/mcp_server/README.md +33 -3
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/mcp_server/__init__.py +1 -1
- nlp2sql-0.2.0rc21/mcp_server/provider.py +78 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/mcp_server/pyproject.toml +4 -3
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/mcp_server/server.py +7 -44
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/pyproject.toml +10 -6
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/__init__.py +59 -22
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/_provider_errors.py +5 -3
- nlp2sql-0.2.0rc21/src/nlp2sql/adapters/_provider_validation.py +26 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/anthropic_adapter.py +19 -26
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/gemini_adapter.py +144 -107
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/openai_adapter.py +103 -27
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/openai_embedding_adapter.py +7 -3
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/postgres_repository.py +9 -8
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/redshift_adapter.py +6 -9
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/cli.py +129 -56
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/client.py +30 -13
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/config/settings.py +1 -1
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/provider_config.py +18 -1
- nlp2sql-0.2.0rc21/src/nlp2sql/core/sql_safety.py +271 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/__init__.py +10 -1
- nlp2sql-0.2.0rc21/src/nlp2sql/ports/ai_provider.py +144 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/query_service.py +26 -11
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/conftest.py +23 -1
- nlp2sql-0.2.0rc21/tests/fakes/fake_anthropic.py +104 -0
- nlp2sql-0.2.0rc21/tests/fakes/fake_gemini.py +134 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/fakes/fake_openai.py +19 -5
- nlp2sql-0.2.0rc21/tests/mcp/test_provider_from_environment.py +125 -0
- nlp2sql-0.2.0rc21/tests/mcp/test_sdk_bound.py +42 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_cli_against_postgres.py +33 -0
- nlp2sql-0.2.0rc21/tests/test_cli_base_url.py +195 -0
- nlp2sql-0.2.0rc21/tests/test_cli_query_output.py +48 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_connect_embeddings.py +64 -0
- nlp2sql-0.2.0rc21/tests/test_connect_ready_provider.py +67 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_first_run.py +45 -1
- nlp2sql-0.2.0rc21/tests/test_llm_validation_contract.py +117 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_model_defaults.py +123 -19
- nlp2sql-0.2.0rc21/tests/test_openai_compatible_endpoint.py +222 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_provider_compat_llm.py +124 -34
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_provider_errors.py +93 -46
- nlp2sql-0.2.0rc21/tests/test_provider_event_loops.py +82 -0
- nlp2sql-0.2.0rc21/tests/test_provider_validation.py +119 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_query_service_contract.py +114 -0
- nlp2sql-0.2.0rc21/tests/test_readonly_connections.py +48 -0
- nlp2sql-0.2.0rc21/tests/test_readonly_execution_against_postgres.py +77 -0
- nlp2sql-0.2.0rc21/tests/test_sql_safety.py +128 -0
- nlp2sql-0.2.0rc21/tests/test_sql_safety_against_postgres.py +91 -0
- nlp2sql-0.2.0rc21/uv.lock +6428 -0
- nlp2sql-0.2.0rc19/src/nlp2sql/core/sql_safety.py +0 -108
- nlp2sql-0.2.0rc19/src/nlp2sql/ports/ai_provider.py +0 -71
- nlp2sql-0.2.0rc19/tests/test_sql_safety.py +0 -40
- nlp2sql-0.2.0rc19/uv.lock +0 -4433
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.claude/commands/db.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.claude/commands/quality.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.claude/commands/test.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.claude/rules/adapters.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.claude/rules/architecture.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.claude/rules/python-style.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.claude/rules/testing.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.claude/settings.json +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.github/pull_request_template.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.github/scripts/verify_release_tag.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.github/workflows/publish-pypi.yml +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.github/workflows/publish-testpypi.yml +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.gitignore +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.mcp.json.example +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/.python-version +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/CLAUDE.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/CODE_OF_CONDUCT.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/CONTRIBUTING.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/LICENSE +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/assets/nlp2sql-hero-dark.svg +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/assets/nlp2sql-hero-light.svg +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/benchmarks/enterprise_benchmark_results.json +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docker/.env.example +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docker/README.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docker/docker-compose.yml +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docker/get-db-urls.sh +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docker/init-schema.sql +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docker/large-schema.sql +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docker/localstack-init.sh +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docker/test-redshift.sh +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docs/ARCHITECTURE.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docs/ENTERPRISE.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/docs/Redshift.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/README.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/advanced/test_simple_api.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/database_specific/test_odoo_integration.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/default_examples.json +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/documentation/real_world_example.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/getting_started/basic_usage.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/getting_started/simple_demo.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/getting_started/test_api_setup.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/schema_management/test_auto_schema.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/schema_management/test_schema_filters_comprehensive.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/.dockerignore +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/.env.example +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/DOCKER_README.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/DOCKER_SETUP.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/DOCKER_TESTING_SUMMARY.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/Dockerfile +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/INDEX.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/README.md +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/docker/init-ecommerce-schema.sql +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/docker-compose.yml +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/main.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/pyproject.toml +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/test-docker-endpoints.sh +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/install-dev.sh +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/mcp_server/example_config.json +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/default_error_classifier.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/default_repair_policy.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/dict_semantic_resolver.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/file_semantic_resolver.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/local_embedding_adapter.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/noop_semantic_resolver.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/noop_semantic_validator.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/pgvector_example_repository.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/regex_query_validator.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/schema_repository_execution_adapter.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/config/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/database_prompts.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/entities.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/result.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/runtime.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/sql_keywords.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/exceptions/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/factories/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/factories/repository_factory.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/cache.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/embedding_provider.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/error_classifier.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/example_repository.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/query_execution.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/query_optimizer.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/query_safety.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/query_validator.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/repair_policy.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/schema_repository.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/schema_strategy.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/semantic_resolver.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/semantic_validator.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/analyzer.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/embedding_manager.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/example_loader.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/example_store.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/filters.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/manager.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/example_selection_service.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/prompt_assembly_service.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/query_analysis_service.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/query_repair_service.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/semantic_resolution_service.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/semantic_validation_service.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/sql_intent_planning_service.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/artifact_loader.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/helpers.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/logger.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/redaction.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/semantic_prompt.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/storage.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/test_tmp/.gitignore +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/data/gold_questions.json +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/fakes/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/mcp/__init__.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/mcp/test_sql_security.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_artifact_loader.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_basic.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_batch_scoring.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_cli_cache.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_cli_inspect.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_cli_providers.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_cli_semantic_support.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_cli_setup.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_client_hooks.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_client_stats.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_column_validation.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_cost_per_question.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_database_prompts.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_dsl_integration.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_embedding_manager.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_false_invalid_regression.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_integration.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_library_logging.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_library_output.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_pgvector_example_repository.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_postgres_integration.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_query_result.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_redaction.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_redshift_integration.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_refresh_schema.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_repository_cache.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_repository_factory.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_retrieval_pipeline.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_schema_context_cache.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_startup.py +0 -0
- {nlp2sql-0.2.0rc19 → nlp2sql-0.2.0rc21}/tests/test_version_consistency.py +0 -0
|
@@ -97,8 +97,10 @@ jobs:
|
|
|
97
97
|
|
|
98
98
|
# README Quick Start per provider, the false-invalid gold set, the cost of one
|
|
99
99
|
# question (LLM calls, tokens, database connections) and what an application gets
|
|
100
|
-
# back (no output, rows, validation reasons),
|
|
101
|
-
# counts, caches),
|
|
100
|
+
# back (no output, rows, validation reasons), the CLI against the database (row
|
|
101
|
+
# counts, caches), SQL that hides code in literals never reaching the database, and
|
|
102
|
+
# the database refusing writes the check misses, with the OpenAI SDK pointed at
|
|
103
|
+
# tests/fakes/fake_openai.py (no keys, no cost).
|
|
102
104
|
- name: First-run regression tests
|
|
103
105
|
env:
|
|
104
106
|
PYTHONPATH: src
|
|
@@ -108,7 +110,7 @@ jobs:
|
|
|
108
110
|
NLP2SQL_TEST_POSTGRES_USER: testuser
|
|
109
111
|
NLP2SQL_TEST_POSTGRES_PASS: testpass
|
|
110
112
|
NLP2SQL_TEST_POSTGRES_DB: testdb
|
|
111
|
-
run: pytest tests/test_first_run.py tests/test_false_invalid_regression.py tests/test_cost_per_question.py tests/test_library_output.py tests/test_cli_against_postgres.py -m integration -q
|
|
113
|
+
run: pytest tests/test_first_run.py tests/test_false_invalid_regression.py tests/test_cost_per_question.py tests/test_library_output.py tests/test_cli_against_postgres.py tests/test_sql_safety_against_postgres.py tests/test_readonly_execution_against_postgres.py -m integration -q
|
|
112
114
|
|
|
113
115
|
# Installs the built wheel the way a user does: fresh environment, no lock
|
|
114
116
|
# file, latest dependency versions. Catches undeclared dependencies (rc13-rc15
|
|
@@ -134,7 +136,7 @@ jobs:
|
|
|
134
136
|
run: |
|
|
135
137
|
python -m venv "$RUNNER_TEMP/clean"
|
|
136
138
|
"$RUNNER_TEMP/clean/bin/pip" install dist/*.whl
|
|
137
|
-
"$RUNNER_TEMP/clean/bin/pip" list | grep -iE "^(openai|anthropic|google-
|
|
139
|
+
"$RUNNER_TEMP/clean/bin/pip" list | grep -iE "^(openai|anthropic|google-genai|pyyaml) "
|
|
138
140
|
|
|
139
141
|
- name: Import the package and run the CLI
|
|
140
142
|
working-directory: ${{ runner.temp }}
|
|
@@ -22,6 +22,149 @@ pre-1.0.
|
|
|
22
22
|
|
|
23
23
|
## [Unreleased]
|
|
24
24
|
|
|
25
|
+
## [0.2.0rc21] - 2026-11-17
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
- `OpenAIAdapter` takes `base_url`, or a ready-made `client`, to use another server that
|
|
29
|
+
speaks the Chat Completions API, such as Ollama, vLLM or a gateway.
|
|
30
|
+
- The OpenAI key of the environment is not sent to that server. Only an `api_key` passed
|
|
31
|
+
together with `base_url` is, and a placeholder when there is none.
|
|
32
|
+
- OpenAI model names keep their request parameters. Any other name is treated as an open
|
|
33
|
+
model and is sent `temperature` and `max_tokens`, the parameters every compatible
|
|
34
|
+
server implements. Pass `reasoning_effort` to say that it is a reasoning model.
|
|
35
|
+
- `client` is the SDK's sync client (`openai.OpenAI`). An `AsyncOpenAI` client is rejected.
|
|
36
|
+
- Token counts use an OpenAI tokenizer, so for other models they are an estimate.
|
|
37
|
+
- `ProviderConfig` takes `base_url`, so `connect()` and `create_ai_provider` reach those
|
|
38
|
+
servers too: `ProviderConfig(provider="openai", base_url="http://localhost:11434/v1",
|
|
39
|
+
model="llama3.2")`. It is only accepted for the `openai` provider.
|
|
40
|
+
- `connect(provider=...)` also takes a ready AI provider, such as `OpenAIAdapter(client=...)`
|
|
41
|
+
or your own `AIProviderPort`. So does the `ai_provider` argument of
|
|
42
|
+
`create_and_initialize_service`, `create_query_service` and `generate_sql_from_db`.
|
|
43
|
+
- With `base_url` or a ready provider, `connect()` does not default to OpenAI embeddings,
|
|
44
|
+
and the chat key is never sent to OpenAI. It uses local embeddings when
|
|
45
|
+
`nlp2sql[embeddings-local]` is installed, and none otherwise.
|
|
46
|
+
- `nlp2sql query`, `nlp2sql providers test` and `nlp2sql benchmark` take `--base-url`, to use
|
|
47
|
+
an OpenAI-compatible server from the CLI: `nlp2sql query ... --base-url
|
|
48
|
+
http://localhost:11434/v1 --model llama3.2`.
|
|
49
|
+
- No key is needed. Only `--api-key` is sent to that server, never `OPENAI_API_KEY`.
|
|
50
|
+
- `providers test --base-url` checks that server with one request, and takes `--model` and
|
|
51
|
+
`--api-key`.
|
|
52
|
+
- `benchmark --base-url` measures that server, alone or next to `--providers`. Its results
|
|
53
|
+
are under `openai-compatible`.
|
|
54
|
+
- The MCP server can use an OpenAI-compatible server. `NLP2SQL_LLM_BASE_URL` selects it,
|
|
55
|
+
`NLP2SQL_LLM_MODEL` is the model to ask for and `NLP2SQL_LLM_API_KEY` its key, if it has
|
|
56
|
+
one. `OPENAI_API_KEY` is not sent there. Before, the MCP server could not choose a model.
|
|
57
|
+
- Docs: [OpenAI-compatible endpoints](https://github.com/luiscarbonel1991/nlp2sql/blob/main/docs/CONFIGURATION.md#openai-compatible-endpoints),
|
|
58
|
+
with an Ollama example and how to set the context size of a local model.
|
|
59
|
+
|
|
60
|
+
### Changed
|
|
61
|
+
- **The Gemini adapter uses the `google-genai` SDK** (`google-genai>=1.51.0`) instead of
|
|
62
|
+
`google-generativeai`, which Google has deprecated. The dependency is still part
|
|
63
|
+
of the core install and of the `gemini` and `all-providers` extras. Installs no longer
|
|
64
|
+
pull `grpcio`, `protobuf` or `google-api-core`. Pip installs `google-genai` 2.33 on
|
|
65
|
+
Python 3.10 and 3.0 or later on Python 3.11 and up.
|
|
66
|
+
- Requests go to the stable `v1` API version on every SDK release. The SDK's own default
|
|
67
|
+
is `v1beta` up to 2.x and `v1` from 3.0.
|
|
68
|
+
- The system prompt is sent as a system instruction, and the answer is requested as JSON
|
|
69
|
+
(`response_mime_type="application/json"`).
|
|
70
|
+
- The adapter still runs requests in a worker thread. The SDK's async client keeps
|
|
71
|
+
connections bound to the event loop that opened them, so one adapter used from two
|
|
72
|
+
`asyncio.run()` calls failed with "Event loop is closed".
|
|
73
|
+
- **The default Gemini model is `gemini-3.8-flash`**, with `thinking_level="low"`. Other
|
|
74
|
+
models keep their own thinking default; `gemini-3.6-flash` and other models can still be
|
|
75
|
+
pinned with `ProviderConfig(model=...)`.
|
|
76
|
+
- **Behavior change:** the Gemini adapter no longer sends `temperature` or `candidate_count`.
|
|
77
|
+
Google deprecated `temperature` for Gemini 3.6 and later (ignored now, an error in future
|
|
78
|
+
models), and `candidate_count` is unsupported since Gemini 3. A `temperature` passed to
|
|
79
|
+
`GeminiAdapter` is kept and logged at INFO, like the Anthropic adapter does.
|
|
80
|
+
- The Gemini adapter estimates prompt tokens locally (about 4 characters per token), like the
|
|
81
|
+
Anthropic adapter. It called the countTokens API before every question, a blocking network
|
|
82
|
+
round trip inside `generate_query`.
|
|
83
|
+
- **Behavior change:** the LLM review of a query (`llm_validation=True`, or `validate()`)
|
|
84
|
+
gives a result with the same keys for every provider: `is_valid`, `errors` and
|
|
85
|
+
`warnings`. With the Anthropic and Gemini adapters the problems were listed under
|
|
86
|
+
`issues`. They are now under `errors`, as with OpenAI and as `docs/API.md` says.
|
|
87
|
+
`AIProviderPort.validate_query` documents this contract, and the service holds every
|
|
88
|
+
provider's answer to it. A custom provider that answers with `issues` keeps working.
|
|
89
|
+
|
|
90
|
+
### Fixed
|
|
91
|
+
- `nlp2sql query` and `nlp2sql benchmark` no longer hand the chat key to the OpenAI embeddings
|
|
92
|
+
of the few-shot examples when the chat provider is not OpenAI. With `--provider anthropic
|
|
93
|
+
--embedding-provider openai` and examples, the Anthropic key was sent to OpenAI as its key.
|
|
94
|
+
Those embeddings now use `OPENAI_API_KEY`.
|
|
95
|
+
- Gemini thinking tokens are counted. `tokens_used` now includes them, and the response
|
|
96
|
+
metadata reports `thinking_tokens`. They are billed as output, but the old adapter counted
|
|
97
|
+
only prompt and answer tokens.
|
|
98
|
+
- Network failures that httpx reports as `ConnectError`, `ReadError` or `RemoteProtocolError`
|
|
99
|
+
are treated as transient and retried. Their class names do not contain "Connection", so
|
|
100
|
+
they ended the question at once. The `google-genai` SDK raises them unwrapped.
|
|
101
|
+
- A Gemini prompt blocked by a safety filter raises `ProviderRequestError` that names the
|
|
102
|
+
block reason, instead of "Gemini returned no response candidates".
|
|
103
|
+
- The OpenAI, OpenAI embedding and Anthropic adapters work when one adapter is used from
|
|
104
|
+
more than one event loop, for example with one `asyncio.run()` per question. With
|
|
105
|
+
`openai` 3.x and `anthropic` 2.x, the SDKs' async clients keep connections bound to the
|
|
106
|
+
event loop that opened them. The OpenAI adapters failed every other call with "Event loop
|
|
107
|
+
is closed". The Anthropic adapter lost one attempt and a retry delay on each new loop, and
|
|
108
|
+
failed when the SDK's retries were off. The adapters now call the SDKs' sync clients in a
|
|
109
|
+
worker thread, like the Gemini adapter. Cancelling a question no longer cancels its HTTP
|
|
110
|
+
request, which runs to the end in the thread. Code that replaced `adapter.client` should
|
|
111
|
+
pass an `openai.OpenAI` or `anthropic.Anthropic` client instead of the async one.
|
|
112
|
+
- An LLM review that could not be done is no longer reported as an approval. When the
|
|
113
|
+
validation call of the Anthropic or Gemini adapter failed (a network error, a rate limit,
|
|
114
|
+
an answer that was not JSON), the result said `is_valid: True`, `nlp2sql query` printed
|
|
115
|
+
"SQL validation: Passed", and in `generate_only` mode the result was cached as valid.
|
|
116
|
+
The result is now `is_valid: False`, with the reason in `errors` and in the new
|
|
117
|
+
`validation["llm_validation_error"]`. The question keeps its SQL.
|
|
118
|
+
- A custom provider that raises from `validate_query` no longer fails the whole question,
|
|
119
|
+
and `validate()` returns the result above instead of raising `ValidationException`.
|
|
120
|
+
- `result.validation["errors"]` no longer raises `KeyError` when the Anthropic or Gemini
|
|
121
|
+
review is on.
|
|
122
|
+
- `nlp2sql query` prints the errors of an invalid query. It printed an empty list unless
|
|
123
|
+
the Anthropic or Gemini review was on, because it read `issues`.
|
|
124
|
+
- An error or warning that the reviewing model writes as an object is reported by its text.
|
|
125
|
+
`"warnings": [{"message": "no LIMIT"}]` came out as the text of a Python dict,
|
|
126
|
+
`"{'message': 'no LIMIT'}"`. Small local models answer this way more often.
|
|
127
|
+
- The three provider adapters answer `validate_query` by the port's contract when they are
|
|
128
|
+
called directly too. The Anthropic and Gemini adapters reported a failed call as valid,
|
|
129
|
+
and treated a JSON answer without `is_valid` as valid. An answer that is not JSON, or has
|
|
130
|
+
no boolean `is_valid`, is now a review that could not be done, and its tokens are still
|
|
131
|
+
counted. `OpenAIAdapter` reports a failed call the same way: `llm_validation_error`, and
|
|
132
|
+
"LLM validation unavailable: ..." in `errors` instead of "Validation failed: ...". The
|
|
133
|
+
Anthropic and Gemini adapters no longer add default `suggestions` and `complexity` keys.
|
|
134
|
+
- The MCP server asks for `mcp<2`. It uses the 1.x API of the `mcp` SDK, and with 2.x, which
|
|
135
|
+
`pip install nlp2sql mcp` installs today, it failed at import with "No module named
|
|
136
|
+
'mcp.server.fastmcp'". The README installs `"mcp<2"` too.
|
|
137
|
+
|
|
138
|
+
## [0.2.0rc20] - 2026-11-08
|
|
139
|
+
|
|
140
|
+
### Security
|
|
141
|
+
- **The read-only check reads literals and comments the way PostgreSQL does.**
|
|
142
|
+
`is_safe_query` removed string literals with a regex that knew only `'...'` and
|
|
143
|
+
`"..."`. A query could hide another statement, or a prohibited function, inside a
|
|
144
|
+
dollar-quoted (`$$...$$`) or `E'...'` literal, and the check passed it: `ask(validate=True)`,
|
|
145
|
+
`execute_query()` and the MCP server's `run_sql` then ran it. The query is now split into
|
|
146
|
+
tokens like PostgreSQL's lexer does, and the checks look only at its code. Affects every
|
|
147
|
+
earlier release.
|
|
148
|
+
- `SELECT ... INTO` is rejected (it creates a table).
|
|
149
|
+
- Prohibited functions are found when quoted (`"pg_sleep"(1)`) or schema-qualified, and
|
|
150
|
+
`query_to_xml`, `query_to_xml_and_xmlschema`, `query_to_xmlschema` and `ts_stat` are
|
|
151
|
+
prohibited: they run SQL given as a string, which the check cannot see into.
|
|
152
|
+
- Rejected because servers read them differently: a string literal whose end depends on
|
|
153
|
+
whether `\` escapes the next character (`'it\'s'`, `'C:\'`; write quotes as `''`),
|
|
154
|
+
nested `/* */` comments and Unicode-escaped identifiers (`U&"..."`). Unterminated
|
|
155
|
+
literals, quoted names and comments are rejected too.
|
|
156
|
+
- A leading comment (`-- top customers` before `SELECT`) is now allowed.
|
|
157
|
+
- `apply_row_limit` added `LIMIT` after a trailing `-- comment`, where it became part of the
|
|
158
|
+
comment, and skipped it when `LIMIT` appeared inside a `$$...$$` literal or a comment. A
|
|
159
|
+
query that ended with a comment returned every row instead of the limit.
|
|
160
|
+
- **Queries run in read-only transactions** on PostgreSQL and Redshift, so the database
|
|
161
|
+
refuses a write that the check misses. Before, a write was undone only because the
|
|
162
|
+
connection closed without a commit: a `COMMIT` inside the query kept what followed it,
|
|
163
|
+
and `nextval()` moved a sequence for good. Every connection now asks for read-only
|
|
164
|
+
transactions, and on PostgreSQL `default_transaction_read_only` is also set for the
|
|
165
|
+
query's session, so a transaction started after a `COMMIT` is read-only too. `SECURITY.md`
|
|
166
|
+
shows how to create a database user that can only read, which is still the strongest guard.
|
|
167
|
+
|
|
25
168
|
## [0.2.0rc19] - 2026-11-05
|
|
26
169
|
|
|
27
170
|
### Added
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: nlp2sql
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.0rc21
|
|
4
4
|
Summary: Enterprise-ready Natural Language to SQL converter with multi-provider support. Built for production scale (1000+ tables) with Clean Architecture.
|
|
5
5
|
Project-URL: Homepage, https://github.com/luiscarbonel1991/nlp2sql
|
|
6
6
|
Project-URL: Bug Tracker, https://github.com/luiscarbonel1991/nlp2sql/issues
|
|
@@ -25,7 +25,7 @@ Requires-Dist: azure-identity>=1.15.0
|
|
|
25
25
|
Requires-Dist: boto3>=1.34.0
|
|
26
26
|
Requires-Dist: click>=8.0.0
|
|
27
27
|
Requires-Dist: faiss-cpu>=1.7.4
|
|
28
|
-
Requires-Dist: google-
|
|
28
|
+
Requires-Dist: google-genai>=1.51.0
|
|
29
29
|
Requires-Dist: greenlet>=3.2.3
|
|
30
30
|
Requires-Dist: httpx>=0.25.0
|
|
31
31
|
Requires-Dist: numpy>=1.24.0
|
|
@@ -47,7 +47,7 @@ Provides-Extra: all-embeddings
|
|
|
47
47
|
Requires-Dist: sentence-transformers>=2.5.0; extra == 'all-embeddings'
|
|
48
48
|
Provides-Extra: all-providers
|
|
49
49
|
Requires-Dist: anthropic>=0.18.0; extra == 'all-providers'
|
|
50
|
-
Requires-Dist: google-
|
|
50
|
+
Requires-Dist: google-genai>=1.51.0; extra == 'all-providers'
|
|
51
51
|
Provides-Extra: anthropic
|
|
52
52
|
Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
|
|
53
53
|
Provides-Extra: dev
|
|
@@ -66,7 +66,7 @@ Provides-Extra: embeddings-local
|
|
|
66
66
|
Requires-Dist: sentence-transformers>=2.5.0; extra == 'embeddings-local'
|
|
67
67
|
Provides-Extra: embeddings-openai
|
|
68
68
|
Provides-Extra: gemini
|
|
69
|
-
Requires-Dist: google-
|
|
69
|
+
Requires-Dist: google-genai>=1.51.0; extra == 'gemini'
|
|
70
70
|
Provides-Extra: mssql
|
|
71
71
|
Requires-Dist: pymssql>=2.2.0; extra == 'mssql'
|
|
72
72
|
Provides-Extra: mysql
|
|
@@ -111,9 +111,10 @@ The library is designed for both simple schemas and large warehouses, but all pu
|
|
|
111
111
|
- **DSL-first API**: `connect()` returns an `NLP2SQL` client with `ask()`, `validate()`, `explain()`, and `suggest()`
|
|
112
112
|
- **Business-aware generation**: optional `SemanticContext` adds canonical tables, metrics, dimensions, rules, and mappings
|
|
113
113
|
- **Execution modes**: generate only, generate plus validate, and generate plus validate plus repair
|
|
114
|
+
- **Read-only execution**: queries pass a safety check and run in read-only transactions; connect with a database user that can only read (see [SECURITY.md](https://github.com/luiscarbonel1991/nlp2sql/blob/main/SECURITY.md#security-best-practices))
|
|
114
115
|
- **Few-shot examples**: pass example lists directly or use an example repository implementation
|
|
115
116
|
- **Large schema support**: FAISS plus TF-IDF hybrid retrieval, schema filters, and disk-backed caches
|
|
116
|
-
- **Multiple providers**: OpenAI, Anthropic, and Gemini built in
|
|
117
|
+
- **Multiple providers**: OpenAI, Anthropic, and Gemini built in; OpenAI-compatible servers such as Ollama and vLLM through `base_url`; or your own `AIProviderPort` passed to `connect()`
|
|
117
118
|
- **Database support**: PostgreSQL and Amazon Redshift built in; register a `SchemaRepositoryPort` implementation with `RepositoryFactory.register()` and pass `database_type=` to `connect()` to add another database
|
|
118
119
|
- **Async by default**: built for services, APIs, notebooks, and workers
|
|
119
120
|
|
|
@@ -351,10 +352,27 @@ postgresql://testuser:testpass@localhost:5432/testdb
|
|
|
351
352
|
|----------|---------------|--------------|------------|----------|
|
|
352
353
|
| OpenAI | `gpt-5.6-luna` | 1.05M (922K input) | 128K | Fast, low-cost general purpose usage |
|
|
353
354
|
| Anthropic | `claude-sonnet-5` | 1M | 128K | Larger schemas and long prompts |
|
|
354
|
-
| Gemini | `gemini-3.
|
|
355
|
+
| Gemini | `gemini-3.8-flash` | 1M | 64K | High-volume and very large contexts |
|
|
355
356
|
|
|
356
357
|
Defaults are pinned snapshot IDs, not floating aliases. Override any of them through `ProviderConfig(model=...)`; for example `gpt-5.6-terra` is the higher-quality OpenAI option.
|
|
357
358
|
|
|
359
|
+
### Local and Self-Hosted Models
|
|
360
|
+
|
|
361
|
+
The OpenAI provider can use any server that speaks OpenAI's Chat Completions API, such as Ollama, vLLM or a gateway. Pass its address as `base_url`:
|
|
362
|
+
|
|
363
|
+
```python
|
|
364
|
+
nlp = await nlp2sql.connect(
|
|
365
|
+
"postgresql://testuser:testpass@localhost:5432/testdb",
|
|
366
|
+
provider=ProviderConfig(
|
|
367
|
+
provider="openai",
|
|
368
|
+
base_url="http://localhost:11434/v1", # a local Ollama
|
|
369
|
+
model="llama3.2",
|
|
370
|
+
),
|
|
371
|
+
)
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
No OpenAI key is needed, and the one in your environment is not sent to that server. See [OpenAI-compatible endpoints](https://github.com/luiscarbonel1991/nlp2sql/blob/main/docs/CONFIGURATION.md#openai-compatible-endpoints) for keys, request parameters, embeddings and the context size of local models.
|
|
375
|
+
|
|
358
376
|
## Lower-Level API
|
|
359
377
|
|
|
360
378
|
`connect()` is the recommended path. Lower-level entry points still exist for advanced wiring:
|
|
@@ -31,9 +31,10 @@ The library is designed for both simple schemas and large warehouses, but all pu
|
|
|
31
31
|
- **DSL-first API**: `connect()` returns an `NLP2SQL` client with `ask()`, `validate()`, `explain()`, and `suggest()`
|
|
32
32
|
- **Business-aware generation**: optional `SemanticContext` adds canonical tables, metrics, dimensions, rules, and mappings
|
|
33
33
|
- **Execution modes**: generate only, generate plus validate, and generate plus validate plus repair
|
|
34
|
+
- **Read-only execution**: queries pass a safety check and run in read-only transactions; connect with a database user that can only read (see [SECURITY.md](https://github.com/luiscarbonel1991/nlp2sql/blob/main/SECURITY.md#security-best-practices))
|
|
34
35
|
- **Few-shot examples**: pass example lists directly or use an example repository implementation
|
|
35
36
|
- **Large schema support**: FAISS plus TF-IDF hybrid retrieval, schema filters, and disk-backed caches
|
|
36
|
-
- **Multiple providers**: OpenAI, Anthropic, and Gemini built in
|
|
37
|
+
- **Multiple providers**: OpenAI, Anthropic, and Gemini built in; OpenAI-compatible servers such as Ollama and vLLM through `base_url`; or your own `AIProviderPort` passed to `connect()`
|
|
37
38
|
- **Database support**: PostgreSQL and Amazon Redshift built in; register a `SchemaRepositoryPort` implementation with `RepositoryFactory.register()` and pass `database_type=` to `connect()` to add another database
|
|
38
39
|
- **Async by default**: built for services, APIs, notebooks, and workers
|
|
39
40
|
|
|
@@ -271,10 +272,27 @@ postgresql://testuser:testpass@localhost:5432/testdb
|
|
|
271
272
|
|----------|---------------|--------------|------------|----------|
|
|
272
273
|
| OpenAI | `gpt-5.6-luna` | 1.05M (922K input) | 128K | Fast, low-cost general purpose usage |
|
|
273
274
|
| Anthropic | `claude-sonnet-5` | 1M | 128K | Larger schemas and long prompts |
|
|
274
|
-
| Gemini | `gemini-3.
|
|
275
|
+
| Gemini | `gemini-3.8-flash` | 1M | 64K | High-volume and very large contexts |
|
|
275
276
|
|
|
276
277
|
Defaults are pinned snapshot IDs, not floating aliases. Override any of them through `ProviderConfig(model=...)`; for example `gpt-5.6-terra` is the higher-quality OpenAI option.
|
|
277
278
|
|
|
279
|
+
### Local and Self-Hosted Models
|
|
280
|
+
|
|
281
|
+
The OpenAI provider can use any server that speaks OpenAI's Chat Completions API, such as Ollama, vLLM or a gateway. Pass its address as `base_url`:
|
|
282
|
+
|
|
283
|
+
```python
|
|
284
|
+
nlp = await nlp2sql.connect(
|
|
285
|
+
"postgresql://testuser:testpass@localhost:5432/testdb",
|
|
286
|
+
provider=ProviderConfig(
|
|
287
|
+
provider="openai",
|
|
288
|
+
base_url="http://localhost:11434/v1", # a local Ollama
|
|
289
|
+
model="llama3.2",
|
|
290
|
+
),
|
|
291
|
+
)
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
No OpenAI key is needed, and the one in your environment is not sent to that server. See [OpenAI-compatible endpoints](https://github.com/luiscarbonel1991/nlp2sql/blob/main/docs/CONFIGURATION.md#openai-compatible-endpoints) for keys, request parameters, embeddings and the context size of local models.
|
|
295
|
+
|
|
278
296
|
## Lower-Level API
|
|
279
297
|
|
|
280
298
|
`connect()` is the recommended path. Lower-level entry points still exist for advanced wiring:
|
|
@@ -58,7 +58,18 @@ Security issues relevant to this project include:
|
|
|
58
58
|
When using nlp2sql in production:
|
|
59
59
|
|
|
60
60
|
1. **Never commit `.env` files** - Use environment variables or secret management
|
|
61
|
-
2. **
|
|
61
|
+
2. **Connect with a database user that can only read** - nlp2sql checks every query it executes and runs it in a read-only transaction, but the database's own permissions are the guarantee that holds if a check is ever bypassed. In PostgreSQL:
|
|
62
|
+
|
|
63
|
+
```sql
|
|
64
|
+
CREATE ROLE nlp2sql_reader LOGIN PASSWORD '...';
|
|
65
|
+
GRANT CONNECT ON DATABASE mydb TO nlp2sql_reader;
|
|
66
|
+
GRANT USAGE ON SCHEMA public TO nlp2sql_reader;
|
|
67
|
+
GRANT SELECT ON ALL TABLES IN SCHEMA public TO nlp2sql_reader;
|
|
68
|
+
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO nlp2sql_reader;
|
|
69
|
+
ALTER ROLE nlp2sql_reader SET default_transaction_read_only = on;
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Do not use a superuser: it can read server files (`pg_read_file`) and end other sessions.
|
|
62
73
|
3. **Enable query validation** to prevent dangerous SQL execution
|
|
63
74
|
4. **Review generated SQL** before executing on sensitive data
|
|
64
75
|
5. **Keep dependencies updated** - Run `uv sync` regularly
|
|
@@ -49,13 +49,13 @@ nlp = await nlp2sql.connect(
|
|
|
49
49
|
| Parameter | Type | Description |
|
|
50
50
|
| ------------------------- | ------------------------------------------- | ------------------------------------------------------------------- |
|
|
51
51
|
| `database_url` | `str` | Database connection URL |
|
|
52
|
-
| `provider` | `ProviderConfig | None`
|
|
52
|
+
| `provider` | `ProviderConfig | AIProviderPort | None` | Provider config or a ready provider, otherwise resolved from environment |
|
|
53
53
|
| `schema` | `str | None` | Schema name, usually `public` for PostgreSQL |
|
|
54
54
|
| `database_type` | `DatabaseType | None` | Optional explicit override |
|
|
55
55
|
| `schema_filters` | `dict | None` | Include or exclude schemas and tables |
|
|
56
56
|
| `examples` | `list[dict] | ExampleRepositoryPort | None` | Few-shot examples or custom repository |
|
|
57
57
|
| `embedding_provider` | `EmbeddingProviderPort | None` | Custom embedding provider instance |
|
|
58
|
-
| `embedding_provider_type` | `str | None` | Auto-create embedding provider, typically `local` or `openai
|
|
58
|
+
| `embedding_provider_type` | `str | None` | Auto-create embedding provider, typically `local` or `openai`. Default: OpenAI embeddings for chat on OpenAI itself, otherwise local embeddings when installed |
|
|
59
59
|
| `hooks` | `ExecutionHooks | None` | Execution, classification, and repair hooks |
|
|
60
60
|
| `semantic_hooks` | `SemanticHooks | None` | Semantic resolver, validator, and optional default semantic context |
|
|
61
61
|
| `semantic_context` | `SemanticContext | dict | None` | Default semantic context applied to future `ask()` calls |
|
|
@@ -108,6 +108,12 @@ config = ProviderConfig(
|
|
|
108
108
|
| `model` | optional explicit model |
|
|
109
109
|
| `temperature` | generation temperature |
|
|
110
110
|
| `max_tokens` | response budget |
|
|
111
|
+
| `base_url` | another server that speaks OpenAI's API, such as Ollama or vLLM; `openai` only |
|
|
112
|
+
|
|
113
|
+
With `base_url`, `api_key` is the key of that server, and the OpenAI key of the environment is
|
|
114
|
+
not sent there. `provider` in `connect()` also takes a ready provider, such as
|
|
115
|
+
`OpenAIAdapter(client=...)`. See
|
|
116
|
+
[OpenAI-compatible endpoints](CONFIGURATION.md#openai-compatible-endpoints).
|
|
111
117
|
|
|
112
118
|
`ProviderConfig.API_KEY_ENV_VARS` maps each provider to the environment variable the CLI
|
|
113
119
|
reads its key from: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and `GOOGLE_API_KEY`.
|
|
@@ -167,7 +173,7 @@ If you do not pass `execution_mode`, the library infers it from `validate` and `
|
|
|
167
173
|
| `generation_time_ms` | `float` | End-to-end generation time |
|
|
168
174
|
| `examples_used` | `int` | Count of selected examples |
|
|
169
175
|
| `metadata` | `dict[str, object]` | Runtime metadata for debugging and integration |
|
|
170
|
-
| `validation` | `dict[str, object]` | The checks behind `is_valid`: `errors`, `warnings`, `column_errors`, `dialect_issues`, `semantic_validation`, `llm_validation` |
|
|
176
|
+
| `validation` | `dict[str, object]` | The checks behind `is_valid`: `errors`, `warnings`, `column_errors`, `dialect_issues`, `semantic_validation`, `llm_validation`, and `llm_validation_error` when the LLM review could not be done |
|
|
171
177
|
| `rows` | `list[dict] | None` | Result rows when the query was executed (`validate=True`) and succeeded; at most 100, values as returned by the database driver |
|
|
172
178
|
| `columns` | `list[str] | None` | Column names of `rows` |
|
|
173
179
|
|
|
@@ -297,6 +303,10 @@ from nlp2sql import ProviderConfig, create_ai_provider
|
|
|
297
303
|
provider = create_ai_provider(ProviderConfig(provider="anthropic", api_key="sk-ant-..."))
|
|
298
304
|
```
|
|
299
305
|
|
|
306
|
+
The `ai_provider` argument of `create_and_initialize_service()`, `create_query_service()` and
|
|
307
|
+
`generate_sql_from_db()` takes a provider name or a ready provider. A ready provider has its
|
|
308
|
+
own key and model, so it cannot be combined with `api_key`, `model` or `provider_config`.
|
|
309
|
+
|
|
300
310
|
`NLP2SQL.get_stats()` returns the provider, its context size and which components are
|
|
301
311
|
enabled. From synchronous code, `nlp.stats` runs it; inside an event loop it raises
|
|
302
312
|
`RuntimeError`, so use `await nlp.get_stats()` there.
|
|
@@ -390,6 +400,8 @@ nlp2sql query \
|
|
|
390
400
|
| `--schema` | Schema name |
|
|
391
401
|
| `--provider` | `openai`, `anthropic`, or `gemini` |
|
|
392
402
|
| `--api-key` | Explicit provider key |
|
|
403
|
+
| `--model` | Model name; the provider's default if omitted |
|
|
404
|
+
| `--base-url` | Another server that speaks the OpenAI API, such as Ollama or vLLM. With it, only `--api-key` is sent as the key |
|
|
393
405
|
| `--embedding-provider` | Example and schema embedding provider |
|
|
394
406
|
| `--schema-filters` | JSON schema filters |
|
|
395
407
|
| `--examples-file` | Load few-shot examples from JSON or YAML |
|
|
@@ -421,6 +433,18 @@ nlp2sql benchmark \
|
|
|
421
433
|
|
|
422
434
|
The benchmark command also accepts examples and semantic context so provider comparisons stay fair.
|
|
423
435
|
|
|
436
|
+
`--base-url`, with `--model` and an optional `--api-key`, measures an OpenAI-compatible
|
|
437
|
+
server. Given alone, that server is the only target, so no hosted provider is called without
|
|
438
|
+
being asked for. With `--providers` it is measured next to them, and its results are under
|
|
439
|
+
`openai-compatible`:
|
|
440
|
+
|
|
441
|
+
```bash
|
|
442
|
+
nlp2sql benchmark \
|
|
443
|
+
--database-url postgresql://testuser:testpass@localhost:5432/testdb \
|
|
444
|
+
--providers openai \
|
|
445
|
+
--base-url http://localhost:11434/v1 --model llama3.2
|
|
446
|
+
```
|
|
447
|
+
|
|
424
448
|
### `nlp2sql inspect`
|
|
425
449
|
|
|
426
450
|
Inspect the schema available to the library:
|
|
@@ -456,9 +480,13 @@ hundred tokens), and print the model, latency and tokens:
|
|
|
456
480
|
```bash
|
|
457
481
|
nlp2sql providers test # every provider with a key set
|
|
458
482
|
nlp2sql providers test --provider gemini
|
|
483
|
+
nlp2sql providers test --base-url http://localhost:11434/v1 --model llama3.2
|
|
459
484
|
nlp2sql validate # providers, plus DATABASE_URL when set
|
|
460
485
|
```
|
|
461
486
|
|
|
487
|
+
With `--base-url`, the check goes to that server only. `--model` and `--api-key` belong to it,
|
|
488
|
+
and `OPENAI_API_KEY` is not sent there.
|
|
489
|
+
|
|
462
490
|
A failure says what to fix (rejected key, unknown model id, rate limit, unreachable
|
|
463
491
|
provider, SDK not installed), and the command exits 1.
|
|
464
492
|
|
|
@@ -15,7 +15,7 @@ Configuration falls into four buckets:
|
|
|
15
15
|
|
|
16
16
|
### Provider Credentials
|
|
17
17
|
|
|
18
|
-
At least one provider key is required.
|
|
18
|
+
At least one provider key is required, unless the model is served by another [OpenAI-compatible endpoint](#openai-compatible-endpoints).
|
|
19
19
|
|
|
20
20
|
| Variable | Description |
|
|
21
21
|
|----------|-------------|
|
|
@@ -79,6 +79,107 @@ export NLP2SQL_EMBEDDING_PROVIDER=local
|
|
|
79
79
|
| `NLP2SQL_ENV` | unset | Optional environment label |
|
|
80
80
|
| `TOKENIZERS_PARALLELISM` | unset | Set to `false` to reduce tokenizer warnings |
|
|
81
81
|
|
|
82
|
+
## OpenAI-Compatible Endpoints
|
|
83
|
+
|
|
84
|
+
The OpenAI provider can use any server that speaks OpenAI's Chat Completions API, such as Ollama, vLLM, LiteLLM or another gateway. Pass the server's address as `base_url`:
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
import nlp2sql
|
|
88
|
+
from nlp2sql import ProviderConfig
|
|
89
|
+
|
|
90
|
+
nlp = await nlp2sql.connect(
|
|
91
|
+
database_url,
|
|
92
|
+
provider=ProviderConfig(
|
|
93
|
+
provider="openai",
|
|
94
|
+
base_url="http://localhost:11434/v1", # a local Ollama
|
|
95
|
+
model="llama3.2",
|
|
96
|
+
),
|
|
97
|
+
)
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
If the server needs a key, pass it as `api_key`. `base_url` is only accepted for the `openai` provider.
|
|
101
|
+
|
|
102
|
+
The notes below were checked against Ollama 0.20.5 with `llama3.2`. Other servers can differ.
|
|
103
|
+
|
|
104
|
+
### CLI
|
|
105
|
+
|
|
106
|
+
`query`, `providers test` and `benchmark` take `--base-url`:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
nlp2sql providers test --base-url http://localhost:11434/v1 --model llama3.2
|
|
110
|
+
|
|
111
|
+
nlp2sql query \
|
|
112
|
+
--database-url "$DATABASE_URL" \
|
|
113
|
+
--question "Count active users by region" \
|
|
114
|
+
--base-url http://localhost:11434/v1 \
|
|
115
|
+
--model llama3.2
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
No key is needed. If the server has one, pass it with `--api-key`: `OPENAI_API_KEY` is not sent there.
|
|
119
|
+
|
|
120
|
+
### MCP Server
|
|
121
|
+
|
|
122
|
+
The MCP server reads the endpoint from its environment:
|
|
123
|
+
|
|
124
|
+
| Variable | Description |
|
|
125
|
+
|----------|-------------|
|
|
126
|
+
| `NLP2SQL_LLM_BASE_URL` | Address of the server. When it is set, the MCP server uses it instead of a hosted provider |
|
|
127
|
+
| `NLP2SQL_LLM_MODEL` | Model to ask for |
|
|
128
|
+
| `NLP2SQL_LLM_API_KEY` | Key of that server, if it has one. `OPENAI_API_KEY` is not sent there |
|
|
129
|
+
|
|
130
|
+
### A Ready Client
|
|
131
|
+
|
|
132
|
+
For anything `ProviderConfig` has no field for, such as timeouts, custom headers or a reasoning model, build the adapter yourself and pass it as the provider:
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
from openai import OpenAI
|
|
136
|
+
|
|
137
|
+
import nlp2sql
|
|
138
|
+
from nlp2sql import OpenAIAdapter
|
|
139
|
+
|
|
140
|
+
client = OpenAI(base_url="https://llm-gateway.example.com/v1", api_key=gateway_key, timeout=120)
|
|
141
|
+
nlp = await nlp2sql.connect(database_url, provider=OpenAIAdapter(client=client, model="my-model"))
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`client` is the SDK's synchronous client, `openai.OpenAI`. An `AsyncOpenAI` client is rejected, because the adapter runs each request in a worker thread.
|
|
145
|
+
|
|
146
|
+
`connect()` takes any `AIProviderPort` implementation this way, not only `OpenAIAdapter`.
|
|
147
|
+
|
|
148
|
+
### What Is Different on Another Endpoint
|
|
149
|
+
|
|
150
|
+
| Topic | Behavior |
|
|
151
|
+
|-------|----------|
|
|
152
|
+
| API key | Only the `api_key` passed with `base_url` is sent to that server. `OPENAI_API_KEY` is never sent there. Without a key, the request carries a placeholder, which servers that take no key ignore. |
|
|
153
|
+
| Request parameters | OpenAI model names keep the parameters they get on OpenAI. Any other name is treated as an open model and is sent `temperature` and `max_tokens`. For a reasoning model with another name, build `OpenAIAdapter(base_url=..., model=..., reasoning_effort="low")`: it is then sent `reasoning_effort` and `max_completion_tokens`. Ollama rejects `reasoning_effort` for a model without thinking, and ignores `max_completion_tokens`. |
|
|
154
|
+
| JSON answers | Requests ask for a JSON object through `response_format`, so the server and the model must support JSON mode. |
|
|
155
|
+
| Embeddings | `connect()` does not send that key to OpenAI. It uses local embeddings when `nlp2sql[embeddings-local]` is installed, and no embeddings otherwise. For OpenAI embeddings next to a local chat model, pass `embedding_provider_type="openai"`, which reads `OPENAI_API_KEY`. |
|
|
156
|
+
| Token counts | Prompts are measured with an OpenAI tokenizer, and a model the library does not know is assumed to have a 128K context window. For other models both are estimates. |
|
|
157
|
+
|
|
158
|
+
### Context Size of Local Models
|
|
159
|
+
|
|
160
|
+
Each question sends up to `NLP2SQL_MAX_SCHEMA_TOKENS` schema tokens (8000 by default), plus the question, the examples and the instructions. The model needs a context window that fits them. If its window is smaller, lower `NLP2SQL_MAX_SCHEMA_TOKENS` or raise the window.
|
|
161
|
+
|
|
162
|
+
A prompt longer than the window is not an error in Ollama. It drops the beginning of the prompt, where the schema is, and answers from the rest. `ollama ps` shows the window a loaded model has.
|
|
163
|
+
|
|
164
|
+
Ollama's OpenAI-compatible API has no parameter for the context size. Set it in a `Modelfile`:
|
|
165
|
+
|
|
166
|
+
```text
|
|
167
|
+
FROM llama3.2
|
|
168
|
+
PARAMETER num_ctx 16384
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Create a model from it, in the folder that holds the `Modelfile`, and use that name as `model`:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
ollama create llama3.2-16k
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### `OPENAI_BASE_URL`
|
|
178
|
+
|
|
179
|
+
The OpenAI SDK also reads `OPENAI_BASE_URL`. It redirects every OpenAI request, chat and embeddings, and `OPENAI_API_KEY` goes with them. Use it for a proxy in front of OpenAI: for `nlp2sql` that is still OpenAI, so models keep OpenAI's request parameters.
|
|
180
|
+
|
|
181
|
+
It is not a way to reach a local model. A name that is not an OpenAI model is sent `reasoning_effort`, and Ollama answers `400 ... does not support thinking` for a model without thinking. Use `base_url` from Python, `--base-url` in the CLI or `NLP2SQL_LLM_BASE_URL` in the MCP server.
|
|
182
|
+
|
|
82
183
|
## Semantic Context Guidance
|
|
83
184
|
|
|
84
185
|
Semantic context is not configured by environment variable. It is passed through the API or CLI and should be chosen intentionally per integration.
|
|
@@ -191,6 +292,10 @@ doubles the latency of each question, and executing the query against the databa
|
|
|
191
292
|
stronger signal. Turn it on with `connect(..., llm_validation=True)`,
|
|
192
293
|
`NLP2SQL_LLM_VALIDATION=true` or `nlp2sql query --llm-validation`.
|
|
193
294
|
|
|
295
|
+
A review that cannot be done is not an approval. If the call fails, or the model's answer
|
|
296
|
+
cannot be read, the result is not valid, `validation["llm_validation_error"]` says why, and
|
|
297
|
+
the question keeps its SQL.
|
|
298
|
+
|
|
194
299
|
### Python
|
|
195
300
|
|
|
196
301
|
```python
|
|
@@ -155,12 +155,12 @@ async def demo_provider_selection():
|
|
|
155
155
|
print("Cost Comparison (approx, per 1M tokens in/out, default models):")
|
|
156
156
|
print(" OpenAI gpt-5.6-luna: $0.20 / $1.20")
|
|
157
157
|
print(" Anthropic claude-sonnet-5: $2 / $10")
|
|
158
|
-
print(" Google gemini-3.
|
|
158
|
+
print(" Google gemini-3.8-flash: $0.75 / $3.75 (through 2026; $1.50 / $7.50 from 2027)")
|
|
159
159
|
print()
|
|
160
160
|
print("Context Limits (default models):")
|
|
161
161
|
print(" OpenAI gpt-5.6-luna: 1.05M tokens (922K input)")
|
|
162
162
|
print(" Anthropic claude-sonnet-5: 1M tokens")
|
|
163
|
-
print(" Google gemini-3.
|
|
163
|
+
print(" Google gemini-3.8-flash: 1M tokens")
|
|
164
164
|
|
|
165
165
|
|
|
166
166
|
if __name__ == "__main__":
|
|
@@ -19,7 +19,7 @@ This MCP server provides **5 simple, idiomatic tools** optimized for BI analysts
|
|
|
19
19
|
- **Natural Language Queries**: Convert questions to SQL using AI
|
|
20
20
|
- **Direct Execution**: Execute queries and get results (read-only, secure)
|
|
21
21
|
- **Schema Discovery**: Explore database structure interactively
|
|
22
|
-
- **Multi-Provider Support**: OpenAI, Anthropic, Google Gemini
|
|
22
|
+
- **Multi-Provider Support**: OpenAI, Anthropic, Google Gemini, or an OpenAI-compatible server such as Ollama
|
|
23
23
|
- **Performance Optimized**: Service caching for fast subsequent calls (~5s vs ~50s)
|
|
24
24
|
- **Security First**: SQL injection protection, read-only enforcement
|
|
25
25
|
|
|
@@ -27,12 +27,14 @@ This MCP server provides **5 simple, idiomatic tools** optimized for BI analysts
|
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
29
|
# Install from PyPI
|
|
30
|
-
pip install nlp2sql mcp
|
|
30
|
+
pip install nlp2sql "mcp<2"
|
|
31
31
|
|
|
32
32
|
# Or with uv
|
|
33
|
-
uv add nlp2sql mcp
|
|
33
|
+
uv add nlp2sql "mcp<2"
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
+
The server uses the 1.x API of the `mcp` SDK. It does not start with `mcp` 2.x.
|
|
37
|
+
|
|
36
38
|
## Configuration
|
|
37
39
|
|
|
38
40
|
### Claude Desktop / Claude Code
|
|
@@ -77,6 +79,28 @@ Configure databases using environment variables for security:
|
|
|
77
79
|
| `test` | `NLP2SQL_TEST_DB_URL` | Test database |
|
|
78
80
|
| `prod` / `production` | `NLP2SQL_PROD_DB_URL` | Production database |
|
|
79
81
|
|
|
82
|
+
### AI Provider
|
|
83
|
+
|
|
84
|
+
The server uses the first provider that has an API key: `OPENAI_API_KEY`, then `ANTHROPIC_API_KEY`, then `GOOGLE_API_KEY`.
|
|
85
|
+
|
|
86
|
+
To use a local or self-hosted model instead, point it at a server that speaks the OpenAI API, such as Ollama or vLLM:
|
|
87
|
+
|
|
88
|
+
| Environment Variable | Meaning |
|
|
89
|
+
|---------------------|---------|
|
|
90
|
+
| `NLP2SQL_LLM_BASE_URL` | Address of the server, for example `http://localhost:11434/v1`. When it is set, the server uses it instead of the providers above |
|
|
91
|
+
| `NLP2SQL_LLM_MODEL` | Model to ask for, for example `llama3.2` |
|
|
92
|
+
| `NLP2SQL_LLM_API_KEY` | Key of that server, if it has one |
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
"env": {
|
|
96
|
+
"NLP2SQL_LLM_BASE_URL": "http://localhost:11434/v1",
|
|
97
|
+
"NLP2SQL_LLM_MODEL": "llama3.2",
|
|
98
|
+
"NLP2SQL_DEFAULT_DB_URL": "postgresql://user:pass@localhost:5432/mydb"
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`OPENAI_API_KEY` is never sent to that server. `NLP2SQL_LLM_MODEL` and `NLP2SQL_LLM_API_KEY` are only read together with `NLP2SQL_LLM_BASE_URL`. See [OpenAI-compatible endpoints](https://github.com/luiscarbonel1991/nlp2sql/blob/main/docs/CONFIGURATION.md#openai-compatible-endpoints) for what differs on such a server, and for the context size of local models.
|
|
103
|
+
|
|
80
104
|
## Tools Reference
|
|
81
105
|
|
|
82
106
|
### 1. `ask_database` - Main Tool
|
|
@@ -367,6 +391,10 @@ All SQL execution goes through security validation:
|
|
|
367
391
|
- `COPY`, `EXEC`, `CALL`
|
|
368
392
|
- Multiple statements (`;` injection)
|
|
369
393
|
|
|
394
|
+
### Read-only Transactions
|
|
395
|
+
|
|
396
|
+
Queries run in read-only transactions (PostgreSQL and Redshift), so the database refuses a write even if the check above missed it. Configure the server with a database user that can only read; see [SECURITY.md](https://github.com/luiscarbonel1991/nlp2sql/blob/main/SECURITY.md#security-best-practices).
|
|
397
|
+
|
|
370
398
|
### Row Limits
|
|
371
399
|
|
|
372
400
|
- Default: 100 rows
|
|
@@ -386,6 +414,8 @@ export ANTHROPIC_API_KEY="sk-ant-..."
|
|
|
386
414
|
export GOOGLE_API_KEY="..."
|
|
387
415
|
```
|
|
388
416
|
|
|
417
|
+
Or point the server at an OpenAI-compatible server with `NLP2SQL_LLM_BASE_URL` (see [AI Provider](#ai-provider)).
|
|
418
|
+
|
|
389
419
|
### "Database alias not configured"
|
|
390
420
|
|
|
391
421
|
Add the database URL to your config:
|