Metadata-Version: 2.4
Name: facton
Version: 0.2.0
Summary: A Python-native knowledge graph library.
Author: Milad Olad
Author-email: Milad Olad <milad.olad@gmail.com>
License-Expression: MIT
Requires-Dist: pydantic>=2.11
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# Facton

A Python-native knowledge graph library.

Define entities and connections as Python classes. Query, traverse, and annotate
your graph without learning a separate query language.

**[Documentation](https://milad-o.github.io/facton/)** · **[Changelog](CHANGELOG.md)**

## Install

```bash
pip install facton
```

Requires Python 3.13+.

## Quick Start

```python
from facton import Connection, Entity, Field, Graph


class Person(Entity):
    name: str
    age: int = Field(ge=0)


class Knows(Connection[Person, Person]):
    since: int | None = None


g = Graph()
alice = Person(id="alice", name="Alice", age=30)
bob = Person(id="bob", name="Bob", age=28)
g.add(alice)
g.add(bob)
g.connect(alice, bob, Knows(since=2019))

# Query
seniors = g.query(Person).where(lambda p: p.age >= 30).all()

# Traverse
friends = g.traverse(alice, Knows, depth=2)

# Persist
g.save_file("social.json")
```

## Features

- **Pure Python** — no external database, no query language
- **Typed from the ground up** — Pydantic models with full validation and generic connections
- **Queries** — fluent builder with `where`, `connected_to`, `order_by`, `group_by`, aggregation
- **Traversal** — depth-limited traversal, shortest path, connected components
- **Fact annotations** — per-field provenance metadata
- **Constraints** — field uniqueness, composite uniqueness, connection cardinality
- **Transactions** — atomic writes with rollback, read-only snapshots
- **Temporal history** — change log, point-in-time queries, named snapshots
- **Serialization** — lossless JSON with self-describing schema
- **Backends** — `InMemoryBackend`, `JsonFileBackend`, or implement `StorageBackend`
- **Inference rules** — `@rule` decorator and declarative `when`/`then` rules

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
uv run ruff format .
```