Metadata-Version: 2.4
Name: ocg
Version: 0.4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
License-File: NOTICE
Summary: 100% openCypher-compliant in-memory graph database — 4 backends, 175+ algorithms, pure Rust
Keywords: graph,database,cypher,opencypher,graph-database,query-language,rust,graph-algorithms,bulk-loader
Author-email: Gregorio Momm <gregoriomomm@gmail.com>
License: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.ibm.com/enjoycode/ocg
Project-URL: Homepage, https://github.ibm.com/enjoycode/ocg
Project-URL: Repository, https://github.ibm.com/enjoycode/ocg

# OCG — OpenCypher Graph

**High-performance in-memory graph database with 100% OpenCypher compliance, 4 backends, and 31 algorithms — pure Rust.**

[![PyPI](https://img.shields.io/pypi/v/ocg)](https://pypi.org/project/ocg)
[![Python](https://img.shields.io/pypi/pyversions/ocg)](https://pypi.org/project/ocg)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![OpenCypher TCK](https://img.shields.io/badge/OpenCypher%20TCK-100%25-brightgreen)](https://opencypher.org)
[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org)

## Overview

OCG executes [OpenCypher](https://opencypher.org) queries against in-memory property graphs. It is built in pure Rust and exposed to Python via PyO3 bindings.

- **100% OpenCypher TCK**: 3,897 / 3,897 scenarios passing (0 skipped, 0 failed)
- **4 graph backends**: PropertyGraph, NetworKitRust, RustworkxCore, Graphrs
- **31 graph algorithms**: centrality, community detection, pathfinding, spanning trees, flow, coloring, matching
- **Bulk Loader API**: 57x faster batch construction vs OpenCypher `CREATE` statements
- **Serialization**: save/load graphs to JSON with full metadata
- **Python 3.8–3.13**, macOS · Linux · Windows

---

## Installation

```bash
pip install ocg
```

Rust:

```toml
[dependencies]
ocg = "0.3.0"
```

---

## Quick Start

### Python

```python
from ocg import Graph

graph = Graph()

# OpenCypher queries
graph.execute("CREATE (a:Person {name: 'Alice', age: 30})")
graph.execute("CREATE (b:Person {name: 'Bob', age: 25})")
graph.execute("MATCH (a:Person), (b:Person) WHERE a.name='Alice' AND b.name='Bob' CREATE (a)-[:KNOWS]->(b)")

result = graph.execute("MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name AS from, b.name AS to")
print(result)  # [{'from': 'Alice', 'to': 'Bob'}]
```

### Bulk Loader (10–57x faster)

Bypasses the OpenCypher parser for large batch operations:

```python
from ocg import Graph

graph = Graph()

node_ids = graph.bulk_create_nodes([
    (["Person"], {"name": "Alice", "age": 30}),
    (["Person"], {"name": "Bob",   "age": 25}),
])

graph.bulk_create_relationships([
    (node_ids[0], node_ids[1], "KNOWS", {"since": 2020}),
])

result = graph.execute("MATCH (a)-[:KNOWS]->(b) RETURN a.name, b.name")
```

### Serialization

```python
graph.save("my_graph.json")
loaded = Graph.load("my_graph.json")
```

### Rust

```rust
use ocg::{PropertyGraph, execute};

let mut graph = PropertyGraph::new();
execute(&mut graph, "CREATE (a:Person {name: 'Alice'})").unwrap();
let result = execute(&mut graph, "MATCH (n:Person) RETURN n.name").unwrap();
```

---

## Graph Backends

| Backend | Class | Description |
|---------|-------|-------------|
| PropertyGraph | `Graph` | Native petgraph-based property graph |
| NetworKitRust | `NetworKitGraph` | Port of NetworKit algorithms to pure Rust |
| RustworkxCore | `RustworkxGraph` | IBM Qiskit rustworkx-core algorithms |
| Graphrs | `GraphrsGraph` | graphrs-based community detection |

All four backends expose identical APIs: OpenCypher execution, bulk loader, 31 algorithms, and save/load.

---

## Graph Algorithms (31)

All algorithms are available on all 4 backends.

| Category | Algorithms |
|----------|-----------|
| Centrality | degree, betweenness, closeness, pagerank |
| Pathfinding | bfs, dijkstra, astar, bellman_ford, floyd_warshall, all_pairs |
| Spanning Trees | minimum, maximum |
| DAG | topological_sort, is_dag, find_cycles, dag_longest_path, dag_longest_path_weighted, transitive_closure |
| Flow | max_flow, min_cut_capacity |
| Coloring | node_coloring, edge_coloring, chromatic_number |
| Matching | max_weight_matching, max_cardinality_matching |
| Community | louvain, label_propagation, girvan_newman |
| Components | connected_components, strongly_connected_components |

```python
from ocg import Graph

graph = Graph()
# ... populate graph ...

scores = graph.pagerank(damping=0.85, max_iter=100)
communities = graph.louvain()
path = graph.dijkstra(source_id, target_id)
```

---

## Supported OpenCypher Features

### Clauses
- `MATCH`, `OPTIONAL MATCH`, variable-length paths `[*1..3]`
- `CREATE`, `MERGE`, `SET`, `DELETE`, `DETACH DELETE`, `REMOVE`
- `WITH`, `UNWIND`, `RETURN`, `WHERE`
- `ORDER BY`, `SKIP`, `LIMIT`, `DISTINCT`
- `UNION`, `UNION ALL`

### Expressions
- Property access, list indexing, string slicing
- Arithmetic: `+`, `-`, `*`, `/`, `%`, `^`
- Comparison: `=`, `<>`, `<`, `>`, `<=`, `>=`
- Logical: `AND`, `OR`, `NOT`, `XOR`
- String: `STARTS WITH`, `ENDS WITH`, `CONTAINS`, `=~`
- Null: `IS NULL`, `IS NOT NULL`
- List: `IN`, comprehensions, quantifiers

### Functions (60+)
- **String**: `substring`, `trim`, `toLower`, `toUpper`, `split`, `replace`
- **Math**: `abs`, `ceil`, `floor`, `round`, `sqrt`, `sin`, `cos`, `log`
- **List**: `size`, `head`, `tail`, `range`, `reverse`, `keys`
- **Aggregation**: `count`, `sum`, `avg`, `min`, `max`, `collect`
- **Temporal**: `date`, `datetime`, `localDatetime`, `duration`
- **Predicates**: `exists`, `all`, `any`, `none`, `single`

### Procedures
- `db.labels()`, `db.relationshipTypes()`, `db.propertyKeys()`
- `dbms.components()`

---

## TCK Compliance

**3,897 / 3,897 scenarios passing — 100% (0 skipped, 0 failed)**

Validated against the [openCypher Technology Compatibility Kit](https://github.com/opencypher/openCypher).

---

## Development

```bash
# Build
cargo build --release

# Unit tests
cargo test --no-default-features

# OpenCypher TCK
cargo test --test tck_property_graph --no-default-features

# Python wheel (requires maturin)
maturin develop --features python
```

---

## Credits

- **[petgraph](https://github.com/petgraph/petgraph)** — core graph data structures (MIT/Apache-2.0)
- **[rustworkx-core](https://github.com/Qiskit/rustworkx)** — graph algorithms (Apache-2.0)
- **[graphrs](https://github.com/malcolmvr/graphrs)** — community detection (MIT)
- **[openCypher TCK](https://github.com/opencypher/openCypher)** — test compatibility kit (Apache-2.0)
- Algorithm designs inspired by [NetworKit](https://networkit.github.io/) (MIT)

Algorithm implementations (PageRank, Betweenness Centrality, Dijkstra, etc.) are based on published academic work. See NOTICE file for complete citations.

---

## License

Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE) files.

OpenCypher® and Cypher® are registered trademarks of Neo4j, Inc. This project implements the open [OpenCypher specification](https://opencypher.org) and is not affiliated with Neo4j.

---

## Contributing

Issues and proposals may be submitted via GitHub. Contributions are evaluated on a controlled schedule — pull requests are reviewed at the maintainer's discretion and timeline.

