cyphersmith 0.1.0__py3-none-any.whl

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/__main__.py

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

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))

cyphersmith/context.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+
+SUPPORTED_CONTEXT_EXTENSIONS = {".txt", ".md", ".yaml", ".yml", ".json"}
+
+
+def load_business_context(path: str | Path | None) -> str:
+    """Load optional business context from a text, markdown, YAML, or JSON file."""
+    if path is None:
+        return ""
+
+    context_path = Path(path).expanduser()
+    suffix = context_path.suffix.lower()
+    if suffix not in SUPPORTED_CONTEXT_EXTENSIONS:
+        allowed = ", ".join(sorted(SUPPORTED_CONTEXT_EXTENSIONS))
+        raise ValueError(
+            f"Unsupported business context extension '{suffix}'. "
+            f"Expected one of: {allowed}."
+        )
+
+    try:
+        text = context_path.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise FileNotFoundError(f"Business context file not found: {context_path}") from exc
+    except OSError as exc:
+        raise OSError(f"Failed to read business context file {context_path}: {exc}") from exc
+
+    if not text.strip():
+        return ""
+
+    if suffix == ".json":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON business context at {context_path}: {exc}") from exc
+        return json.dumps(data, indent=2, ensure_ascii=False)
+
+    if suffix in {".yaml", ".yml"}:
+        try:
+            data = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise ValueError(f"Invalid YAML business context at {context_path}: {exc}") from exc
+        if data is None:
+            return ""
+        return yaml.safe_dump(
+            data,
+            sort_keys=False,
+            allow_unicode=True,
+            default_flow_style=False,
+        ).strip()
+
+    return text.strip()