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
