.. runic documentation master file

Welcome to **Runic**
====================

Graph schema migrations and OGM for Cypher-based graph databases.

|PyPI| |Github| |Python| |License|


.. |PyPI| image:: https://img.shields.io/pypi/v/runic-py.svg
   :target: https://pypi.org/project/runic-py/
   :alt: PyPI

.. |Github| image:: https://img.shields.io/badge/release-0.3.5-yellow?logo=github
   :target: https://github.com/jenreh/runic/tree/v0.3.5
   :alt: GitHub

.. |Python| image:: https://img.shields.io/badge/python-3.14%2B-orange.svg
   :target: https://www.python.org
   :alt: Python Support

.. |License| image:: https://img.shields.io/badge/license-MIT-green.svg
   :target: https://github.com/jenreh/runic/blob/main/LICENSE.md
   :alt: License

-----

**runic** ships two tools:

* **runic.ogm** — a lightweight, graph-optimized OGM that maps Python classes
  to graph nodes and edges.  Supports FalkorDB, ArcadeDB, Neo4j,
  Memgraph, Apache AGE (PostgreSQL), and any Bolt-compatible database
  via a pluggable driver layer.
* **runic.migrate** — an Alembic-style migration engine that tracks index and
  constraint changes as versioned, replayable scripts.

.. code-block:: python

   from runic.ogm import Field, Node, Repository, Session, create_driver

   class Person(Node, labels=["Person"]):
       id: str = Field()
       name: str = Field()
       email: str = Field(index=True, unique=True)

   with Session(driver) as session:
       session.add(Person(id="alice", name="Alice", email="alice@example.com"))
       session.commit()

       repo = Repository(session, Person)
       print(repo.count())   # 1

----

.. rubric:: OGM

.. grid:: 2

   .. grid-item-card:: OGM quickstart
      :link: quickstart
      :link-type: doc

      Define your first node, open a session, and persist it in under a
      minute.

   .. grid-item-card:: Define your models
      :link: concepts
      :link-type: doc

      Declare nodes, edges, fields, and relationships — with types, indexes,
      and constraints.

.. grid:: 2

   .. grid-item-card:: Model connections
      :link: relationships
      :link-type: doc

      Lazy/eager loading, polymorphic hierarchies, edge properties.

   .. grid-item-card:: Read and write data
      :link: session
      :link-type: doc

      add · delete · get · flush · commit · rollback · expire.

.. grid:: 2

   .. grid-item-card:: Query your graph
      :link: query_builder
      :link-type: doc

      Fluent filter, traversal, aggregation, fulltext and vector KNN API.

   .. grid-item-card:: Async guide
      :link: async
      :link-type: doc

      AsyncSession, no-lazy rules, async CRUD, repositories, and testing.

.. grid:: 2

   .. grid-item-card:: Test your code
      :link: testing
      :link-type: doc

      Embedded FalkorDB, pytest fixtures, isolation patterns, and gotchas.

   .. grid-item-card:: Choose a backend
      :link: drivers
      :link-type: doc

      FalkorDB, ArcadeDB, Neo4j, Memgraph, AGE — feature matrix and limits.

.. grid:: 2

   .. grid-item-card:: OGM API reference
      :link: api
      :link-type: doc

      Full autodoc reference for every public class and function.

----

.. rubric:: Migration

.. grid:: 2

   .. grid-item-card:: Migration quickstart
      :link: migration/quickstart
      :link-type: doc

      Install runic, run ``runic init``, write your first migration, and
      apply it — all in one page.

   .. grid-item-card:: OGM + Migration guide
      :link: migration/integration
      :link-type: doc

      Three-stage workflow, Field→op table, ordering rules, and 7 annotated
      patterns.

.. grid:: 2

   .. grid-item-card:: CLI reference
      :link: migration/cli_reference
      :link-type: doc

      Every command, option, and flag documented with examples.

   .. grid-item-card:: Operations reference
      :link: migration/operations_reference
      :link-type: doc

      Full list of ``op.*`` calls available inside migration scripts.

.. grid:: 2

   .. grid-item-card:: Schema management
      :link: migration/schema
      :link-type: doc

      IndexManager and SchemaManager — declare, validate, and sync indexes.

   .. grid-item-card:: Migration API reference
      :link: migration/api
      :link-type: doc

      ``runic.migrate`` — programmatic migration engine API.

----

.. toctree::
   :hidden:
   :caption: OGM

   quickstart
   concepts
   relationships
   query_builder
   session
   async
   testing
   drivers
   api

.. toctree::
   :hidden:
   :caption: Migration

   installation
   migration/index