schema-search 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

schema_search/mcp_server.py

@@ -16,7 +16,6 @@ mcp = FastMCP("schema-search")
 @mcp.tool()
 def schema_search(
     query: str,
-    hops: Optional[int] = None,
     limit: int = 5,
 ) -> dict:
     """Search database schema using natural language.
@@ -25,14 +24,14 @@ def schema_search(
     using semantic similarity. Expands results by traversing foreign key relationships.
 
     Args:
-        query: Natural language question about database schema (e.g., 'where are user refunds stored?', 'tables related to payments')
-        hops: Number of foreign key relationship hops for graph expansion. Use 0 for exact matches only, 1-2 to include related tables. If not specified, uses value from config.yml (default: 1)
-        limit: Maximum number of table schemas to return in results. Default: 5
+        query: Natural language question about database schema (e.g., 'tables related to payments')
+        limit: Maximum number of table schemas to return in results. Default: 5; Max: 10.
 
     Returns:
         Dictionary with 'results' (list of table schemas with columns, types, constraints, and relationships) and 'latency_sec' (query execution time)
     """
-    search_result = mcp.search_engine.search(query, hops=hops, limit=limit)  # type: ignore
+    limit = min(limit, 10)
+    search_result = mcp.search_engine.search(query, limit=limit)  # type: ignore
     return {
         "results": search_result["results"],
         "latency_sec": search_result["latency_sec"],

{schema_search-0.1.5.dist-info → schema_search-0.1.7.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: schema-search
-Version: 0.1.5
-Summary: Natural language search for database schemas with graph-aware semantic retrieval
-Home-page: https://github.com/neehan/schema-search
-Author: 
+Version: 0.1.7
+Summary: Natural language database schema search with graph-aware semantic retrieval
+Home-page: https://adibhasan.com/blog/schema-search/
+Author: Adib Hasan
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -38,6 +38,7 @@ Requires-Dist: snowflake-sqlalchemy>=1.4.0; extra == "snowflake"
 Requires-Dist: snowflake-connector-python>=3.0.0; extra == "snowflake"
 Provides-Extra: bigquery
 Requires-Dist: sqlalchemy-bigquery>=1.6.0; extra == "bigquery"
+Dynamic: author
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
@@ -82,6 +83,48 @@ uv pip install "schema-search[snowflake,mcp]"  # Snowflake
 uv pip install "schema-search[bigquery,mcp]"   # BigQuery
 ```
 
+## Configuration
+
+Edit [`config.yml`](https://github.com/Neehan/schema-search/blob/main/config.yml):
+
+```yaml
+logging:
+  level: "WARNING"
+
+embedding:
+  location: "memory" # Options: "memory", "vectordb" (coming soon)
+  model: "multi-qa-MiniLM-L6-cos-v1"
+  metric: "cosine" # Options: "cosine", "euclidean", "manhattan", "dot"
+  batch_size: 32
+  show_progress: false
+  cache_dir: "/tmp/.schema_search_cache"
+
+chunking:
+  strategy: "raw" # Options: "raw", "llm"
+  max_tokens: 256
+  overlap_tokens: 50
+  model: "gpt-4o-mini"
+
+search:
+  # Search strategy: "semantic" (embeddings), "bm25" (BM25 lexical), "fuzzy" (fuzzy string matching), "hybrid" (semantic + bm25)
+  strategy: "hybrid"
+  initial_top_k: 20
+  rerank_top_k: 5
+  semantic_weight: 0.67 # For hybrid search (bm25_weight = 1 - semantic_weight)
+  hops: 1 # Number of foreign key hops for graph expansion (0-2 recommended)
+
+reranker:
+  # CrossEncoder model for reranking. Set to null to disable reranking
+  model: null # "Alibaba-NLP/gte-reranker-modernbert-base"
+
+schema:
+  include_columns: true
+  include_indices: true
+  include_foreign_keys: true
+  include_constraints: true
+```
+
+
 ## MCP Server
 
 Integrate with Claude Desktop or any MCP client.
@@ -96,7 +139,13 @@ Add to your MCP config (e.g., `~/.cursor/mcp.json` or Claude Desktop config):
   "mcpServers": {
     "schema-search": {
       "command": "uvx",
-      "args": ["schema-search[postgres,mcp]", "postgresql://user:pass@localhost/db", "optional config.yml path", "optional llm_api_key", "optional llm_base_url"]
+      "args": [
+        "schema-search[postgres,mcp]", 
+        "postgresql://user:pass@localhost/db", 
+        "optional/path/to/config.yml", 
+        "optional llm_api_key", 
+        "optional llm_base_url"
+      ]
     }
   }
 }
@@ -107,8 +156,14 @@ Add to your MCP config (e.g., `~/.cursor/mcp.json` or Claude Desktop config):
 {
   "mcpServers": {
     "schema-search": {
-      "command": "path/to/schema-search", // conda: /Users/<username>/opt/miniconda3/envs/<your env>/bin/schema-search",
-      "args": ["postgresql://user:pass@localhost/db", "optional config.yml path", "optional llm_api_key", "optional llm_base_url"]
+      // conda: /Users/<username>/opt/miniconda3/envs/<your env>/bin/schema-search",
+      "command": "path/to/schema-search",
+      "args": [
+        "postgresql://user:pass@localhost/db", 
+        "optional/path/to/config.yml", 
+        "optional llm_api_key", 
+        "optional llm_base_url"
+      ]
     }
   }
 }
@@ -120,7 +175,7 @@ The LLM API key and base url are only required if you use LLM-generated schema s
 ### CLI Usage
 
 ```bash
-schema-search "postgresql://user:pass@localhost/db"
+schema-search "postgresql://user:pass@localhost/db" "optional/path/to/config.yml"
 ```
 
 Optional args: `[config_path] [llm_api_key] [llm_base_url]`
@@ -151,47 +206,6 @@ results = search.search("user_table", hops=0, limit=5, search_type="semantic")
 
 `SchemaSearch.index()` automatically detects schema changes and refreshes cached metadata, so you rarely need to force a reindex manually.
 
-## Configuration
-
-Edit `[config.yml](config.yml)`:
-
-```yaml
-logging:
-  level: "WARNING"
-
-embedding:
-  location: "memory" # Options: "memory", "vectordb" (coming soon)
-  model: "multi-qa-MiniLM-L6-cos-v1"
-  metric: "cosine" # Options: "cosine", "euclidean", "manhattan", "dot"
-  batch_size: 32
-  show_progress: false
-  cache_dir: "/tmp/.schema_search_cache"
-
-chunking:
-  strategy: "raw" # Options: "raw", "llm"
-  max_tokens: 256
-  overlap_tokens: 50
-  model: "gpt-4o-mini"
-
-search:
-  # Search strategy: "semantic" (embeddings), "bm25" (BM25 lexical), "fuzzy" (fuzzy string matching), "hybrid" (semantic + bm25)
-  strategy: "hybrid"
-  initial_top_k: 20
-  rerank_top_k: 5
-  semantic_weight: 0.67 # For hybrid search (bm25_weight = 1 - semantic_weight)
-  hops: 1 # Number of foreign key hops for graph expansion (0-2 recommended)
-
-reranker:
-  # CrossEncoder model for reranking. Set to null to disable reranking
-  model: null # "Alibaba-NLP/gte-reranker-modernbert-base"
-
-schema:
-  include_columns: true
-  include_indices: true
-  include_foreign_keys: true
-  include_constraints: true
-```
-
 ## Search Strategies
 
 Schema Search supports four search strategies:
@@ -199,7 +213,7 @@ Schema Search supports four search strategies:
 - **semantic**: Embedding-based similarity search using sentence transformers
 - **bm25**: Lexical search using BM25 ranking algorithm
 - **fuzzy**: String matching on table/column names using fuzzy matching
-- **hybrid**: Combines semantic and bm25 scores (default: 67% semantic, 33% fuzzy)
+- **hybrid**: Combines semantic and bm25 scores (default: 67% semantic, 33% bm25)
 
 Each strategy performs its own initial ranking, then optionally applies CrossEncoder reranking if `reranker.model` is configured. Set `reranker.model` to `null` to disable reranking.
 
@@ -209,14 +223,14 @@ We [benchmarked](/tests/test_spider_eval.py) on the Spider dataset (1,234 train
 **Memory:** The embedding model requires ~90 MB and the optional reranker adds ~155 MB. Actual process memory depends on your Python runtime.
 
 ### Without Reranker (`reranker.model: null`)
-![Without Reranker](img/spider_benchmark_without_reranker.png)
+![Without Reranker](https://raw.githubusercontent.com/Neehan/schema-search/refs/heads/main/img/spider_benchmark_without_reranker.png)
 - **Indexing:** 0.22s ± 0.08s per database (18 total).
 - **Accuracy:** Hybrid leads with Recall@1 62% / MRR 0.93; Semantic follows at Recall@1 58% / MRR 0.89.
 - **Latency:** BM25 and Fuzzy return in ~5ms; Semantic spends ~15ms; Hybrid (semantic + fuzzy) averages 52ms.
 - **Fuzzy baseline:** Recall@1 22%, highlighting the need for semantic signals on natural-language queries.
 
 ### With Reranker (`Alibaba-NLP/gte-reranker-modernbert-base`)
-![With Reranker](img/spider_benchmark_with_reranker.png)
+![With Reranker](https://raw.githubusercontent.com/Neehan/schema-search/refs/heads/main/img/spider_benchmark_with_reranker.png)
 - **Indexing:** 0.25s ± 0.05s per database (same 18 DBs).
 - **Accuracy:** All strategies converge around Recall@1 62% and MRR ≈ 0.92; Fuzzy jumps from 51% → 92% MRR.
 - **Latency trade-off:** Extra CrossEncoder pass lifts per-query latency to ~0.18–0.29s depending on strategy.
@@ -266,7 +280,7 @@ search = SchemaSearch(
 5. **Optional reranking** with CrossEncoder to refine results
 6. Return top tables with full schema and relationships
 
-Cache stored in `.schema_search_cache/` (configurable in `config.yml`)
+Cache stored in `/tmp/.schema_search_cache/` (configurable in `config.yml`)
 
 ## License
 

{schema_search-0.1.5.dist-info → schema_search-0.1.7.dist-info}/RECORD

@@ -1,6 +1,6 @@
 schema_search/__init__.py,sha256=06680k1q7pUf1m-1MNhKJGgHyT2NYiyJTLUIOP74dJY,486
 schema_search/graph_builder.py,sha256=oKiVdVI_EB_ZmnxNiIV7Dt-jyKjV8B1RlbiSWpOSe30,2140
-schema_search/mcp_server.py,sha256=pl5PWdqAbSkEuzoxEVkB_nNMt5A3AonlCV-FbwrdWZ0,2475
+schema_search/mcp_server.py,sha256=uFTGONeQ8Zib9r2zw-YO_uzZgVdIVh-_o8deMmNA2i0,2241
 schema_search/metrics.py,sha256=veyPo23aysiU_1MCwTVbBcVNreZFr_RGJwMCKBq1RAs,913
 schema_search/schema_extractor.py,sha256=tpFF5FNPT694qZNoPZoRBjMSZySDt0CxUU0Ljtno6Z8,4280
 schema_search/schema_search.py,sha256=60Xk8R3K--Sjsg4TUOiciEKqVe-lNns7K7O1iFsoxq0,8845
@@ -26,13 +26,13 @@ schema_search/search/factory.py,sha256=wgcx-xnZ8c7uSvu6oP3Fpoabd2Gl8FyJxn7zu3zZY
 schema_search/search/fuzzy.py,sha256=Urn2GtJ5h6j0R3HsRkrMfQCLSTU8jtGaHdfYXL_Nb3A,1865
 schema_search/search/hybrid.py,sha256=T1O46SLCPgpCOnTw2bznnCWmqP9EUkUBLqu5AeQu7oQ,2864
 schema_search/search/semantic.py,sha256=brw7x2hZMCep6QK7WWMT451RnpVcSMuNIZtp51kC6Bo,1673
-schema_search-0.1.5.dist-info/licenses/LICENSE,sha256=jOHFAJEjJCD7iBjS2dBe73X5IGDJdAWGosGOUxfCHTM,1067
+schema_search-0.1.7.dist-info/licenses/LICENSE,sha256=jOHFAJEjJCD7iBjS2dBe73X5IGDJdAWGosGOUxfCHTM,1067
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/test_integration.py,sha256=8Iiq9NAwAxMoZcnfR19oOcBEGTyIOmt6nSafG6LWpj0,11959
 tests/test_llm_sql_generation.py,sha256=bj6iwTqXfNEvlrSXnbPxbrgEM2nscbrmYHbT-rNBJZ4,11834
 tests/test_spider_eval.py,sha256=xQwrNXpipaDxk-vIKqSy0nOIl-3Nadtof58nZpsAsZA,15333
-schema_search-0.1.5.dist-info/METADATA,sha256=oSfANTlqkUd-yOFntVULaP4y9hHjfqXxO8wiPoZVW4Q,9157
-schema_search-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-schema_search-0.1.5.dist-info/entry_points.txt,sha256=9FAtZWOuIlmRNBPX_v7bn8x_aUcfojAKWU6ruSo48GM,64
-schema_search-0.1.5.dist-info/top_level.txt,sha256=NZTdQFHoJMezNIhtZICGPOuXlCXQkQduQV925Oqf4sk,20
-schema_search-0.1.5.dist-info/RECORD,,
+schema_search-0.1.7.dist-info/METADATA,sha256=rME6mBAfrGDD7hU4ZnSUo3ceKBMSSh22CvIHOD7djyM,9514
+schema_search-0.1.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+schema_search-0.1.7.dist-info/entry_points.txt,sha256=9FAtZWOuIlmRNBPX_v7bn8x_aUcfojAKWU6ruSo48GM,64
+schema_search-0.1.7.dist-info/top_level.txt,sha256=NZTdQFHoJMezNIhtZICGPOuXlCXQkQduQV925Oqf4sk,20
+schema_search-0.1.7.dist-info/RECORD,,