nlp2sql 0.2.0rc20__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.
Files changed (210) hide show
  1. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.github/workflows/ci.yml +1 -1
  2. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/CHANGELOG.md +113 -0
  3. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/PKG-INFO +23 -6
  4. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/README.md +19 -2
  5. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docs/API.md +31 -3
  6. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docs/CONFIGURATION.md +106 -1
  7. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/advanced/test_multiple_providers.py +2 -2
  8. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/mcp_server/README.md +29 -3
  9. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/mcp_server/__init__.py +1 -1
  10. nlp2sql-0.2.0rc21/mcp_server/provider.py +78 -0
  11. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/mcp_server/pyproject.toml +4 -3
  12. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/mcp_server/server.py +7 -44
  13. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/pyproject.toml +10 -6
  14. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/__init__.py +59 -22
  15. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/_provider_errors.py +5 -3
  16. nlp2sql-0.2.0rc21/src/nlp2sql/adapters/_provider_validation.py +26 -0
  17. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/anthropic_adapter.py +19 -26
  18. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/gemini_adapter.py +144 -107
  19. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/openai_adapter.py +103 -27
  20. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/openai_embedding_adapter.py +7 -3
  21. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/cli.py +129 -56
  22. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/client.py +30 -13
  23. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/config/settings.py +1 -1
  24. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/provider_config.py +18 -1
  25. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/__init__.py +10 -1
  26. nlp2sql-0.2.0rc21/src/nlp2sql/ports/ai_provider.py +144 -0
  27. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/query_service.py +26 -11
  28. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/conftest.py +23 -1
  29. nlp2sql-0.2.0rc21/tests/fakes/fake_anthropic.py +104 -0
  30. nlp2sql-0.2.0rc21/tests/fakes/fake_gemini.py +134 -0
  31. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/fakes/fake_openai.py +19 -5
  32. nlp2sql-0.2.0rc21/tests/mcp/test_provider_from_environment.py +125 -0
  33. nlp2sql-0.2.0rc21/tests/mcp/test_sdk_bound.py +42 -0
  34. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_cli_against_postgres.py +33 -0
  35. nlp2sql-0.2.0rc21/tests/test_cli_base_url.py +195 -0
  36. nlp2sql-0.2.0rc21/tests/test_cli_query_output.py +48 -0
  37. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_connect_embeddings.py +64 -0
  38. nlp2sql-0.2.0rc21/tests/test_connect_ready_provider.py +67 -0
  39. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_first_run.py +45 -1
  40. nlp2sql-0.2.0rc21/tests/test_llm_validation_contract.py +117 -0
  41. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_model_defaults.py +123 -19
  42. nlp2sql-0.2.0rc21/tests/test_openai_compatible_endpoint.py +222 -0
  43. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_provider_compat_llm.py +124 -34
  44. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_provider_errors.py +93 -46
  45. nlp2sql-0.2.0rc21/tests/test_provider_event_loops.py +82 -0
  46. nlp2sql-0.2.0rc21/tests/test_provider_validation.py +119 -0
  47. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_query_service_contract.py +114 -0
  48. nlp2sql-0.2.0rc21/uv.lock +6428 -0
  49. nlp2sql-0.2.0rc20/src/nlp2sql/ports/ai_provider.py +0 -71
  50. nlp2sql-0.2.0rc20/uv.lock +0 -4433
  51. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.claude/commands/db.md +0 -0
  52. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.claude/commands/quality.md +0 -0
  53. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.claude/commands/test.md +0 -0
  54. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.claude/rules/adapters.md +0 -0
  55. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.claude/rules/architecture.md +0 -0
  56. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.claude/rules/python-style.md +0 -0
  57. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.claude/rules/testing.md +0 -0
  58. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.claude/settings.json +0 -0
  59. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
  60. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  61. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.github/pull_request_template.md +0 -0
  62. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.github/scripts/verify_release_tag.py +0 -0
  63. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.github/workflows/publish-pypi.yml +0 -0
  64. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.github/workflows/publish-testpypi.yml +0 -0
  65. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.gitignore +0 -0
  66. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.mcp.json.example +0 -0
  67. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/.python-version +0 -0
  68. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/CLAUDE.md +0 -0
  69. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/CODE_OF_CONDUCT.md +0 -0
  70. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/CONTRIBUTING.md +0 -0
  71. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/LICENSE +0 -0
  72. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/SECURITY.md +0 -0
  73. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/assets/nlp2sql-hero-dark.svg +0 -0
  74. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/assets/nlp2sql-hero-light.svg +0 -0
  75. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/benchmarks/enterprise_benchmark_results.json +0 -0
  76. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docker/.env.example +0 -0
  77. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docker/README.md +0 -0
  78. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docker/docker-compose.yml +0 -0
  79. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docker/get-db-urls.sh +0 -0
  80. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docker/init-schema.sql +0 -0
  81. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docker/large-schema.sql +0 -0
  82. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docker/localstack-init.sh +0 -0
  83. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docker/test-redshift.sh +0 -0
  84. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docs/ARCHITECTURE.md +0 -0
  85. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docs/ENTERPRISE.md +0 -0
  86. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/docs/Redshift.md +0 -0
  87. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/README.md +0 -0
  88. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/advanced/test_simple_api.py +0 -0
  89. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/database_specific/test_odoo_integration.py +0 -0
  90. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/default_examples.json +0 -0
  91. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/documentation/real_world_example.py +0 -0
  92. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/getting_started/basic_usage.py +0 -0
  93. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/getting_started/simple_demo.py +0 -0
  94. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/getting_started/test_api_setup.py +0 -0
  95. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/schema_management/test_auto_schema.py +0 -0
  96. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/schema_management/test_schema_filters_comprehensive.py +0 -0
  97. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/.dockerignore +0 -0
  98. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/.env.example +0 -0
  99. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/DOCKER_README.md +0 -0
  100. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/DOCKER_SETUP.md +0 -0
  101. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/DOCKER_TESTING_SUMMARY.md +0 -0
  102. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/Dockerfile +0 -0
  103. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/INDEX.md +0 -0
  104. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/README.md +0 -0
  105. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/docker/init-ecommerce-schema.sql +0 -0
  106. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/docker-compose.yml +0 -0
  107. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/main.py +0 -0
  108. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/pyproject.toml +0 -0
  109. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/examples/strands-fastapi-agent/test-docker-endpoints.sh +0 -0
  110. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/install-dev.sh +0 -0
  111. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/mcp_server/example_config.json +0 -0
  112. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/__init__.py +0 -0
  113. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/default_error_classifier.py +0 -0
  114. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/default_repair_policy.py +0 -0
  115. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/dict_semantic_resolver.py +0 -0
  116. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/file_semantic_resolver.py +0 -0
  117. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/local_embedding_adapter.py +0 -0
  118. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/noop_semantic_resolver.py +0 -0
  119. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/noop_semantic_validator.py +0 -0
  120. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/pgvector_example_repository.py +0 -0
  121. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/postgres_repository.py +0 -0
  122. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/redshift_adapter.py +0 -0
  123. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/regex_query_validator.py +0 -0
  124. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/adapters/schema_repository_execution_adapter.py +0 -0
  125. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/config/__init__.py +0 -0
  126. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/__init__.py +0 -0
  127. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/database_prompts.py +0 -0
  128. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/entities.py +0 -0
  129. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/result.py +0 -0
  130. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/runtime.py +0 -0
  131. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/sql_keywords.py +0 -0
  132. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/core/sql_safety.py +0 -0
  133. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/exceptions/__init__.py +0 -0
  134. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/factories/__init__.py +0 -0
  135. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/factories/repository_factory.py +0 -0
  136. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/cache.py +0 -0
  137. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/embedding_provider.py +0 -0
  138. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/error_classifier.py +0 -0
  139. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/example_repository.py +0 -0
  140. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/query_execution.py +0 -0
  141. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/query_optimizer.py +0 -0
  142. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/query_safety.py +0 -0
  143. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/query_validator.py +0 -0
  144. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/repair_policy.py +0 -0
  145. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/schema_repository.py +0 -0
  146. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/schema_strategy.py +0 -0
  147. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/semantic_resolver.py +0 -0
  148. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/ports/semantic_validator.py +0 -0
  149. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/__init__.py +0 -0
  150. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/analyzer.py +0 -0
  151. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/embedding_manager.py +0 -0
  152. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/example_loader.py +0 -0
  153. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/example_store.py +0 -0
  154. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/filters.py +0 -0
  155. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/schema/manager.py +0 -0
  156. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/__init__.py +0 -0
  157. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/example_selection_service.py +0 -0
  158. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/prompt_assembly_service.py +0 -0
  159. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/query_analysis_service.py +0 -0
  160. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/query_repair_service.py +0 -0
  161. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/semantic_resolution_service.py +0 -0
  162. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/semantic_validation_service.py +0 -0
  163. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/services/sql_intent_planning_service.py +0 -0
  164. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/__init__.py +0 -0
  165. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/artifact_loader.py +0 -0
  166. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/helpers.py +0 -0
  167. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/logger.py +0 -0
  168. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/redaction.py +0 -0
  169. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/semantic_prompt.py +0 -0
  170. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/src/nlp2sql/utils/storage.py +0 -0
  171. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/test_tmp/.gitignore +0 -0
  172. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/data/gold_questions.json +0 -0
  173. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/fakes/__init__.py +0 -0
  174. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/mcp/__init__.py +0 -0
  175. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/mcp/test_sql_security.py +0 -0
  176. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_artifact_loader.py +0 -0
  177. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_basic.py +0 -0
  178. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_batch_scoring.py +0 -0
  179. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_cli_cache.py +0 -0
  180. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_cli_inspect.py +0 -0
  181. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_cli_providers.py +0 -0
  182. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_cli_semantic_support.py +0 -0
  183. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_cli_setup.py +0 -0
  184. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_client_hooks.py +0 -0
  185. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_client_stats.py +0 -0
  186. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_column_validation.py +0 -0
  187. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_cost_per_question.py +0 -0
  188. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_database_prompts.py +0 -0
  189. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_dsl_integration.py +0 -0
  190. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_embedding_manager.py +0 -0
  191. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_false_invalid_regression.py +0 -0
  192. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_integration.py +0 -0
  193. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_library_logging.py +0 -0
  194. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_library_output.py +0 -0
  195. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_pgvector_example_repository.py +0 -0
  196. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_postgres_integration.py +0 -0
  197. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_query_result.py +0 -0
  198. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_readonly_connections.py +0 -0
  199. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_readonly_execution_against_postgres.py +0 -0
  200. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_redaction.py +0 -0
  201. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_redshift_integration.py +0 -0
  202. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_refresh_schema.py +0 -0
  203. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_repository_cache.py +0 -0
  204. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_repository_factory.py +0 -0
  205. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_retrieval_pipeline.py +0 -0
  206. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_schema_context_cache.py +0 -0
  207. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_sql_safety.py +0 -0
  208. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_sql_safety_against_postgres.py +0 -0
  209. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_startup.py +0 -0
  210. {nlp2sql-0.2.0rc20 → nlp2sql-0.2.0rc21}/tests/test_version_consistency.py +0 -0
@@ -136,7 +136,7 @@ jobs:
136
136
  run: |
137
137
  python -m venv "$RUNNER_TEMP/clean"
138
138
  "$RUNNER_TEMP/clean/bin/pip" install dist/*.whl
139
- "$RUNNER_TEMP/clean/bin/pip" list | grep -iE "^(openai|anthropic|google-generativeai|pyyaml) "
139
+ "$RUNNER_TEMP/clean/bin/pip" list | grep -iE "^(openai|anthropic|google-genai|pyyaml) "
140
140
 
141
141
  - name: Import the package and run the CLI
142
142
  working-directory: ${{ runner.temp }}
@@ -22,6 +22,119 @@ 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
+
25
138
  ## [0.2.0rc20] - 2026-11-08
26
139
 
27
140
  ### Security
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: nlp2sql
3
- Version: 0.2.0rc20
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-generativeai>=0.8.5
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-generativeai>=0.8.5; extra == 'all-providers'
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-generativeai>=0.8.5; extra == 'gemini'
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
@@ -114,7 +114,7 @@ The library is designed for both simple schemas and large warehouses, but all pu
114
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))
115
115
  - **Few-shot examples**: pass example lists directly or use an example repository implementation
116
116
  - **Large schema support**: FAISS plus TF-IDF hybrid retrieval, schema filters, and disk-backed caches
117
- - **Multiple providers**: OpenAI, Anthropic, and Gemini built in, or your own `AIProviderPort` passed to `QueryGenerationService`
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()`
118
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
119
119
  - **Async by default**: built for services, APIs, notebooks, and workers
120
120
 
@@ -352,10 +352,27 @@ postgresql://testuser:testpass@localhost:5432/testdb
352
352
  |----------|---------------|--------------|------------|----------|
353
353
  | OpenAI | `gpt-5.6-luna` | 1.05M (922K input) | 128K | Fast, low-cost general purpose usage |
354
354
  | Anthropic | `claude-sonnet-5` | 1M | 128K | Larger schemas and long prompts |
355
- | Gemini | `gemini-3.6-flash` | 1M | 64K | High-volume and very large contexts |
355
+ | Gemini | `gemini-3.8-flash` | 1M | 64K | High-volume and very large contexts |
356
356
 
357
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.
358
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
+
359
376
  ## Lower-Level API
360
377
 
361
378
  `connect()` is the recommended path. Lower-level entry points still exist for advanced wiring:
@@ -34,7 +34,7 @@ The library is designed for both simple schemas and large warehouses, but all pu
34
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))
35
35
  - **Few-shot examples**: pass example lists directly or use an example repository implementation
36
36
  - **Large schema support**: FAISS plus TF-IDF hybrid retrieval, schema filters, and disk-backed caches
37
- - **Multiple providers**: OpenAI, Anthropic, and Gemini built in, or your own `AIProviderPort` passed to `QueryGenerationService`
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()`
38
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
39
39
  - **Async by default**: built for services, APIs, notebooks, and workers
40
40
 
@@ -272,10 +272,27 @@ postgresql://testuser:testpass@localhost:5432/testdb
272
272
  |----------|---------------|--------------|------------|----------|
273
273
  | OpenAI | `gpt-5.6-luna` | 1.05M (922K input) | 128K | Fast, low-cost general purpose usage |
274
274
  | Anthropic | `claude-sonnet-5` | 1M | 128K | Larger schemas and long prompts |
275
- | Gemini | `gemini-3.6-flash` | 1M | 64K | High-volume and very large contexts |
275
+ | Gemini | `gemini-3.8-flash` | 1M | 64K | High-volume and very large contexts |
276
276
 
277
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.
278
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
+
279
296
  ## Lower-Level API
280
297
 
281
298
  `connect()` is the recommended path. Lower-level entry points still exist for advanced wiring:
@@ -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` | Provider config, otherwise resolved from environment |
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.6-flash: $0.75 / $3.75")
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.6-flash: 1M tokens")
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
@@ -390,6 +414,8 @@ export ANTHROPIC_API_KEY="sk-ant-..."
390
414
  export GOOGLE_API_KEY="..."
391
415
  ```
392
416
 
417
+ Or point the server at an OpenAI-compatible server with `NLP2SQL_LLM_BASE_URL` (see [AI Provider](#ai-provider)).
418
+
393
419
  ### "Database alias not configured"
394
420
 
395
421
  Add the database URL to your config:
@@ -1,3 +1,3 @@
1
1
  """nlp2sql MCP Server - Expose nlp2sql as MCP tools."""
2
2
 
3
- __version__ = "0.2.0rc20"
3
+ __version__ = "0.2.0rc21"
@@ -0,0 +1,78 @@
1
+ """Which AI provider the MCP server uses, read from the environment.
2
+
3
+ Kept apart from server.py so that it can be imported, and tested, without the MCP SDK.
4
+ """
5
+
6
+ import logging
7
+ import os
8
+
9
+ from nlp2sql import ProviderConfig
10
+
11
+ logger = logging.getLogger(__name__)
12
+
13
+ # An OpenAI-compatible server (Ollama, vLLM, a gateway): its address, the model to ask
14
+ # for, and its key if it has one
15
+ LLM_BASE_URL_ENV = "NLP2SQL_LLM_BASE_URL"
16
+ LLM_MODEL_ENV = "NLP2SQL_LLM_MODEL"
17
+ LLM_API_KEY_ENV = "NLP2SQL_LLM_API_KEY"
18
+
19
+ ENDPOINT_LABEL = "openai-compatible"
20
+
21
+
22
+ def endpoint_config() -> ProviderConfig | None:
23
+ """The OpenAI-compatible endpoint the environment points at, if any.
24
+
25
+ Only ``NLP2SQL_LLM_API_KEY`` is sent to that server: ``OPENAI_API_KEY`` is for OpenAI.
26
+ """
27
+ base_url = os.getenv(LLM_BASE_URL_ENV)
28
+ if not base_url:
29
+ ignored = [name for name in (LLM_MODEL_ENV, LLM_API_KEY_ENV) if os.getenv(name)]
30
+ if ignored:
31
+ logger.warning("%s ignored: they are only read with %s", ", ".join(ignored), LLM_BASE_URL_ENV)
32
+ return None
33
+ return ProviderConfig(
34
+ provider="openai",
35
+ base_url=base_url,
36
+ model=os.getenv(LLM_MODEL_ENV) or None,
37
+ api_key=os.getenv(LLM_API_KEY_ENV) or None,
38
+ )
39
+
40
+
41
+ def provider_config(provider: str | None = None) -> ProviderConfig:
42
+ """The provider of a query service.
43
+
44
+ A named provider uses its API key from the environment. Otherwise the endpoint of
45
+ ``NLP2SQL_LLM_BASE_URL`` when it is set, else the first provider with an API key.
46
+
47
+ Raises:
48
+ ValueError: If the named provider has no API key, or nothing is configured.
49
+ """
50
+ env_vars = ProviderConfig.API_KEY_ENV_VARS
51
+ if provider:
52
+ api_key = os.getenv(env_vars.get(provider, ""))
53
+ if not api_key:
54
+ raise ValueError(f"API key not configured for provider '{provider}'")
55
+ return ProviderConfig(provider=provider, api_key=api_key)
56
+
57
+ endpoint = endpoint_config()
58
+ if endpoint is not None:
59
+ return endpoint
60
+ for name, env_var in env_vars.items():
61
+ api_key = os.getenv(env_var)
62
+ if api_key:
63
+ return ProviderConfig(provider=name, api_key=api_key)
64
+ raise ValueError(
65
+ f"No AI provider configured. Set one of: {', '.join(env_vars.values())}, "
66
+ f"or {LLM_BASE_URL_ENV} for an OpenAI-compatible server"
67
+ )
68
+
69
+
70
+ def provider_label(config: ProviderConfig) -> str:
71
+ """A name for logs and cache metadata. It never holds the endpoint's address or key."""
72
+ return ENDPOINT_LABEL if config.base_url else config.provider
73
+
74
+
75
+ def service_cache_key(database_url: str, config: ProviderConfig, schema_name: str) -> str:
76
+ """One cached service per database, provider (or endpoint and model) and schema."""
77
+ target = f"{config.base_url}:{config.resolved_model}" if config.base_url else config.provider
78
+ return f"service:{database_url}:{target}:{schema_name}"
@@ -1,11 +1,12 @@
1
1
  [project]
2
2
  name = "nlp2sql-mcp"
3
- version = "0.2.0rc20"
3
+ version = "0.2.0rc21"
4
4
  description = "MCP server for nlp2sql - Natural Language to SQL conversion"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
7
7
  dependencies = [
8
- "mcp",
8
+ # server.py uses FastMCP, which mcp 2.x renamed to MCPServer
9
+ "mcp<2",
9
10
  ]
10
11
 
11
12
  [project.optional-dependencies]
@@ -21,4 +22,4 @@ build-backend = "hatchling.build"
21
22
  [tool.mcp]
22
23
  name = "nlp2sql"
23
24
  description = "Convert natural language queries to SQL using multiple AI providers"
24
- version = "0.2.0rc20"
25
+ version = "0.2.0rc21"