Metadata-Version: 2.5
Name: ontary
Version: 0.10.0
Summary: Domain-agnostic ontology SDK — declare a Foundry-style ontology (typed objects, links, actions, functions) and get a governed runtime
Project-URL: Repository, https://github.com/ryoochi0112/ontary
Project-URL: Changelog, https://github.com/ryoochi0112/ontary/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/ryoochi0112/ontary/blob/main/docs/api-reference.md
Project-URL: Compatibility, https://github.com/ryoochi0112/ontary/blob/main/docs/compatibility.md
Project-URL: License, https://github.com/ryoochi0112/ontary/blob/main/LICENSE
License-Expression: MIT
License-File: LICENSE
Keywords: audit,governance,mcp,ontology,pydantic,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.7
Provides-Extra: bq
Requires-Dist: dlt<2.0,>=1.0; extra == 'bq'
Requires-Dist: dlt[bigquery]<2.0,>=1.0; extra == 'bq'
Requires-Dist: duckdb<2.0,>=1.0; extra == 'bq'
Provides-Extra: dev
Requires-Dist: dlt<2.0,>=1.0; extra == 'dev'
Requires-Dist: dlt[bigquery]<2.0,>=1.0; extra == 'dev'
Requires-Dist: duckdb<2.0,>=1.0; extra == 'dev'
Requires-Dist: mcp<2,>=1.27.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: dlt
Requires-Dist: dlt<2.0,>=1.0; extra == 'dlt'
Requires-Dist: duckdb<2.0,>=1.0; extra == 'dlt'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.27.2; extra == 'mcp'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'postgres'
Description-Content-Type: text/markdown

# ontary — a domain-agnostic ontology SDK

Declare an ontology once — typed objects, links, actions, functions, and a
security policy — and get a governed runtime: scope- and sensitivity-aware
reads, audited business-verb actions, and an MCP server for AI agents.
The engine stays domain-agnostic; the tickets example is just one small domain.

Python 3.12+ · pydantic-only core · `mypy --strict` · offline `make verify`.

Release metadata: version
**0.10.0**, store schema **v9**. Releases are annotated tags (`v0.10.0`).

## Install

From PyPI:

```bash
uv add "ontary[mcp,postgres,dlt]==0.10.0"
```

or pin it in `pyproject.toml`:

```toml
[project]
dependencies = ["ontary[mcp,postgres,dlt]==0.10.0"]
```

The extras are optional: `mcp` serves the ontology to AI agents, `postgres`
adds the `PostgresStore` backend, and `dlt` adds the connector pipeline. The
core needs only `pydantic`.

Without an index, install the tagged git ref instead (exact tag, no patch
updates):

    uv add "ontary @ git+https://github.com/ryoochi0112/ontary@v0.10.0"

## Quickstart

This short runnable path uses a support-ticket domain. The complete
`Org → Queue → Ticket → Comment` ontology, connectors, effects, functions, and
runnable MCP stdio and effects-drain examples are in
[`examples/tickets/`](examples/tickets/).

<!-- quickstart-runnable:start -->
```python
from ontary import (
    ActionContext, ActionError, ActionParams, Consumer, DirectProperty,
    ObjectStore, Ontology, OntologyObject, Source, prop, target,
)
ontology = Ontology(name="tickets", scope_levels=["queue"])
@ontology.object(
    layer="L0", owned={"escalated": False},
    scope=[DirectProperty(level="queue", property_name="queue_id")],
)
class Ticket(OntologyObject):
    id: str = prop(primary_key=True)
    subject: str
    queue_id: str = prop(scope_level="queue")
    escalated: bool | None = prop(default=False)
class EscalateTicket(ActionParams):
    ticket_id: str = target(Ticket)
@ontology.action(
    EscalateTicket, target=Ticket, roles=["Agent"],
    display_name="Escalate ticket", description="Mark a ticket urgent.",
    api_name="EscalateTicket",
)
def escalate(ctx: ActionContext, params: EscalateTicket) -> dict[str, str]:
    if ctx.read_current("Ticket", params.ticket_id) is None:
        raise ActionError("ticket does not exist", code="PRECONDITION_FAILED")
    ctx.update("Ticket", params.ticket_id, {"escalated": True})
    return {"ticket_id": params.ticket_id}
ontology.validate()
store = ObjectStore(ontology.registry)
ticket_id = store.insert(
    "Ticket", {"subject": "Invoice mismatch", "queue_id": "queue-a"},
    Source(source_system="demo"),
)
client = ontology.bind(store).for_consumer(
    Consumer(actor_id="agent-1", role="Agent", scope_level="queue",
             scope_id="queue-a", kind="human")
)
ticket = client.get(Ticket, ticket_id)
assert ticket is not None and ticket.subject == "Invoice mismatch"
client.execute(EscalateTicket(ticket_id=ticket_id))
assert client.get(Ticket, ticket_id).escalated is True
```
<!-- quickstart-runnable:end -->

## Where to go

| Learn about | Destination |
| --- | --- |
| Authoring an ontology | [Ontology design guide](docs/ontology-design.md) |
| オントロジー設計 | [日本語ガイド](docs/ontology-design.ja.md) |
| Look up names and errors | [API reference](docs/api-reference.md) · [error-code table](docs/api-reference.md#error-codes) |
| API リファレンス | [日本語リファレンス](docs/api-reference.ja.md) |
| Storage and tenancy | [Storage, tenancy, and schema](docs/storage.md) |
| Connectors | [Connectors and canonical staging](docs/connectors.md) |
| MCP serving | [MCP serving](docs/mcp-serving.md) |
| Governed effects | [Governed capabilities and effects](docs/effects.md) |
| Queries and pagination | [Queries, typed reads, and pagination](docs/queries.md) |
| Authority and architecture | [Authority, declarations, and architecture](docs/authority.md) |
| Cookbook recipes | [Cookbook](docs/cookbook.md) |
| Compatibility and migration | [CHANGELOG.md](CHANGELOG.md) · [Compatibility](docs/compatibility.md) |
| v1 release gate | [v1.0.0 acceptance gate](docs/v1-gate.md) |
## License

MIT — see [LICENSE](LICENSE). `ontary` continues the `ontos` SDK, which
Atrae, Inc. authored and released to the author for open-source development.
