endeavor-nova-wire 0.1.0.dev394__tar.gz

endeavor_nova_wire-0.1.0.dev394/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Endeavor AI, Inc.
+
+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.

endeavor_nova_wire-0.1.0.dev394/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: endeavor-nova-wire
+Version: 0.1.0.dev394
+Summary: Nova wire models: the request and response shapes of the Nova API.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: email-validator>=2
+Requires-Dist: pydantic>=2.11,<3
+Requires-Python: >=3.14

endeavor_nova_wire-0.1.0.dev394/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "endeavor-nova-wire"
+version = "0.1.0.dev394"
+description = "Nova wire models: the request and response shapes of the Nova API."
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = [
+    "email-validator>=2",
+    "pydantic>=2.11,<3",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "nova_wire"

endeavor_nova_wire-0.1.0.dev394/pyproject.toml.orig

@@ -0,0 +1,18 @@
+[project]
+name = "endeavor-nova-wire"
+version = "0.1.0.dev394"
+description = "Nova wire models: the request and response shapes of the Nova API."
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = [
+    "email-validator>=2",
+    "pydantic>=2.11,<3",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "nova_wire"

endeavor_nova_wire-0.1.0.dev394/src/nova_wire/__init__.py

@@ -0,0 +1,4 @@
+"""Request and response models shared by the Nova API and its clients.
+
+Pure pydantic: this package has no logic, so the CLI can depend on it alone.
+"""

endeavor_nova_wire-0.1.0.dev394/src/nova_wire/access.py

@@ -0,0 +1,105 @@
+"""App access over the wire: the synced spec, members, app sessions and ``/me``."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class AccessSync(BaseModel):
+    spec: dict[str, Any]
+    """The app's ``access.yaml``, as data."""
+    allow_breaking: bool = False
+    """Allow narrowing roles that have members. Removing them is never allowed."""
+
+
+class AccessOut(BaseModel):
+    spec: dict[str, Any] | None
+    version: str | None
+    synced_at: datetime | None
+    synced_by: str | None
+    members: dict[str, int] = {}
+    """Members per role id."""
+
+
+class AccessSynced(AccessOut):
+    diff: dict[str, Any]
+    warnings: list[str] = []
+
+
+class MemberGrant(BaseModel):
+    role: str = Field(min_length=1, max_length=64)
+    attributes: dict[str, str] = {}
+
+
+class AppMemberOut(BaseModel):
+    user_id: str
+    email: str
+    name: str
+    role: str
+    attributes: dict[str, str]
+    created_at: datetime
+
+
+class EffectiveAccess(BaseModel):
+    """What one member can do and read in an app, attributes filled in."""
+
+    user_id: str
+    email: str
+    name: str
+    app: str
+    role: str
+    via: str
+    """``member`` for an app member; ``tenant-admin`` for an org owner or admin."""
+    permissions: list[str]
+    max_sensitivity: str
+    objects: list[str] | None
+    """Readable object types; ``None`` for every type."""
+    rows: dict[str, str]
+    """Object type → the row filter applied, with the member's attributes bound."""
+    attributes: dict[str, str]
+
+
+class AppLogin(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class AppSession(BaseModel):
+    token: str
+    expires_at: datetime
+    access: EffectiveAccess
+
+
+# -- checks on an access.yaml the client holds -----------------------------------------
+
+
+class AccessCheck(BaseModel):
+    spec: str
+    """The ``access.yaml`` text."""
+    code_permissions: dict[str, list[str]] | None = None
+    """Permission → where the app's code requires it (``file:line``)."""
+    ontology_yaml: str | None = None
+    """Check against this spec; defaults to the org's published version, if any."""
+    snapshot_id: str | None = None
+    ontology_source: str | None = None
+    """Echoed back as ``ontology`` so the caller can say what was checked against."""
+    app: str | None = None
+    """The app's slug: once registered with object types of its own, those are
+    merged into the ontology checked against, so roles may name them."""
+
+
+class AccessExplain(AccessCheck):
+    role: str
+    attributes: dict[str, str] = Field(default_factory=dict)
+    query: dict[str, Any] | None = None
+
+
+class AccessCompare(BaseModel):
+    spec: str
+    first: str
+    second: str
+    ontology_yaml: str | None = None
+    app: str | None = None

endeavor_nova_wire-0.1.0.dev394/src/nova_wire/actions.py

@@ -0,0 +1,153 @@
+"""Actions over the wire: what an app's caller may run, one call, and its audit."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ActionParamOut(BaseModel):
+    id: str
+    label: str
+    description: str | None = None
+    type: str
+    format: str | None = None
+    """``file`` when the parameter takes the id of a file uploaded to the app."""
+    values: list[str] | None = None
+    required: bool = True
+    min: float | None = None
+    max: float | None = None
+    min_length: int | None = None
+    max_length: int | None = None
+    pattern: str | None = None
+    items: ActionParamOut | None = None
+    """For a ``list``: what each item is."""
+    fields: list[ActionParamOut] | None = None
+    """For an ``object``: its fields."""
+    max_items: int | None = None
+    max_bytes: int | None = None
+
+
+class ActionAgentOut(BaseModel):
+    """For an agent action: what Nova's agent reads and writes through."""
+
+    reads: list[str]
+    """The object types it may query, the object's own among them."""
+    writes: str
+    """The action it ends with, run as the app."""
+    triggers: list[str] = Field(default_factory=list)
+    """When it also runs without being asked: ``created``, for each new object
+    of its type."""
+
+
+class ActionOut(BaseModel):
+    """One action of the app's ontology, and whether the caller may run it."""
+
+    id: str
+    label: str
+    description: str | None = None
+    object_type: str
+    effect: str
+    """``create``, ``modify``, ``delete`` or ``agent``."""
+    permission: str | None = None
+    """The permission a role needs; ``None`` means every permission (``*``)."""
+    params: list[ActionParamOut] = Field(default_factory=list)
+    writes: list[str] = Field(default_factory=list)
+    """The properties it sets."""
+    key: list[str] = Field(default_factory=list)
+    """The columns a modify or delete identifies the object by."""
+    allowed: bool
+    """Whether the caller's role may run it."""
+    tool: str | None = None
+    """The tool it writes to (``linear``), for an action that calls one of a
+    synced type's operations: it changes data outside Nova."""
+    calls: str | None = None
+    """That operation, ``<tool>.<operation>``."""
+    agent: ActionAgentOut | None = None
+    """For an agent action: Nova carries it out with the organization's model,
+    in the background; its run is at ``agent_runs/{run_id}``."""
+
+
+class ActionRun(BaseModel):
+    """One call: the parameters, and the object's key for modify and delete."""
+
+    params: dict[str, Any] = Field(default_factory=dict)
+    key: Any = None
+    """The primary key value, a list for a composite key, or a mapping by column."""
+    dry_run: bool = False
+    """Compile and report the SQL (or the tool's requests) without running it."""
+    idempotency_key: str | None = Field(
+        default=None, min_length=1, max_length=128, pattern=r"^[A-Za-z0-9_.:-]+$"
+    )
+    """The same key again returns the first run's result instead of writing
+    twice, and resumes a tool write whose answer was lost. Without one, each
+    call is its own run."""
+    force: bool = False
+    """Resend a tool write whose outcome is unknown and that can't be looked
+    up, accepting that it may be done twice."""
+
+
+class ToolRequestOut(BaseModel):
+    """One request a tool write sent (or, for a dry run, would send)."""
+
+    step: str
+    method: str
+    url: str
+    status: int | None = None
+    """The tool's answer; ``None`` for a dry run, or when none came."""
+    body: Any = None
+    """For a dry run: what would be sent."""
+    found: bool = False
+    """Already done: a retried run found it (``find``) instead of sending it."""
+
+
+class ActionResultOut(BaseModel):
+    action: str
+    object_type: str
+    effect: str
+    status: str
+    """``ok``; ``unchanged`` when a modify or delete found nothing to change;
+    ``dry_run`` when nothing ran; ``queued`` for an agent action, which Nova
+    carries out in the background (``run_id``)."""
+    rows: int
+    key: dict[str, Any] | None = None
+    """The key of the object written, when the warehouse (or the tool) reports
+    it."""
+    sql: str = ""
+    elapsed_ms: int
+    tool: str | None = None
+    """For a tool write: the tool."""
+    requests: list[ToolRequestOut] = Field(default_factory=list)
+    """For a tool write: what was sent, in order."""
+    idempotency_key: str | None = None
+    """The run's key: retry with it to resume a write whose answer was lost."""
+    run_id: str | None = None
+    """For an agent action: the run to poll (``GET .../agent-runs/{id}``)."""
+
+
+class ActionAuditOut(BaseModel):
+    id: str
+    principal: str
+    app_id: str | None = None
+    app_role: str | None = None
+    ontology_version: str | None = None
+    action: str
+    object_type: str
+    effect: str
+    params: dict[str, Any]
+    key: dict[str, Any] | None = None
+    sql: str | None = None
+    status: str
+    """``ok``, ``unchanged``, ``error``, ``denied``; for a tool write also
+    ``pending`` (being sent) and ``unknown`` (sent, but no answer said whether
+    it was done)."""
+    rows: int | None = None
+    elapsed_ms: int | None = None
+    error: str | None = None
+    tool: str | None = None
+    idempotency_key: str | None = None
+    steps: list[dict[str, Any]] | None = None
+    """For a tool write: each request's step, method, URL and status."""
+    at: datetime

endeavor_nova_wire-0.1.0.dev394/src/nova_wire/agents.py

@@ -0,0 +1,54 @@
+"""Agent runs: an agent action carried out by Nova, kept with what it did."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from nova_wire.actions import ActionResultOut
+from nova_wire.snapshots import JobStatus
+
+type AgentStepKind = Literal["query", "note", "write", "error"]
+
+
+class AgentStepOut(BaseModel):
+    """One thing the agent did: a query it ran, what it said, the write it
+    asked for, or a call Nova turned down (which it then fixed)."""
+
+    kind: AgentStepKind
+    text: str | None = None
+    """For a note, what the model said; for an error, what was wrong."""
+    query: dict[str, Any] | None = None
+    """For a query, the query it ran (the ontology's IR)."""
+    rows: int | None = None
+    """For a query, how many rows came back."""
+    params: dict[str, Any] | None = None
+    """For a write, what it gave the action."""
+    elapsed_ms: int | None = None
+
+
+class AgentRunOut(BaseModel):
+    id: str
+    action: str
+    key: str
+    """The primary key of the object it read."""
+    status: JobStatus
+    trigger: Literal["person", "created"]
+    """``person``: someone ran the action; ``created``: a new object of its
+    type started it."""
+    requested_by: str
+    """Who ran the action, or created the object; ``nova:inbox`` for a message
+    the inbox received."""
+    model: str | None = None
+    files: list[str] = Field(default_factory=list)
+    """The names of the files it was shown."""
+    steps: list[AgentStepOut] | None = None
+    """What it did, in order; ``None`` for a caller whose role may not read
+    the object's confidential properties."""
+    written: ActionResultOut | None = None
+    """The write it ended with, once done."""
+    error: str | None = None
+    created_at: datetime
+    finished_at: datetime | None = None

endeavor_nova_wire-0.1.0.dev394/src/nova_wire/apps.py

@@ -0,0 +1,253 @@
+"""Registered apps (code projects from ``nova create-app``) and their hosted
+sites."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class AppRegister(BaseModel):
+    slug: str = Field(pattern=r"^[a-z0-9][a-z0-9-]{1,62}$")
+    name: str = Field(min_length=1, max_length=200)
+    repo_url: str | None = None
+    path: str | None = None
+    """The app's folder in its repo: ``apps/<slug>/``, or ``/`` for the repo's
+    root. Unset: ``apps/<slug>/``."""
+
+
+class AppUpdate(BaseModel):
+    repo_url: str | None = None
+    """Where the app's code lives: a GitHub repository URL; null clears it."""
+    path: str | None = None
+    """The app's folder in that repo (``apps/<slug>/``, ``/`` for its root),
+    where Code and agents work on it; null puts it back to ``apps/<slug>/``."""
+    model_token_budget: int | None = Field(default=None, ge=1)
+    """Tokens (input and output) the app may spend through the model gateway
+    each calendar month; null lifts the limit."""
+
+
+class AppOut(BaseModel):
+    id: str
+    slug: str
+    name: str
+    repo_url: str | None
+    path: str = ""
+    """The app's folder in its repo: ``apps/<slug>/``, or ``/`` for the root."""
+    token_prefix: str | None
+    created_at: datetime
+    site_url: str | None = None
+    """Where the hosted site's production is served, once a version is there."""
+    staging_version: str | None = None
+    production_version: str | None = None
+    model_token_budget: int | None = None
+    """Tokens the app may spend through the model gateway each calendar
+    month; null means no limit."""
+
+
+class AppRegistered(AppOut):
+    token: str
+    """The app's own API token, shown once."""
+
+
+# --- hosted sites ---------------------------------------------------------------------
+#
+# An app's frontend build is uploaded as a zip of its dist folder and kept as a
+# version. The site has two environments, staging and production, each serving
+# one released version at ``/sites/{org}/{slug}/`` (production by default;
+# ``?env=staging`` switches a browser to staging, ``?version=`` previews any
+# version). Limits match what a static host wants: 1,000 files and 20 MB unpacked.
+
+SITE_MAX_FILES = 1000
+SITE_MAX_BYTES = 20 * 1024 * 1024
+SITE_VERSION_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+"""A site version's name: what `nova site deploy` uploads and ``?version=`` names."""
+
+SiteEnvironment = Literal["staging", "production"]
+SITE_ENVIRONMENTS: tuple[SiteEnvironment, ...] = ("staging", "production")
+"""In pipeline order: a version goes to staging, then production."""
+
+
+class SiteVersionOut(BaseModel):
+    id: str
+    version: str
+    files: int
+    bytes: int
+    uploaded_by: str | None
+    notes: str | None
+    environments: list[SiteEnvironment]
+    """Where this version is released; empty when only uploaded."""
+    backend: bool = False
+    """Whether the app's backend was uploaded with it, to run on the platform at
+    ``/sites/{org}/{slug}/api/``."""
+    created_at: datetime
+    preview_url: str
+
+
+class SiteReleaseOut(BaseModel):
+    """One release of a version to an environment, newest first in ``SiteOut``."""
+
+    id: str
+    environment: SiteEnvironment
+    version: str
+    released_by: str | None
+    notes: str | None
+    at: datetime
+    current: bool
+    """Still what the environment serves."""
+
+
+class SiteOut(BaseModel):
+    app: str
+    url: str
+    """Where production is served (404 until a version is released there)."""
+    staging: SiteVersionOut | None
+    production: SiteVersionOut | None
+    versions: list[SiteVersionOut]
+    """Newest first."""
+    releases: list[SiteReleaseOut]
+    """Newest first."""
+
+
+class SiteRelease(BaseModel):
+    """Serve ``version`` in ``environment`` from now on."""
+
+    version: str
+    environment: SiteEnvironment = "production"
+
+
+BACKEND_MAX_BYTES = 50 * 1024 * 1024
+"""The largest backend archive (source and lock file, no virtualenv)."""
+
+
+class FunctionEnvSet(BaseModel):
+    """Settings the hosted backend runs with (``nova site env set``), by name.
+    Values are kept encrypted and never shown again."""
+
+    values: dict[str, str] = Field(min_length=1)
+
+
+class FunctionEnvOut(BaseModel):
+    keys: list[str]
+    """The names set, in order."""
+    builtin: list[str]
+    """What Nova sets by itself: the API's URL, the app's token and names."""
+
+
+# --- an app's own object types -------------------------------------------------------
+
+
+class AppOntologyPublish(BaseModel):
+    """``apps/<slug>/ontology.yaml``: object types (and links, groups) the app adds
+    over its own warehouse tables or views. Links may name the organization's types."""
+
+    spec_yaml: str
+    force: bool = False
+    """Publish despite validation errors."""
+
+
+class AppOntologyCheck(BaseModel):
+    """``nova app ontology validate``: the fragment checked, nothing stored."""
+
+    valid: bool
+    org_version: str
+    snapshot_id: str | None
+    object_types: list[str]
+    link_types: list[str]
+    managed: list[str] = Field(default_factory=list)
+    """The object types whose tables Nova manages."""
+    plan: list[str] = Field(default_factory=list)
+    """The statements a publish would run on the managed database."""
+    errors: list[str]
+    warnings: list[str]
+
+
+class EffectiveOntologyOut(BaseModel):
+    """Everything an app's sessions read, merged into one spec."""
+
+    version: str
+    """``<org version>+<fragment version>``, or the organization's alone."""
+    spec: dict[str, Any]
+    """The merged ontology in the spec's own shape (``ontology.yaml`` as JSON)."""
+
+
+class AppOntologyOut(BaseModel):
+    app: str
+    version: str
+    """Content version of the fragment."""
+    org_version: str
+    """The organization's version it was merged with and checked against."""
+    snapshot_id: str | None
+    object_types: list[str]
+    link_types: list[str]
+    groups: list[str]
+    inputs: dict[str, list[str]]
+    """Per local table that is a warehouse view: the tables its definition reads."""
+    managed: list[str] = Field(default_factory=list)
+    """The object types whose tables Nova manages."""
+    migration: dict[str, list[str]] | None = None
+    """What this publish did to the managed database: the statements run, and
+    the types created, altered and unchanged."""
+    errors: list[str]
+    warnings: list[str]
+    published_by: str | None
+    published_at: datetime
+
+
+# --- an app's card ------------------------------------------------------------------
+
+
+class AppCardPublish(BaseModel):
+    """``apps/<slug>/card.yaml``: what the All Apps page shows for the app."""
+
+    spec_yaml: str
+    force: bool = False
+    """Publish despite validation errors."""
+
+
+class AppCardCheck(BaseModel):
+    """``nova app card validate``: the card checked, nothing stored."""
+
+    valid: bool
+    org_version: str | None
+    queries: list[str]
+    """Where the card runs a query: ``metric``, ``metric.delta``, ``trend``."""
+    errors: list[str]
+    warnings: list[str]
+
+
+class CardMetricData(BaseModel):
+    value: str
+    raw: float | str | None = None
+    delta: str | None = None
+    delta_tone: Literal["ok", "warn", "crit", "muted"] | None = None
+
+
+class CardTrendData(BaseModel):
+    values: list[float]
+    labels: list[str]
+
+
+class CardData(BaseModel):
+    """What the card's queries answered when they last ran."""
+
+    metric: CardMetricData | None = None
+    trend: CardTrendData | None = None
+    refreshed_at: datetime | None = None
+    elapsed_ms: int | None = None
+    errors: list[str] = Field(default_factory=list)
+
+
+class AppCardOut(BaseModel):
+    app: str
+    version: str
+    """Content version of the card."""
+    spec: dict[str, Any]
+    """The card as published, in the shape of ``card.yaml``."""
+    data: CardData
+    errors: list[str]
+    warnings: list[str]
+    published_by: str | None
+    published_at: datetime