Metadata-Version: 2.4
Name: ontodag
Version: 0.14.1
Summary: Associative memory and categories based on a directed acyclic graph data structure
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/petfold/ontodag
Project-URL: Repository, https://github.com/petfold/ontodag
Project-URL: Issues, https://github.com/petfold/ontodag/issues
Keywords: ontology,knowledge-representation,knowledge-graph,concept-lattice,fca,formal-concept-analysis,formal concept analysis,pattern-structures,concrete-domains,dag,taxonomy,associative-memory,swarm,web3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: recordstore>=0.16.0
Provides-Extra: viz
Requires-Dist: graphviz; extra == "viz"
Requires-Dist: Pillow; extra == "viz"
Provides-Extra: owl
Requires-Dist: owlready2; extra == "owl"
Provides-Extra: store
Requires-Dist: recordstore>=0.16.0; extra == "store"
Provides-Extra: web
Requires-Dist: ontodag[owl,viz]; extra == "web"
Requires-Dist: flask; extra == "web"
Requires-Dist: dot2tex; extra == "web"
Provides-Extra: swarm
Requires-Dist: recordstore[bee,feeds,stamps]>=0.16.0; extra == "swarm"
Provides-Extra: all
Requires-Dist: ontodag[owl,store,swarm,viz,web]; extra == "all"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: ontodag[owl,store,viz]; extra == "test"
Dynamic: license-file

# OntoDAG

[![tests](https://github.com/petfold/ontodag/actions/workflows/tests.yml/badge.svg)](https://github.com/petfold/ontodag/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/ontodag)](https://pypi.org/project/ontodag/)
[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)

Associative memory and categories based on a directed acyclic graph data structure

## Documentation

- **[User Guide](docs/USER_GUIDE.md)** — tutorial and how-to: installation, Python,
  command line, web app/REST, AI agents, troubleshooting. Start here.
- **[Reference](docs/REFERENCE.md)** — every command, setting, kind, endpoint and
  tool, compact; its tables are pinned to the code by the test suite.
- **[How It Works Inside](docs/HOW_IT_WORKS.md)** — the design in plain language
  (canonical form, query planning, content-addressed persistence, verifiable answers).
- **[Changelog](CHANGELOG.md)** — what each release added, with registry migration notes.
- **[The contract](docs/CONTRACT.md)** — what programs (and AI agents) built on
  OntoDAG may rely on: the guarantees, versioned.
- **[docs/README.md](docs/README.md)** — the full documentation map: design records
  (`docs/`) and discussion drafts / future directions (`docs/plans/`, including the
  [Roadmap](docs/plans/ROADMAP.md)).

See also **[ontodag-fs](https://github.com/petfold/ontodag-fs)**: any OntoDAG
store can be browsed as a filesystem — paths are category queries, files are
classified objects stored on Swarm, FUSE-mountable (`odag-fs`, which shares
odag's store settings).

## Specification

A Directed Acyclic Graph (DAG) associative storage and category manager in Python. You can store items into a ontodag and recall items from it. To store or "put" an item into a ontodag, you give it a name and a set of other names of already existing items that are its supercategories. To recall or "get", you specify a set of item names to get all items that are subcategories of all these items; alternatives are one word away (`odag get Flight Japan or Hotel`, `get_any` in Python).

File a flight confirmation under both `Flight` and `Japan`, the boarding pass
under the flight itself, and `odag get Japan` returns the whole trip — including
the boarding pass you never filed under the trip. No folder had to be chosen.

Categories can also carry **typed values**: declare `time` as a dimension
and `time(2026-08-15)` becomes an ordinary category whose ordering OntoDAG
computes — `odag get Flight 'time(2026-06-01..2026-08-31)'` finds last summer's
flights with no edge ever stored between them, at any range, with exact
arithmetic — values are rationals of the SI anchor units, so *every* exactly
defined unit works: all of SI, pounds and psi, TB and TiB, even Celsius and
Fahrenheit (mapped exactly onto the kelvin scale: `temperature(24C)`) built
in, and **unit packs one merge
away** (`odag pack crypto-core` for BTC/ETH/BZZ, `fiat-iso4217` for ~150 national
currencies, `crypto-majors` for the market's top coins — or declare your
own: vocabulary is graph data that travels with the store, no release
needed). `odag prelude` declares the everyday dimensions in one command. Weights and sizes (`weight(..5kg)`), hierarchical codes like geohash
cells, and does-it-fit tuples all work the same way. See
[User Guide §4.7](docs/USER_GUIDE.md) and the design record
[docs/DIMENSIONS.md](docs/DIMENSIONS.md).

Values are stored in an exact canonical form and shown to you in a friendly
one: on a terminal `odag` prints `time(2026)` and `weight(3kg)`, while pipes
and files always get the exact bytes, so `odag get ... | odag` round-trips
(`--render`/`--raw` override; `odag canon TERM` shows what any spelling
actually stores). The same split governs how much you get: a terminal stops
at 50 results with a note saying how many were withheld, a pipe is never
truncated. A query with no terms at all is the empty intersection — no
constraints, so every item (`odag count` gives just the size).

## For AI agents

Serve any store to an agent over MCP with **`odag-mcp`**
(`claude mcp add odag -- odag-mcp`): query, fits-within, overlap candidates,
per-item description, canonical echo, and an `about` tool that says what the
store contains — read-only by default; `--write` adds a propose→confirm write
surface where every change carries a **signed provenance record** (who
asserted what, against which state) and a `review` tool computes each claim's
standing under *your* trust list: claims merge, acceptance is policy. Every answer cites the **root** — a fingerprint of the
store's entire content — and `is_below` answers can carry a **certificate**
that anyone holding only that fingerprint can verify, with no access to the
store (`ontodag.certificates.verify_below`). Equal knowledge yields an equal
fingerprint, so two parties can prove they agree — and a disagreement shows
up as structure, not prose. The guarantees an agent (or any program) may
rely on are written down and versioned in [docs/CONTRACT.md](docs/CONTRACT.md);
the tool shapes in [docs/AGENT_SURFACE.md](docs/AGENT_SURFACE.md).

## Roadmap

The roadmap — what is done, what is queued next, what is parked and why — is in
**[docs/plans/ROADMAP.md](docs/plans/ROADMAP.md)**.
Longer-term goals for the database direction (and the features deliberately not
built yet) are in [docs/plans/DATABASE_DIRECTION.md](docs/plans/DATABASE_DIRECTION.md); the
day-to-day task list is in `CLAUDE.md`.

## Potential Applications
* Using the ontology graph for content categorization instead of folders
* Replace content tags with a more structured ontology
* Access control (ACT) groups
* Memberships in organizations and gate content based on membership
* Communication channel groups defined by the ontology
* Fostering deals within a universal marketplace for services and goods
