Metadata-Version: 2.4
Name: CyVer
Version: 1.3.5
Summary: Cypher queries Validators against a given Knowledge Graph schema, in terms of syntax, schema validity, and property access.
Home-page: https://gitlab.com/netmode/CyVer
Author: ['Ioanna Mandilara', 'Christina Maria Androna']
Author-email: Ioanna Mandilara <ioanna_mandilara@yahoo.gr>, Christina-Maria Androna <androna.xm@gmail.com>
License: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) License
        Copyright (c) 2025 androna-xm
        
        You are free to:
        Share — copy and redistribute the material in any medium or format for any purpose, even commercially.
        Adapt — remix, transform, and build upon the material for any purpose, even commercially.
        The licensor cannot revoke these freedoms as long as you follow the license terms.
        Under the following terms:
        Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
        ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
        No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
Project-URL: Homepage, https://gitlab.com/netmode/CyVer
Project-URL: Documentation, https://gitlab.com/netmode/CyVer/-/wikis/CyVer-Documentation
Project-URL: Changelog, https://gitlab.com/netmode/CyVer/-/blob/main/CHANGELOG.md
Project-URL: Issues, https://gitlab.com/netmode/CyVer/-/issues
Project-URL: Repository, https://gitlab.com/netmode/CyVer
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: regex>=2024.11.6
Requires-Dist: neo4j>=5.27
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# CyVer
[![License](https://img.shields.io/badge/License-CC_BY_SA_4.0-blue.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
<div align="center">
    <img src="https://gitlab.com/netmode/CyVer/-/raw/main/logoCyVer.jpg?ref_type=heads" alt="CyVer" width="300">
</div>


**CyVer** is a Python library designed to validate Cypher queries against a given Knowledge Graph schema in Neo4j. It ensures correctness in terms of syntax, schema validity, and property access. 

## Features

* **Syntax Validation**: Validates Cypher queries for correct syntax and detects conflicting labels in nodes and relationships.

* **Schema Validation**: Checks query alignment with a predefined KG schema structure.

* **Property Validation**: Ensures property accesses are correct based on the predefined KG schema structure.

## 📖 Documentation

For documentation read [Wiki](https://gitlab.com/netmode/CyVer/-/wikis/CyVer-Documentation).

## 📋 Requirements

Before installing, make sure you have the following Python packages installed, with Python version >= 3.10:

* regex>=2024.11.6
* neo4j>=5.27


## 📦 Installation

To install the latest stable version from [PyPI](https://pypi.org/project/CyVer/), run:

```sh
pip install CyVer
```
Alternatively, if you prefer to install the latest development version, you can install it directly from GitLab:

```sh
pip install git+https://gitlab.com/netmode/CyVer.git
```

Or, you can manually clone the repository and run:

```sh
git clone https://gitlab.com/netmode/CyVer.git
cd CyVer
pip install .
```



## 💻 Example Usage 

### Importing the Library

``` sh
import CyVer
from CyVer.validators import SyntaxValidator,PropertiesValidator,SchemaValidator
```

### Connect to Neo4j Database instance
```sh
from neo4j import GraphDatabase,basic_auth

driver = GraphDatabase.driver(database_url, auth=basic_auth(database_username, database_password))
```

### Syntax Validator

```sh
syntax_validator =  SyntaxValidator(driver)
query = 'MATCH (g:Goal) RETURN COUNT(g) AS output'
is_valid = syntax_validator.validate(query)
print(f"Syntax Valid: {is_valid}")
```

### Schema Validator
```sh
schema_validator =  SchemaValidator(driver)
query = 'MATCH (g:Goal)-[:HAS_TARGET]->(t:Target) RETURN g, t'
# Extraction
extracted_node_labels, extracted_rel_labels, extracted_paths = schema_validator.extract(query)
print(f"Extracted Node Labels : {extracted_node_labels}")
print(f"Extracted Relationships Labels : {extracted_rel_labels}")
print(f"Extracted One-hop Paths : {extracted_paths}")
# Validation 
schema_score = schema_validator.validate(query)
print(f"Schema Validation Score: {schema_score}")

```


### Properties Validator
```sh
props_validator =  PropertiesValidator(driver)
query = 'MATCH (g:Goal)-[:HAS_TARGET]-(t:Target) WHERE g.code =1 RETURN t'
# Extraction
variables_properties , labels_properties = props_validator.extract(query)
print(f"Accessed properties by variables: {variables_properties}")
print(f"Accessed properties by labels (including inferred): {labels_properties}")

# Validation 
props_score = props_validator.validate(query)
print(f"Properties Validation Score: {props_score}")
```


## License

This project is licensed under the [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) license.

## 🤝 Contributing

Contributions are welcome! Please submit a pull request or open an issue.

## Cite

To cite this work, please use:

## Contact

For any request for detailed information or expression of interest for participating at this initiative, you may contact:

- Ioanna Mandilara - ioannamand (at) netmode (dot) ntua (dot) gr
- Christina Maria Androna - andronaxm (at) netmode (dot) ntua (dot) gr
- Eleni Fotopoulou - efotopoulou (at) netmode (dot) ntua (dot) gr
- Anastasios Zafeiropoulos - tzafeir (at) cn (dot) ntua (dot) gr

---
