cyphersmith 0.1.0

Turn natural language into read-only Cypher, validate it with CyVer, and execute it against Neo4j — powered by LiteLLM.

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

pip install cyphersmith

Python API

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:

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:

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