cyphersmith 0.1.0__tar.gz

cyphersmith-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aswin K V
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cyphersmith-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: cyphersmith
+Version: 0.1.0
+Summary: Turn natural language into read-only Cypher, validate it with CyVer, and execute it against Neo4j — powered by LiteLLM.
+Author: Aswin K V
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Aswin-K-V/Neo4j-Cypher-generator
+Project-URL: Repository, https://github.com/Aswin-K-V/Neo4j-Cypher-generator
+Project-URL: Issues, https://github.com/Aswin-K-V/Neo4j-Cypher-generator/issues
+Keywords: neo4j,cypher,llm,natural-language,graph-database,litellm,text-to-cypher
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: neo4j>=5.20
+Requires-Dist: litellm>=1.0
+Requires-Dist: CyVer>=2.0.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# cyphersmith
+
+`cyphersmith` turns natural language into read-only Cypher, validates it with CyVer, executes it against Neo4j, and returns the query plus records.
+
+It uses LiteLLM for provider-neutral model access, so the same package works with OpenAI, Azure OpenAI, Anthropic, Gemini, and all other LiteLLM-supported providers.
+
+## Install
+
+```bash
+pip install cyphersmith
+```
+
+## Python API
+
+```python
+from cyphersmith import CypherGenerator, LLMConfig, Neo4jCredentials
+
+generator = CypherGenerator(
+    neo4j=Neo4jCredentials(
+        uri="bolt://localhost:7687",
+        username="neo4j",
+        password="password",
+        database="neo4j",
+    ),
+    llm=LLMConfig(
+        model="openai/gpt-4o-mini",
+        temperature=0,
+    ),
+    business_context_path="business_context.yaml",
+)
+
+result = generator.ask("show top 10 items by a chosen metric")
+print(result.cypher)
+print(result.records)
+```
+
+## CLI
+
+Interactive setup and question loop:
+
+```bash
+cyphersmith chat --pretty
+```
+
+The interactive command prompts for:
+
+- LLM provider and model
+- API key and any provider-specific endpoint values
+- Neo4j URI, username, password, and database
+- optional business context file path
+
+After setup, keep asking questions at `Question>`. Type `/exit` to stop. Each answer prints the generated Cypher query, records, validation details, attempts, and any error.
+
+One-shot command:
+
+```bash
+cyphersmith ask \
+  --neo4j-uri bolt://localhost:7687 \
+  --neo4j-user neo4j \
+  --neo4j-password password \
+  --neo4j-database neo4j \
+  --model openai/gpt-4o-mini \
+  --business-context business_context.yaml \
+  "show top 10 items by a chosen metric"
+```
+
+The CLI prints live intermediate progress steps to `stderr` (context load, schema fetch, generation attempts, safety checks, validation, and execution) with terminal colors for readability. Final structured output stays on `stdout`.
+
+Use these flags if needed:
+
+- `--no-progress`: disable intermediate step logs
+- `--no-color`: keep progress logs but disable ANSI colors
+
+The final CLI payload includes `cypher`, `records`, `validation`, `attempts`, and `error`.
+
+## Environment Variables
+
+Neo4j values can be passed explicitly or read from:
+
+- `NEO4J_URI`
+- `NEO4J_USER`
+- `NEO4J_PASSWORD`
+- `NEO4J_DATABASE`
+
+LiteLLM credentials should use the environment variables expected by the provider, such as `OPENAI_API_KEY`, `AZURE_API_KEY`, `AZURE_API_BASE`, or provider-specific equivalents.
+
+## Business Context
+
+Pass a `.txt`, `.md`, `.yaml`, `.yml`, or `.json` file through `business_context_path` or `--business-context`. The content is added to the Cypher generation prompt as business context only; it is not treated as a schema source.
+
+## Safety
+
+Generated Cypher is blocked unless it passes both:
+
+- a local read-only keyword/procedure check
+- CyVer syntax, schema, and property validation
+
+The package will not execute generated queries containing obvious write operations such as `CREATE`, `MERGE`, `DELETE`, `SET`, `REMOVE`, or procedures like `CALL db` and `CALL apoc`.
+
+## License
+
+MIT

cyphersmith-0.1.0/README.md

@@ -0,0 +1,102 @@
+# cyphersmith
+
+`cyphersmith` turns natural language into read-only Cypher, validates it with CyVer, executes it against Neo4j, and returns the query plus records.
+
+It uses LiteLLM for provider-neutral model access, so the same package works with OpenAI, Azure OpenAI, Anthropic, Gemini, and all other LiteLLM-supported providers.
+
+## Install
+
+```bash
+pip install cyphersmith
+```
+
+## Python API
+
+```python
+from cyphersmith import CypherGenerator, LLMConfig, Neo4jCredentials
+
+generator = CypherGenerator(
+    neo4j=Neo4jCredentials(
+        uri="bolt://localhost:7687",
+        username="neo4j",
+        password="password",
+        database="neo4j",
+    ),
+    llm=LLMConfig(
+        model="openai/gpt-4o-mini",
+        temperature=0,
+    ),
+    business_context_path="business_context.yaml",
+)
+
+result = generator.ask("show top 10 items by a chosen metric")
+print(result.cypher)
+print(result.records)
+```
+
+## CLI
+
+Interactive setup and question loop:
+
+```bash
+cyphersmith chat --pretty
+```
+
+The interactive command prompts for:
+
+- LLM provider and model
+- API key and any provider-specific endpoint values
+- Neo4j URI, username, password, and database
+- optional business context file path
+
+After setup, keep asking questions at `Question>`. Type `/exit` to stop. Each answer prints the generated Cypher query, records, validation details, attempts, and any error.
+
+One-shot command:
+
+```bash
+cyphersmith ask \
+  --neo4j-uri bolt://localhost:7687 \
+  --neo4j-user neo4j \
+  --neo4j-password password \
+  --neo4j-database neo4j \
+  --model openai/gpt-4o-mini \
+  --business-context business_context.yaml \
+  "show top 10 items by a chosen metric"
+```
+
+The CLI prints live intermediate progress steps to `stderr` (context load, schema fetch, generation attempts, safety checks, validation, and execution) with terminal colors for readability. Final structured output stays on `stdout`.
+
+Use these flags if needed:
+
+- `--no-progress`: disable intermediate step logs
+- `--no-color`: keep progress logs but disable ANSI colors
+
+The final CLI payload includes `cypher`, `records`, `validation`, `attempts`, and `error`.
+
+## Environment Variables
+
+Neo4j values can be passed explicitly or read from:
+
+- `NEO4J_URI`
+- `NEO4J_USER`
+- `NEO4J_PASSWORD`
+- `NEO4J_DATABASE`
+
+LiteLLM credentials should use the environment variables expected by the provider, such as `OPENAI_API_KEY`, `AZURE_API_KEY`, `AZURE_API_BASE`, or provider-specific equivalents.
+
+## Business Context
+
+Pass a `.txt`, `.md`, `.yaml`, `.yml`, or `.json` file through `business_context_path` or `--business-context`. The content is added to the Cypher generation prompt as business context only; it is not treated as a schema source.
+
+## Safety
+
+Generated Cypher is blocked unless it passes both:
+
+- a local read-only keyword/procedure check
+- CyVer syntax, schema, and property validation
+
+The package will not execute generated queries containing obvious write operations such as `CREATE`, `MERGE`, `DELETE`, `SET`, `REMOVE`, or procedures like `CALL db` and `CALL apoc`.
+
+## License
+
+MIT

cyphersmith-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cyphersmith"
+version = "0.1.0"
+description = "Turn natural language into read-only Cypher, validate it with CyVer, and execute it against Neo4j — powered by LiteLLM."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+  { name = "Aswin K V" }
+]
+keywords = ["neo4j", "cypher", "llm", "natural-language", "graph-database", "litellm", "text-to-cypher"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Database",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = [
+  "neo4j>=5.20",
+  "litellm>=1.0",
+  "CyVer>=2.0.0",
+  "pydantic>=2.0",
+  "PyYAML>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Aswin-K-V/Neo4j-Cypher-generator"
+Repository = "https://github.com/Aswin-K-V/Neo4j-Cypher-generator"
+Issues = "https://github.com/Aswin-K-V/Neo4j-Cypher-generator/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8.0",
+]
+
+[project.scripts]
+cyphersmith = "cyphersmith.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

cyphersmith-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cyphersmith-0.1.0/src/cyphersmith/__init__.py

@@ -0,0 +1,16 @@
+"""Public API for the cyphersmith package."""
+
+from .generator import CypherGenerator
+from .models import CypherGenerationResult, LLMConfig, Neo4jCredentials
+from .neo4j_client import Neo4jClient, get_neo4j_client
+from .progress import TerminalProgressReporter
+
+__all__ = [
+    "CypherGenerationResult",
+    "CypherGenerator",
+    "LLMConfig",
+    "Neo4jClient",
+    "Neo4jCredentials",
+    "TerminalProgressReporter",
+    "get_neo4j_client",
+]

cyphersmith-0.1.0/src/cyphersmith/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cyphersmith-0.1.0/src/cyphersmith/cli.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import sys
+from typing import Sequence
+
+from .generator import CypherGenerator
+from .models import LLMConfig, Neo4jCredentials
+from .progress import TerminalProgressReporter
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "ask":
+        return _run_ask(args)
+    if args.command in {"chat", "setup", "interactive"}:
+        return _run_chat(args)
+
+    parser.print_help()
+    return 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cypher-generator",
+        description="Generate, validate, and execute read-only Cypher against Neo4j.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    ask = subparsers.add_parser("ask", help="Ask a natural-language graph question.")
+    ask.add_argument("query", help="Natural-language graph question.")
+    ask.add_argument("--neo4j-uri", dest="neo4j_uri")
+    ask.add_argument("--neo4j-user", dest="neo4j_user")
+    ask.add_argument("--neo4j-password", dest="neo4j_password")
+    ask.add_argument("--neo4j-database", dest="neo4j_database", default=None)
+    ask.add_argument("--model", required=True, help="LiteLLM model name.")
+    ask.add_argument("--temperature", type=float, default=0)
+    ask.add_argument("--timeout", type=float, default=None)
+    ask.add_argument("--api-key", dest="api_key", default=None)
+    ask.add_argument("--api-base", dest="api_base", default=None)
+    ask.add_argument("--api-version", dest="api_version", default=None)
+    ask.add_argument("--business-context", dest="business_context", default=None)
+    ask.add_argument("--max-validation-retries", type=int, default=2)
+    ask.add_argument(
+        "--no-progress",
+        action="store_true",
+        help="Disable intermediate progress output.",
+    )
+    ask.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI colors in progress output.",
+    )
+    ask.add_argument("--pretty", action="store_true", help="Pretty-print JSON output.")
+    ask.set_defaults(command="ask")
+
+    chat = subparsers.add_parser(
+        "chat",
+        aliases=["setup", "interactive"],
+        help="Prompt for setup once, then ask questions in a loop.",
+    )
+    chat.add_argument("--pretty", action="store_true", help="Pretty-print result JSON.")
+    chat.add_argument("--max-validation-retries", type=int, default=2)
+    chat.add_argument(
+        "--no-progress",
+        action="store_true",
+        help="Disable intermediate progress output.",
+    )
+    chat.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI colors in progress output.",
+    )
+    chat.set_defaults(command="chat")
+    return parser
+
+
+def _run_ask(args: argparse.Namespace) -> int:
+    progress_reporter = _build_progress_reporter(args)
+    generator = CypherGenerator(
+        neo4j=Neo4jCredentials(
+            uri=args.neo4j_uri,
+            username=args.neo4j_user,
+            password=args.neo4j_password,
+            database=args.neo4j_database,
+        ),
+        llm=LLMConfig(
+            model=args.model,
+            temperature=args.temperature,
+            timeout=args.timeout,
+            api_key=args.api_key,
+            api_base=args.api_base,
+            api_version=args.api_version,
+        ),
+        business_context_path=args.business_context,
+        max_validation_retries=args.max_validation_retries,
+        progress_reporter=progress_reporter,
+    )
+    result = generator.ask(args.query)
+    payload = result.model_dump(mode="json")
+    print(
+        json.dumps(
+            payload,
+            indent=2 if args.pretty else None,
+            ensure_ascii=False,
+        )
+    )
+    return 1 if result.error else 0
+
+
+def _run_chat(args: argparse.Namespace) -> int:
+    print("Cypher Generator interactive setup")
+    print("Press Enter to accept defaults. Type /exit in the question loop to stop.")
+
+    llm_config = _prompt_llm_config()
+    neo4j_credentials = _prompt_neo4j_credentials()
+    business_context = _prompt_optional(
+        "Business context file path (.txt/.md/.yaml/.json), blank for none",
+        default="",
+    )
+
+    generator = CypherGenerator(
+        neo4j=neo4j_credentials,
+        llm=llm_config,
+        business_context_path=business_context or None,
+        max_validation_retries=args.max_validation_retries,
+        progress_reporter=_build_progress_reporter(args),
+    )
+
+    print("\nSetup complete. Ask a question, or type /exit to quit.")
+    while True:
+        try:
+            question = input("\nQuestion> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+
+        if question.lower() in {"/exit", "/quit", "exit", "quit", "q"}:
+            return 0
+        if not question:
+            continue
+
+        result = generator.ask(question)
+        _print_interactive_result(result, pretty=args.pretty)
+
+
+def _prompt_llm_config() -> LLMConfig:
+    providers = [
+        ("OpenAI", "openai"),
+        ("Azure OpenAI", "azure"),
+        ("Anthropic", "anthropic"),
+        ("Google Gemini", "gemini"),
+        ("Groq", "groq"),
+        ("Custom LiteLLM model string", "custom"),
+    ]
+
+    print("\nLLM provider")
+    for index, (label, _) in enumerate(providers, start=1):
+        print(f"  {index}. {label}")
+
+    provider_index = _prompt_choice("Select provider", default=1, maximum=len(providers))
+    provider = providers[provider_index - 1][1]
+
+    if provider == "openai":
+        model = _prompt_optional("Model", default="openai/gpt-5")
+        api_key = _prompt_secret("OpenAI API key", required=True)
+        return LLMConfig(model=model, api_key=api_key, temperature=0)
+
+    if provider == "azure":
+        deployment = _prompt_required(
+            "Azure deployment name, without azure/ prefix"
+        )
+        api_key = _prompt_secret("Azure OpenAI API key", required=True)
+        api_base = _prompt_required(
+            "Azure API base, e.g. https://your-resource.openai.azure.com"
+        )
+        api_version = _prompt_optional("Azure API version", default="2024-10-21")
+        return LLMConfig(
+            model=f"azure/{deployment}",
+            api_key=api_key,
+            api_base=api_base,
+            api_version=api_version,
+            temperature=0,
+        )
+
+    if provider == "anthropic":
+        model = _prompt_optional(
+            "Model",
+            default="anthropic/claude-3-5-sonnet-latest",
+        )
+        api_key = _prompt_secret("Anthropic API key", required=True)
+        return LLMConfig(model=model, api_key=api_key, temperature=0)
+
+    if provider == "gemini":
+        model = _prompt_optional("Model", default="gemini/gemini-2.5-pro")
+        api_key = _prompt_secret("Gemini API key", required=True)
+        return LLMConfig(model=model, api_key=api_key, temperature=0)
+
+    if provider == "groq":
+        model = _prompt_optional("Model", default="groq/llama-3.3-70b-versatile")
+        api_key = _prompt_secret("Groq API key", required=True)
+        return LLMConfig(model=model, api_key=api_key, temperature=0)
+
+    model = _prompt_required(
+        "LiteLLM model string, e.g. openai/gpt-5 or azure/my-deployment"
+    )
+    api_key = _prompt_secret("API key, blank to use provider environment variables")
+    api_base = _prompt_optional("API base, blank unless provider needs it", default="")
+    api_version = _prompt_optional(
+        "API version, blank unless provider needs it",
+        default="",
+    )
+    return LLMConfig(
+        model=model,
+        api_key=api_key or None,
+        api_base=api_base or None,
+        api_version=api_version or None,
+        temperature=0,
+    )
+
+
+def _prompt_neo4j_credentials() -> Neo4jCredentials:
+    print("\nNeo4j connection")
+    uri = _prompt_optional("Neo4j URI", default="bolt://localhost:7687")
+    username = _prompt_optional("Neo4j username", default="neo4j")
+    password = _prompt_secret("Neo4j password", required=True)
+    database = _prompt_optional("Neo4j database", default="neo4j")
+    return Neo4jCredentials(
+        uri=uri,
+        username=username,
+        password=password,
+        database=database,
+    )
+
+
+def _prompt_choice(prompt: str, *, default: int, maximum: int) -> int:
+    while True:
+        raw = input(f"{prompt} [{default}]: ").strip()
+        if not raw:
+            return default
+        try:
+            value = int(raw)
+        except ValueError:
+            print(f"Enter a number from 1 to {maximum}.", file=sys.stderr)
+            continue
+        if 1 <= value <= maximum:
+            return value
+        print(f"Enter a number from 1 to {maximum}.", file=sys.stderr)
+
+
+def _prompt_optional(prompt: str, *, default: str = "") -> str:
+    suffix = f" [{default}]" if default else ""
+    value = input(f"{prompt}{suffix}: ").strip()
+    return value or default
+
+
+def _prompt_required(prompt: str) -> str:
+    while True:
+        value = input(f"{prompt}: ").strip()
+        if value:
+            return value
+        print("This value is required.", file=sys.stderr)
+
+
+def _prompt_secret(prompt: str, *, required: bool = False) -> str:
+    while True:
+        value = getpass.getpass(f"{prompt}: ").strip()
+        if value or not required:
+            return value
+        print("This value is required.", file=sys.stderr)
+
+
+def _print_interactive_result(result: object, *, pretty: bool) -> None:
+    cypher = getattr(result, "cypher", "") or ""
+    records = getattr(result, "records", []) or []
+    validation = getattr(result, "validation", {}) or {}
+    error = getattr(result, "error", None)
+    attempts = getattr(result, "attempts", 0)
+
+    print("\nCypher:")
+    print(cypher or "(none)")
+
+    print("\nResults:")
+    print(json.dumps(records, indent=2 if pretty else None, ensure_ascii=False))
+
+    print("\nValidation:")
+    print(json.dumps(validation, indent=2 if pretty else None, ensure_ascii=False))
+
+    print(f"\nAttempts: {attempts}")
+    if error:
+        print(f"Error: {error}", file=sys.stderr)
+
+
+def _build_progress_reporter(
+    args: argparse.Namespace,
+) -> TerminalProgressReporter | None:
+    if getattr(args, "no_progress", False):
+        return None
+    return TerminalProgressReporter(use_color=not getattr(args, "no_color", False))