awaredb 0.1.1__py3-none-any.whl

awaredb/__init__.py

@@ -0,0 +1,20 @@
+from .api import AwareDBClient
+from .exceptions import (
+    AuthError,
+    AwareDBError,
+    InvalidCommandError,
+    TransportError,
+    UnexpectedError,
+)
+
+__version__ = "0.1.1"
+
+__all__ = (
+    "AwareDBClient",
+    "AwareDBError",
+    "AuthError",
+    "InvalidCommandError",
+    "TransportError",
+    "UnexpectedError",
+    "__version__",
+)

awaredb/api.py

@@ -0,0 +1,81 @@
+"""AwareDBClient — composes the mixins into the user-facing class."""
+
+from .exceptions import AuthError
+from .mixins import (
+    AnalysesMixin,
+    AuthMixin,
+    DataMixin,
+    HistoryMixin,
+    HTTPClientMixin,
+    IOMixin,
+)
+
+__all__ = ("AwareDBClient",)
+
+
+class AwareDBClient(
+    HTTPClientMixin,
+    AuthMixin,
+    DataMixin,
+    AnalysesMixin,
+    HistoryMixin,
+    IOMixin,
+):
+    """Python client for an AwareDB instance.
+
+    Usage:
+
+        client = AwareDBClient(db="my_db", token="…")
+        client.check()
+        client.calculate(formula="car.power")
+
+    Or with username/password:
+
+        client = AwareDBClient(db="my_db", user="alice", password="…")
+
+    The client keeps a persistent HTTP connection pool. Call `close()` (or use
+    it as a context manager) when finished to release the socket.
+    """
+
+    DEFAULT_HOST = "https://djina.com"
+    DEFAULT_TIMEOUT = 180.0
+
+    def __init__(
+        self,
+        db: str,
+        token: str | None = None,
+        user: str | None = None,
+        password: str | None = None,
+        host: str | None = None,
+        timeout: float | None = None,
+        check_connection: bool = True,
+    ):
+        """Initialise the client.
+
+        Args:
+            db: Database name or UUID.
+            token: API token. Required unless `user`/`password` are provided.
+            user / password: Used to fetch a fresh token at construction time.
+            host: AwareDB base URL. Defaults to ``https://djina.com``.
+            timeout: Request timeout in seconds. Defaults to 180.
+            check_connection: Probe `/check/` on init to fail fast on bad creds.
+
+        Raises:
+            ValueError: Neither token nor user/password were provided.
+            AuthError: Server rejected the credentials, or the database is unreachable.
+        """
+        if not token and not (user and password):
+            raise ValueError("Either `token` or both `user` and `password` are required.")
+
+        self.host = (host or self.DEFAULT_HOST).rstrip("/")
+        self.db = db
+        self.timeout = timeout if timeout is not None else self.DEFAULT_TIMEOUT
+        self.token = token
+
+        if not self.token:
+            assert user
+            assert password
+            self.token = self._fetch_token(user=user, password=password)
+
+        if check_connection and not self.check():
+            raise AuthError(f"Unable to connect to AwareDB database `{db}` at {self.host}.")

awaredb/exceptions.py

@@ -0,0 +1,64 @@
+"""AwareDB client exceptions."""
+
+
+class AwareDBError(Exception):
+    """Base exception for all AwareDB client errors."""
+
+    code = "awaredb_error"
+    default_message = "An error occurred while talking to AwareDB."
+
+    def __init__(self, message: str | None = None, extra_info: str | None = None):
+        super().__init__(message or self.default_message)
+        self.extra_info = extra_info
+
+
+class UnexpectedError(AwareDBError):
+    """Raised when something unanticipated breaks (e.g. a 2xx body that isn't JSON)."""
+
+    code = "unexpected_error"
+    default_message = "An unexpected error occurred."
+
+
+# ---------------------------------------------------------------------------
+# Transport
+# ---------------------------------------------------------------------------
+
+
+class TransportError(AwareDBError):
+    """Raised when an HTTP request fails (non-2xx status, timeout, network error)."""
+
+    code = "transport_error"
+    default_message = "Transport error: HTTP request to AwareDB failed."
+
+    def __init__(
+        self,
+        message: str | None = None,
+        extra_info: str | None = None,
+        status_code: int | None = None,
+    ):
+        super().__init__(message, extra_info)
+        self.status_code = status_code
+
+
+# ---------------------------------------------------------------------------
+# Auth
+# ---------------------------------------------------------------------------
+
+
+class AuthError(AwareDBError):
+    """Raised when authentication or authorisation fails."""
+
+    code = "auth_error"
+    default_message = "Authentication failed."
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+class InvalidCommandError(AwareDBError):
+    """Raised when a request is rejected by the server with a 400 (bad payload, bad command)."""
+
+    code = "invalid_command"
+    default_message = "AwareDB rejected the request as invalid."

awaredb/mixins/__init__.py

@@ -0,0 +1,15 @@
+from .analyses import AnalysesMixin
+from .auth import AuthMixin
+from .data import DataMixin
+from .history import HistoryMixin
+from .http import HTTPClientMixin
+from .io import IOMixin
+
+__all__ = (
+    "AnalysesMixin",
+    "AuthMixin",
+    "DataMixin",
+    "HistoryMixin",
+    "HTTPClientMixin",
+    "IOMixin",
+)

awaredb/mixins/analyses.py

@@ -0,0 +1,117 @@
+"""Wrappers around the read-only analysis endpoints.
+
+The server runs each analysis against a temporarily recalculated context
+(`db.scenarios`, `db.impact`, …). The client just packages settings and
+forwards them.
+"""
+
+from typing import Any
+
+from ..typing import Edit
+
+__all__ = ("AnalysesMixin",)
+
+
+class AnalysesMixin:
+    """Mirrors the server-side analysis commands."""
+
+    def scenarios(
+        self,
+        edits: list[Edit] | dict[str, Any],
+        states: list[str] | None = None,
+    ) -> Any:
+        """Apply path/value overrides, recalculate, return per-scenario results."""
+        return self._request("scenarios", {"edits": edits, "states": states or []})
+
+    def impact(
+        self,
+        edit: Edit | dict[str, Any] | None = None,
+        states: list[str] | None = None,
+        **extra: Any,
+    ) -> Any:
+        """Run impact analysis — vary an input across N steps and observe outputs."""
+        payload: dict[str, Any] = {"states": states or [], **extra}
+        if edit is not None:
+            payload["edit"] = edit
+        return self._request("impact", payload)
+
+    def projection(
+        self,
+        start_from: str | None = None,
+        unit: str = "day",
+        step: int = 1,
+        points: int = 10,
+        edits: list[Edit] | None = None,
+        states: list[str] | None = None,
+    ) -> Any:
+        """Walk forward in time. `edits` apply per-step changes."""
+        payload: dict[str, Any] = {
+            "unit": unit,
+            "step": step,
+            "points": points,
+            "edits": edits or [],
+            "states": states or [],
+        }
+        if start_from is not None:
+            payload["start_from"] = start_from
+        return self._request("projection", payload)
+
+    def goal_seek(
+        self,
+        target: dict[str, Any],
+        decision: dict[str, Any],
+        states: list[str] | None = None,
+        **extra: Any,
+    ) -> Any:
+        """Find the input value that drives `target` to a desired value."""
+        return self._request(
+            "goal_seek",
+            {"target": target, "decision": decision, "states": states or [], **extra},
+        )
+
+    def optimize(
+        self,
+        objectives: list[dict[str, Any]],
+        decisions: list[dict[str, Any]],
+        constraints: list[dict[str, Any]] | None = None,
+        states: list[str] | None = None,
+        **extra: Any,
+    ) -> Any:
+        """Vary decision variables to min/max objectives subject to constraints."""
+        return self._request(
+            "optimize",
+            {
+                "objectives": objectives,
+                "decisions": decisions,
+                "constraints": constraints or [],
+                "states": states or [],
+                **extra,
+            },
+        )
+
+    def sensitivity(
+        self,
+        target: dict[str, Any],
+        inputs: list[dict[str, Any]],
+        states: list[str] | None = None,
+        **extra: Any,
+    ) -> Any:
+        """Perturb each input by ±delta and report the response per variant."""
+        return self._request(
+            "sensitivity",
+            {"target": target, "inputs": inputs, "states": states or [], **extra},
+        )
+
+    def trace(
+        self,
+        target: dict[str, Any] | str,
+        depth: int = 5,
+        states: list[str] | None = None,
+    ) -> Any:
+        """Walk the upstream dependency tree for `target`."""
+        if isinstance(target, str):
+            target = {"path": target}
+        return self._request(
+            "trace",
+            {"target": target, "depth": depth, "states": states or []},
+        )

awaredb/mixins/auth.py

@@ -0,0 +1,48 @@
+"""Authentication + connection-check for the AwareDB client."""
+
+import httpx
+
+from ..exceptions import AuthError, TransportError
+
+__all__ = ("AuthMixin",)
+
+
+class AuthMixin:
+    """Token fetch (username/password → token) and connection probe."""
+
+    host: str
+    token: str | None
+    timeout: float
+
+    def _fetch_token(self, user: str, password: str) -> str:
+        """Exchange username/password for an AwareDB API token.
+
+        Hits the standard DRF auth endpoint `/rest/auth/token/login/`.
+        """
+        try:
+            response = httpx.post(
+                f"{self.host}/rest/auth/token/login/",
+                json={"username": user, "password": password},
+                timeout=self.timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise TransportError(
+                f"login: HTTP request to {self.host} failed ({type(exc).__name__})",
+                extra_info=str(exc)[:500],
+            ) from exc
+
+        if not response.is_success:
+            raise AuthError(
+                f"login: AwareDB returned HTTP {response.status_code}",
+                extra_info=(response.text[:500] if response.text else ""),
+            )
+
+        token = response.json().get("token")
+        if not token:
+            raise AuthError("login: AwareDB returned no token in the response")
+        return token
+
+    def check(self) -> bool:
+        """Return True if the token is valid and the database exists."""
+        # late-bound — provided by HTTPClientMixin
+        return self._request("check") == {"connected": True}

awaredb/mixins/data.py

@@ -0,0 +1,83 @@
+"""Read + write commands against an AwareDB."""
+
+from typing import Any
+
+from ..typing import Node
+
+__all__ = ("DataMixin",)
+
+
+class DataMixin:
+    """Mirrors the server-side data commands declared in `AwareDBCommandView.COMMANDS`."""
+
+    # Reads
+    # ------------------------------------------------------------------
+
+    def get(self, path: str, states: list[str] | None = None) -> Any:
+        """Return the value at `path`.
+
+        Args:
+            path: Dotted path into a node, e.g. ``"car.engine.power"``.
+            states: Optional list of active states to apply during calculation.
+        """
+        return self._request("get", {"path": path, "states": states or []})
+
+    def query(
+        self,
+        nodes: list[str] | None = None,
+        conditions: list[str] | None = None,
+        properties: list[str] | None = None,
+        states: list[str] | None = None,
+        show_abstract: bool = False,
+    ) -> list[Node]:
+        """Return nodes matching the filters.
+
+        Args:
+            nodes: Identifiers (id, uid, or name). Use ``["*"]`` for all.
+            conditions: Formula-language predicates evaluated per node.
+            properties: Project only these properties. Default: all.
+            states: Active states.
+            show_abstract: Include abstract (template) nodes. Default ``False``.
+        """
+        return self._request(
+            "query",
+            {
+                "nodes": nodes or ["*"],
+                "conditions": conditions or [],
+                "properties": properties or [],
+                "states": states or [],
+                "show_abstract": show_abstract,
+            },
+        )
+
+    def calculate(
+        self,
+        formula: str | list[str],
+        states: list[str] | None = None,
+    ) -> Any:
+        """Evaluate one or more formulas against the database."""
+        return self._request("calculate", {"formula": formula, "states": states or []})
+
+    # Writes
+    # ------------------------------------------------------------------
+
+    def update(
+        self,
+        data: dict[str, Any] | list[dict[str, Any]],
+        partial: bool = False,
+    ) -> list[dict[str, Any]]:
+        """Create or update nodes, relations, or relation types.
+
+        Args:
+            data: Item or list of items to upsert.
+            partial: If ``True``, only the fields provided are updated.
+        """
+        return self._request("update", {"data": data, "partial": partial})
+
+    def remove(self, ids: list[str]) -> None:
+        """Delete nodes / relations / relation types by id."""
+        return self._request("remove", {"ids": ids})
+
+    def flush(self) -> None:
+        """Drop everything in the database."""
+        return self._request("flush")

awaredb/mixins/history.py

@@ -0,0 +1,42 @@
+"""History endpoint wrapper."""
+
+from datetime import datetime
+from typing import Any
+
+from ..typing import HistoryChange
+
+__all__ = ("HistoryMixin",)
+
+
+class HistoryMixin:
+    """Mirrors the server-side `history` command."""
+
+    def history(
+        self,
+        change_id: str | None = None,
+        ids: list[str] | None = None,
+        start: int | None = None,
+        end: int | None = None,
+        from_date: datetime | None = None,
+        to_date: datetime | None = None,
+    ) -> list[HistoryChange]:
+        """List changes recorded in the history database.
+
+        Args:
+            change_id: If given, return only the matching change.
+            ids: Filter to changes that touched these node/relation ids.
+            start: Pagination start index (default 0).
+            end: Pagination end index (default 1000).
+            from_date: Restrict to changes on or after this datetime.
+            to_date: Restrict to changes on or before this datetime.
+        """
+        payload: dict[str, Any] = {
+            "change_id": change_id,
+            "ids": ids,
+            "start": start,
+            "end": end,
+            "from_date": from_date.isoformat() if from_date else None,
+            "to_date": to_date.isoformat() if to_date else None,
+        }
+        payload = {key: value for key, value in payload.items() if value is not None}
+        return self._request("history", payload)

awaredb/mixins/http.py

@@ -0,0 +1,122 @@
+"""Low-level signed HTTP transport for the AwareDB client.
+
+One mixin to own every HTTP concern: building the URL, attaching the auth
+header, parsing the response, mapping non-2xx into typed exceptions. Higher
+mixins call `_request(...)` and stay command-shaped.
+"""
+
+from typing import Any
+
+import httpx
+
+from ..exceptions import (
+    AuthError,
+    InvalidCommandError,
+    TransportError,
+    UnexpectedError,
+)
+
+__all__ = ("HTTPClientMixin",)
+
+
+class HTTPClientMixin:
+    """Provides a persistent `httpx.Client` and a thin `_request()` wrapper."""
+
+    # These attributes are set by AwareDBClient.__init__.
+    host: str
+    db: str
+    token: str | None
+    timeout: float
+
+    _client: httpx.Client | None = None
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying httpx client. Safe to call repeatedly."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Request
+    # ------------------------------------------------------------------
+
+    def _http_client(self) -> httpx.Client:
+        """Return (and lazily build) the persistent HTTP client.
+
+        Keeping a single `httpx.Client` per `AwareDBClient` instance reuses
+        the underlying connection pool, which matters when a caller issues
+        many calculate/query requests in a row.
+        """
+        if self._client is None:
+            transport = httpx.HTTPTransport(retries=3)
+            self._client = httpx.Client(
+                base_url=self.host,
+                timeout=self.timeout,
+                transport=transport,
+            )
+        return self._client
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Accept": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Token {self.token}"
+        return headers
+
+    def _request(self, command: str, data: dict[str, Any] | None = None) -> Any:
+        """Send a command request and unwrap the `{"data": ...}` envelope.
+
+        Args:
+            command: The server command name, e.g. ``"query"``, ``"scenarios"``.
+            data: JSON-serialisable payload.
+
+        Raises:
+            AuthError: 401/403 from the server.
+            InvalidCommandError: 400 from the server (bad payload, unknown command).
+            TransportError: Network failure or other non-2xx status.
+            UnexpectedError: 2xx response that isn't JSON.
+        """
+        url = f"/rest/db/{self.db}/{command}/"
+        try:
+            response = self._http_client().post(url, json=data or {}, headers=self._headers())
+        except httpx.HTTPError as exc:
+            raise TransportError(
+                f"{command}: HTTP request to {self.host}{url} failed ({type(exc).__name__})",
+                extra_info=str(exc)[:500],
+            ) from exc
+
+        if response.status_code in (401, 403):
+            raise AuthError(
+                f"{command}: AwareDB returned HTTP {response.status_code}",
+                extra_info=(response.text[:500] if response.text else ""),
+            )
+        if response.status_code == 400:
+            raise InvalidCommandError(
+                f"{command}: AwareDB rejected the request",
+                extra_info=(response.text[:500] if response.text else ""),
+            )
+        if not response.is_success:
+            raise TransportError(
+                f"{command}: AwareDB returned HTTP {response.status_code}",
+                extra_info=(response.text[:500] if response.text else ""),
+                status_code=response.status_code,
+            )
+
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise UnexpectedError(
+                f"{command}: AwareDB returned a non-JSON 2xx body",
+                extra_info=response.text[:500],
+            ) from exc
+
+        return body.get("data") if isinstance(body, dict) else body

awaredb/mixins/io.py

@@ -0,0 +1,59 @@
+"""Bulk-load JSON files / folders into an AwareDB."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+__all__ = ("IOMixin",)
+
+
+class IOMixin:
+    """`load(...)` reads JSON from disk and pushes it through `update`."""
+
+    def load(self, filepath: str | Path, recursive: bool = False, flush: bool = False) -> None:
+        """Push the contents of a JSON file (or folder of JSON files) to the database.
+
+        Args:
+            filepath: File or directory path.
+            recursive: When `filepath` is a directory, descend into subfolders.
+            flush: If ``True``, drop the database before loading.
+
+        Raises:
+            FileNotFoundError: If `filepath` doesn't exist.
+        """
+        path = Path(filepath)
+        if not path.exists():
+            raise FileNotFoundError(f"Path {path} does not exist.")
+
+        if flush:
+            self.flush()
+
+        data: list[dict[str, Any]] = []
+        if path.is_dir():
+            self._load_folder(data, path, recursive=recursive)
+        else:
+            self._load_file(data, path)
+
+        if data:
+            self.update(data)
+
+    def _load_folder(
+        self,
+        data: list[dict[str, Any]],
+        path: Path,
+        recursive: bool = False,
+    ) -> None:
+        for entry in path.iterdir():
+            if entry.is_dir():
+                if recursive:
+                    self._load_folder(data, entry, recursive=recursive)
+            elif entry.suffix.lower() == ".json":
+                self._load_file(data, entry)
+
+    def _load_file(self, data: list[dict[str, Any]], path: Path) -> None:
+        with path.open("r", encoding="utf-8") as f:
+            content = json.load(f)
+        if isinstance(content, list):
+            data.extend(content)
+        else:
+            data.append(content)

awaredb/typing.py

@@ -0,0 +1,47 @@
+"""Typed response shapes returned by AwareDB.
+
+These are intentionally loose `TypedDict`s — AwareDB returns nested,
+dynamically-shaped JSON for most calls. The types document the *known*
+fields so callers get autocomplete; unknown fields are still allowed.
+"""
+
+from typing import Any, NotRequired, TypedDict
+
+
+class Node(TypedDict, total=False):
+    """A node in an AwareDB graph."""
+
+    id: str
+    uid: NotRequired[str]
+    name: NotRequired[str]
+    adb_type: NotRequired[str]
+    abstract: NotRequired[bool]
+    properties: NotRequired[dict[str, Any]]
+    value: NotRequired[Any]
+
+
+class Relation(TypedDict, total=False):
+    """An edge in an AwareDB graph."""
+
+    id: str
+    from_node: NotRequired[str]
+    to_node: NotRequired[str]
+    relation_type: NotRequired[str]
+    properties: NotRequired[dict[str, Any]]
+
+
+class Edit(TypedDict):
+    """A path/value override used by scenarios and other analyses."""
+
+    path: str
+    value: Any
+
+
+class HistoryChange(TypedDict, total=False):
+    """A single change record from the history database."""
+
+    id: str
+    date: str
+    user: NotRequired[str]
+    data: NotRequired[dict[str, Any]]
+    info: NotRequired[dict[str, Any]]

awaredb-0.1.1.dist-info/METADATA

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: awaredb
+Version: 0.1.1
+Summary: Python client for AwareDB — a data-modeling and calculation platform with unit-aware formulas, scenarios, optimization, and reversible history.
+Author-email: AwareDB Team <support@awaredb.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/djinalab/awaredb-python
+Project-URL: Bug Tracker, https://github.com/djinalab/awaredb-python/issues
+Project-URL: Documentation, https://dev.djina.com/
+Project-URL: Source Code, https://github.com/djinalab/awaredb-python
+Keywords: awaredb,calculations,formulas,units,scenarios,optimization,graph,api-client,modeling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Dynamic: license-file
+
+# awaredb
+
+Python client for [AwareDB](https://dev.djina.com/) — a data-modeling and calculation
+platform with unit-aware formulas, reversible history, and a rich analyses toolbox
+(scenarios, optimisation, sensitivity, projections, traces).
+
+```bash
+pip install awaredb
+```
+
+```python
+from awaredb import AwareDBClient
+
+with AwareDBClient(db="my_db", token="…") as client:
+    client.calculate(formula="car.power * 2")
+```
+
+---
+
+## Features
+
+- Connect by token or by username/password.
+- Read commands: `get`, `query`, `calculate`.
+- Write commands: `update`, `remove`, `flush`, `load` (bulk-load JSON from disk).
+- Analyses: `scenarios`, `impact`, `projection`, `goal_seek`, `optimize`,
+  `sensitivity`, `trace`.
+- History: `history` against the reversible audit database.
+- Typed exceptions: `AwareDBError`, `TransportError`, `AuthError`,
+  `InvalidCommandError`, `UnexpectedError`.
+- Persistent `httpx`-backed transport with built-in retries and connection pooling.
+- Ships a `py.typed` marker — works with `mypy` / `pyright` out of the box.
+
+---
+
+## Requirements
+
+- Python 3.12+
+- `httpx`
+
+---
+
+## Quick start
+
+```python
+from awaredb import AwareDBClient
+
+# Token auth
+client = AwareDBClient(db="my_db", token="…")
+
+# Username / password — fetches a token at construction time
+client = AwareDBClient(db="my_db", user="alice", password="…")
+
+# Custom host + timeout, no upfront connection check
+client = AwareDBClient(
+    db="my_db",
+    token="…",
+    host="https://aware.example.com",
+    timeout=30,
+    check_connection=False,
+)
+
+# Close the underlying HTTP client when finished
+client.close()
+
+# Or use the client as a context manager
+with AwareDBClient(db="my_db", token="…") as client:
+    client.flush()
+```
+
+---
+
+## Read commands
+
+### `get(path, states=None)`
+
+Return the value at a path.
+
+```python
+client.get(path="car.power")
+# "250 hp"
+```
+
+### `query(nodes=None, conditions=None, properties=None, states=None, show_abstract=False)`
+
+Return nodes matching the filters. `nodes` defaults to `["*"]` (all).
+
+```python
+client.query(
+    nodes=["employee"],
+    conditions=["node.salary.gross > 60000"],
+    properties=["salary"],
+)
+```
+
+### `calculate(formula, states=None)`
+
+Evaluate one or more formulas against the live database.
+
+```python
+client.calculate(formula="car.power * 2")
+# "500 hp"
+```
+
+---
+
+## Write commands
+
+### `update(data, partial=False)`
+
+Create or update nodes / relations / relation types. `data` accepts a single item
+or a list.
+
+```python
+client.update([
+    {"uid": "fan", "power": "=sum(this.children.power)"},
+])
+```
+
+### `remove(ids)`
+
+Delete by id.
+
+```python
+client.remove(ids=["7037a8a5-…", "7037a8a5-…"])
+```
+
+### `flush()`
+
+Drop every node and relation in the database.
+
+### `load(filepath, recursive=False, flush=False)`
+
+Push the contents of a JSON file (or folder of JSON files) through `update`.
+
+```python
+client.load("./seed", recursive=True, flush=True)
+```
+
+---
+
+## Analyses
+
+All analyses are read-only — they recalculate the graph against a temporary
+context and return per-variant results. None mutate the database.
+
+### `scenarios(edits, states=None)`
+
+Apply path/value overrides, recalculate, return per-scenario results.
+
+```python
+client.scenarios(edits=[{"path": "motor.power", "value": "30 kW"}])
+```
+
+### `impact(edit, states=None, **extra)`
+
+Sweep an input across N steps and observe outputs.
+
+### `projection(start_from, unit="day", step=1, points=10, edits=None, states=None)`
+
+Walk forward in time. Per-step `edits` apply between points.
+
+### `goal_seek(target, decision, states=None, **extra)`
+
+Find the input value that drives `target` to a desired value.
+
+### `optimize(objectives, decisions, constraints=None, states=None, **extra)`
+
+Vary decision variables to minimise / maximise objectives subject to constraints.
+
+### `sensitivity(target, inputs, states=None, **extra)`
+
+Perturb each input by ±delta and report the response per variant.
+
+### `trace(target, depth=5, states=None)`
+
+Walk the upstream dependency tree of a target path.
+
+```python
+client.trace(target="car.range", depth=10)
+```
+
+---
+
+## History
+
+### `history(change_id=None, ids=None, start=None, end=None, from_date=None, to_date=None)`
+
+List changes recorded in the reversible history database.
+
+```python
+from datetime import datetime
+
+client.history(from_date=datetime(2026, 1, 1))
+```
+
+---
+
+## Errors
+
+Everything funnels through `AwareDBError`. Subclasses indicate the failure mode:
+
+| Exception              | When it fires                                            |
+|------------------------|----------------------------------------------------------|
+| `AuthError`            | 401 / 403, or username/password rejected.                |
+| `InvalidCommandError`  | 400 — bad payload or unknown command.                    |
+| `TransportError`       | Network failure or other non-2xx HTTP status.            |
+| `UnexpectedError`      | 2xx body that isn't JSON.                                |
+| `AwareDBError`         | Base class. Catch this to handle everything above.       |
+
+---
+
+## Development
+
+[`uv`](https://github.com/astral-sh/uv) drives dependency management. The
+lockfile (`uv.lock`) is committed and pins exact versions.
+
+```bash
+# One-time: install uv
+brew install uv                            # macOS / Linuxbrew
+# or:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Provision the project env (creates .venv from uv.lock — runtime + dev group)
+uv sync
+
+# Runtime-only (excludes dev group: pytest, ruff, mypy, …)
+uv sync --no-dev
+
+# Tests, lint, format, type check
+uv run pytest
+uv run ruff check awaredb/ tests/
+uv run ruff format --check awaredb/ tests/
+uv run mypy awaredb/
+
+# Add / remove deps (auto-updates pyproject.toml + uv.lock)
+uv add some-package
+uv add --group dev some-package
+uv remove some-package
+```
+
+> **Note:** `python -m build` is the pip-era invocation and requires the `build`
+> package installed in the env. With `uv`, use `uv build` instead — it uses
+> `uv`'s own PEP 517 frontend, no extra dependency needed.
+
+---
+
+## Releasing
+
+Releases are cut by pushing a `v*` git tag. The `.github/workflows/release.yml`
+workflow builds the sdist + wheel with `uv build` and uploads them to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no token
+in CI).
+
+### One-time PyPI setup
+
+1. Create the project on PyPI: <https://pypi.org/manage/account/publishing/>.
+2. Add a **pending trusted publisher** with:
+   - PyPI Project Name: `awaredb`
+   - Owner: `djinalab`
+   - Repository name: `awaredb-python`
+   - Workflow name: `release.yml`
+   - Environment name: `pypi`
+3. In GitHub repo settings → Environments, create an environment named `pypi`
+   (optionally with required reviewers for an approval gate).
+
+### Cutting a release
+
+```bash
+# 1. Bump version in awaredb/__init__.py (e.g. 0.1.0 → 0.1.1)
+# 2. Move the [Unreleased] block in CHANGELOG.md under a new [X.Y.Z] - YYYY-MM-DD heading
+# 3. Commit, push to main
+git commit -am "Release 0.1.1"
+git push
+
+# 4. Tag and push — release.yml fires automatically
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+### Manual publish (fallback)
+
+If you need to publish from a workstation:
+
+```bash
+uv build                                   # writes sdist + wheel to dist/
+uv publish                                 # uses UV_PUBLISH_TOKEN env var
+# or:
+uv publish --token "$PYPI_API_TOKEN"
+```
+
+The `dist/` folder is gitignored — never commit build artifacts.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [CHANGELOG.md](./CHANGELOG.md).

awaredb-0.1.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+awaredb/__init__.py,sha256=WS1XhmOCUFO3tYUNJxk8INse2QM-VD1gM507xWRBRlY,345
+awaredb/api.py,sha256=iO7DGQpORr9v00YYPeEH5-1-XxOLvjEHNMPajNPSNQQ,2450
+awaredb/exceptions.py,sha256=FTD8cE6OZX6NCgnuwdpSDng_VuBgnSSLaSZJ05Cub-g,1983
+awaredb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+awaredb/typing.py,sha256=VmXCTHFx9Jcjm1fCAYF8WshlZZudFwdSHuAS9v196IA,1186
+awaredb/mixins/__init__.py,sha256=R1sckB16TE68qfdqyYcJEGN0WKwAmrnp1k5gh1Dr1Xw,312
+awaredb/mixins/analyses.py,sha256=S-1MtP-z0lqOuJCKpbc5uU-XQsI31xiUJYWzG6LYuvc,3610
+awaredb/mixins/auth.py,sha256=BldS2xxQ8XsyaeJtkovPnAK6KgZ9PBvjjOsxz947X-o,1570
+awaredb/mixins/data.py,sha256=CuQ9PY1a7BcuLvPgDxBkEFI5x4OezZY9-Yj33Y2rQg0,2742
+awaredb/mixins/history.py,sha256=QqRGRqrCEZpDyeMH8-X2eAepLFT0ztTOWzLV8ZtRmk4,1415
+awaredb/mixins/http.py,sha256=JCjYXSYJmwFScaAaUGi7sZU165mUaL0nVY_FCJ6Uss0,4221
+awaredb/mixins/io.py,sha256=i4XJVGM2B0VWKqc48W7hfuYEivyZlMkgi5_cj3fLWeg,1801
+awaredb-0.1.1.dist-info/licenses/LICENSE,sha256=4ONJY9Y7UcYVWtQNV7ltTooadZYWXzlV3wnUdV1L-q8,1072
+awaredb-0.1.1.dist-info/METADATA,sha256=eNsmSfDHMckMFkoxi2htBfHzB52BvQZd65wwwn9mtao,8776
+awaredb-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+awaredb-0.1.1.dist-info/top_level.txt,sha256=V8cxa4yPWZoTfLt-TLzvQ4w1zWSzFwc-q7ywFBRqyWM,8
+awaredb-0.1.1.dist-info/RECORD,,

awaredb-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

awaredb-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nelson Monteiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

awaredb-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+awaredb