anna-app-core 0.2.0__tar.gz

anna_app_core-0.2.0/.gitignore

@@ -0,0 +1,170 @@
+# matrix agent repository
+matrix/
+
+# git diff files
+git.diff
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+# @anna-ai/app-runtime ships a hand-curated dist/ as the publishable
+# artifact (it is not a build output) — keep it tracked.
+!packages/anna-app-runtime/dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+# setuptools sdist MANIFEST (only at repo root — must NOT swallow the
+# packages/anna-app-schema/manifest/ schema bundle directory).
+/MANIFEST
+
+# PyInstaller
+# Anchored to repo root for the same reason — `*.manifest` is too broad
+# and was matching schema bundle files. Re-add specific paths if a real
+# PyInstaller .manifest ever ships.
+/*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project specific
+*.tmp
+*.bak
+
+# Security - RSA keys
+private_key.pem
+*.pem
+!public_key.pem
+
+scripts/nats_auth
+# Anna App runtime cache
+static/anna-apps-cache/

anna_app_core-0.2.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: anna-app-core
+Version: 0.2.0
+Summary: Anna App platform core: manifest schemas, RPC dispatcher, protocols, errors. Shared by matrix-nexus and the local-dev runtime.
+Project-URL: Documentation, https://github.com/talentai/matrix-nexus/blob/main/docs/design/anna-app-local-dev-and-test.md
+Author: Talent AI
+License: MIT
+Keywords: anna,anna-app,executa
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3.0,>=2.0
+Description-Content-Type: text/markdown
+
+# anna-app-core
+
+Shared protocol/error/ACL primitives **and** the Anna App RPC dispatcher,
+manifest schemas, and runtime helpers used by the [Anna App](https://github.com/talentai/matrix-nexus/blob/main/docs/design/anna-app-local-dev-and-test.md)
+platform.
+
+This package is the **stable contract surface** that both `matrix-nexus`
+(production host) and `anna-app-runtime-local` (local dev harness) depend on,
+so neither has to pull in the other's runtime.
+
+## What's here (v0.2.x)
+
+- **Manifest (Pydantic v2)** — `AppManifest`, `UiManifestSection`,
+  `UiBundleSection`, `UiViewSpec`, `UiHostApiSpec`, `UiSize`, `WindowViewMeta`,
+  `AppDevConfig`, `ManifestExecutaRef`
+- **Dispatcher** — `dispatch(method, params, *, manifest, store, ...)` (the
+  full JSON-RPC entry point; previously lived in `matrix-nexus`)
+- **Protocols** — `WindowStoreProtocol` (minimum surface RPC handlers expect
+  from a window store)
+- **Errors** — `HostRpcError`, `WindowError`, `WindowPermissionError`
+- **ACL** — `host_api_allows(manifest_dict, ns, method) -> bool`
+- **Runtime helpers** — `select_view`, `scopes_from_manifest`, `view_meta`
+- **Versions** — `DISPATCHER_VERSION`, `SDK_VERSION`, `__version__`
+
+## Versioning
+
+`0.2.0a2` — docs catch-up over `0.2.0a1` (no code changes); the dispatcher
++ Pydantic manifest extraction landed in `0.2.0a1`. Pin policy lives in the
+central [VERSIONS.md](../VERSIONS.md) and the operator runbook at
+[`docs/operations/anna-app-release-flow.md`](https://github.com/talentai/matrix-nexus/blob/main/docs/operations/anna-app-release-flow.md).

anna_app_core-0.2.0/README.md

@@ -0,0 +1,30 @@
+# anna-app-core
+
+Shared protocol/error/ACL primitives **and** the Anna App RPC dispatcher,
+manifest schemas, and runtime helpers used by the [Anna App](https://github.com/talentai/matrix-nexus/blob/main/docs/design/anna-app-local-dev-and-test.md)
+platform.
+
+This package is the **stable contract surface** that both `matrix-nexus`
+(production host) and `anna-app-runtime-local` (local dev harness) depend on,
+so neither has to pull in the other's runtime.
+
+## What's here (v0.2.x)
+
+- **Manifest (Pydantic v2)** — `AppManifest`, `UiManifestSection`,
+  `UiBundleSection`, `UiViewSpec`, `UiHostApiSpec`, `UiSize`, `WindowViewMeta`,
+  `AppDevConfig`, `ManifestExecutaRef`
+- **Dispatcher** — `dispatch(method, params, *, manifest, store, ...)` (the
+  full JSON-RPC entry point; previously lived in `matrix-nexus`)
+- **Protocols** — `WindowStoreProtocol` (minimum surface RPC handlers expect
+  from a window store)
+- **Errors** — `HostRpcError`, `WindowError`, `WindowPermissionError`
+- **ACL** — `host_api_allows(manifest_dict, ns, method) -> bool`
+- **Runtime helpers** — `select_view`, `scopes_from_manifest`, `view_meta`
+- **Versions** — `DISPATCHER_VERSION`, `SDK_VERSION`, `__version__`
+
+## Versioning
+
+`0.2.0a2` — docs catch-up over `0.2.0a1` (no code changes); the dispatcher
++ Pydantic manifest extraction landed in `0.2.0a1`. Pin policy lives in the
+central [VERSIONS.md](../VERSIONS.md) and the operator runbook at
+[`docs/operations/anna-app-release-flow.md`](https://github.com/talentai/matrix-nexus/blob/main/docs/operations/anna-app-release-flow.md).

anna_app_core-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anna-app-core"
+version = "0.2.0"
+description = "Anna App platform core: manifest schemas, RPC dispatcher, protocols, errors. Shared by matrix-nexus and the local-dev runtime."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Talent AI" }]
+keywords = ["anna", "anna-app", "executa"]
+
+# pydantic v2 is required for the AppManifest schema; everything else is
+# pure stdlib.
+dependencies = [
+    "pydantic>=2.0,<3.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/talentai/matrix-nexus/blob/main/docs/design/anna-app-local-dev-and-test.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anna_app_core"]

anna_app_core-0.2.0/src/anna_app_core/__init__.py

@@ -0,0 +1,60 @@
+"""anna-app-core: stable contract surface shared by matrix-nexus and
+anna-app-runtime-local.
+
+v0.2.0a1 — full extraction. The complete RPC dispatcher, manifest pydantic
+schemas, and helper functions now live here; matrix-nexus re-exports them
+for backward compatibility (see README.md).
+
+v0.2.0a2 — docs catch-up only (README rewrite). No API changes.
+"""
+
+from .acl import host_api_allows
+from .dispatcher import dispatch
+from .errors import HostRpcError, WindowError, WindowPermissionError
+from .manifest import (
+    AppDevConfig,
+    AppManifest,
+    ManifestExecutaRef,
+    UiBundleSection,
+    UiHostApiSpec,
+    UiManifestSection,
+    UiSize,
+    UiViewSpec,
+    WindowViewMeta,
+)
+from .protocols import WindowStoreProtocol
+from .runtime import scopes_from_manifest, select_view, view_meta
+from .versions import DISPATCHER_VERSION, SDK_VERSION
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # errors
+    "HostRpcError",
+    "WindowError",
+    "WindowPermissionError",
+    # protocols
+    "WindowStoreProtocol",
+    # acl
+    "host_api_allows",
+    # dispatcher
+    "dispatch",
+    # manifest schemas
+    "AppManifest",
+    "AppDevConfig",
+    "ManifestExecutaRef",
+    "UiBundleSection",
+    "UiHostApiSpec",
+    "UiManifestSection",
+    "UiSize",
+    "UiViewSpec",
+    "WindowViewMeta",
+    # runtime helpers
+    "select_view",
+    "scopes_from_manifest",
+    "view_meta",
+    # versions
+    "DISPATCHER_VERSION",
+    "SDK_VERSION",
+    "__version__",
+]

anna_app_core-0.2.0/src/anna_app_core/acl.py

@@ -0,0 +1,151 @@
+"""Host-API ACL check.
+
+Accepts either a typed ``AppManifest`` (preferred — production + harness)
+or a plain ``dict`` (e.g. JSON-loaded manifest before pydantic validation).
+
+Mirrors the pre-extraction implementation in
+``matrix-nexus/src/services/anna_app_runtime_service.py::host_api_allows``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Union
+
+from .manifest import AppManifest
+
+
+def _ui_host_api(
+    manifest: Union[AppManifest, dict[str, Any]],
+) -> dict[str, Any] | None:
+    """Return the ``ui.host_api`` mapping (ns -> list[method] | dict) or
+    ``None`` if the manifest has no UI section.
+
+    Note: most namespaces resolve to ``list[str]`` of allowed methods, but
+    ``agent`` is a structured dict (see ``AgentHostApiSpec``).
+    """
+    if isinstance(manifest, AppManifest):
+        if manifest.ui is None:
+            return None
+        api = manifest.ui.host_api
+        return {
+            "tools": api.tools,
+            "chat": api.chat,
+            "artifact": api.artifact,
+            "llm": api.llm,
+            "agent": api.agent.model_dump() if api.agent is not None else None,
+            "fs": api.fs,
+            "storage": api.storage,
+            "prefs": api.prefs,
+            "files": api.files,
+            "user_files": api.user_files,
+        }
+    ui = manifest.get("ui") if isinstance(manifest, dict) else None
+    if ui is None:
+        return None
+    return ui.get("host_api") or {}
+
+
+def host_api_allows(
+    manifest: Union[AppManifest, dict[str, Any]],
+    ns: str,
+    method: str,
+) -> bool:
+    """Return ``True`` iff ``ns.method`` is granted by the manifest's ACL.
+
+    `window.*` is always granted. ``tools.invoke`` and ``tools.list`` are
+    granted whenever the ``tools`` set is non-empty (per-tool gating happens
+    inside the handler). ``agent.session.*`` is granted when at least one
+    submode (``auto`` / ``fixed``) is enabled — the handler validates the
+    selected submode against the structured spec.
+    """
+    if ns == "window":
+        return True
+    api_map = _ui_host_api(manifest)
+    if api_map is None:
+        return False
+    methods = api_map.get(ns)
+    if not methods:
+        return False
+    if ns == "agent":
+        # Structured form: ``{session: {auto: bool, fixed: {client_ids:[]}}, tools: [...]}``.
+        if not method.startswith("session."):
+            return False
+        sess = methods.get("session") if isinstance(methods, dict) else None
+        if not isinstance(sess, dict):
+            return False
+        auto_on = bool(sess.get("auto"))
+        fixed_on = bool(sess.get("fixed"))
+        return auto_on or fixed_on
+    if isinstance(methods, list):
+        if "*" in methods:
+            return True
+        if method in methods:
+            return True
+    if ns == "tools" and method in ("invoke", "list"):
+        return True
+    return False
+
+
+# -----------------------------------------------------------------------------
+# Scope capability — manifest.host_capabilities
+# -----------------------------------------------------------------------------
+
+
+_ACTIONS = ("read", "write")
+_SCOPES = ("user", "app", "tool")
+
+
+def _host_caps_list(
+    manifest: Union[AppManifest, dict[str, Any]],
+) -> list[str]:
+    """Normalise ``host_capabilities`` to a flat list[str]. Tolerates dict form."""
+    if isinstance(manifest, AppManifest):
+        raw: Any = list(manifest.host_capabilities or [])
+    else:
+        raw = manifest.get("host_capabilities") if isinstance(manifest, dict) else None
+        raw = raw or []
+    if isinstance(raw, dict):
+        return [str(k) for k, v in raw.items() if v]
+    if isinstance(raw, (list, tuple)):
+        return [str(c) for c in raw]
+    return []
+
+
+def host_capability_allows_scope(
+    manifest: Union[AppManifest, dict[str, Any]],
+    scope: str,
+    action: str,
+    *,
+    cross_owner: bool = False,
+) -> bool:
+    """Return ``True`` iff the manifest grants APS access to ``(scope, action)``.
+
+    ``scope`` is one of ``user`` / ``app`` / ``tool``; ``action`` is ``read`` or
+    ``write``. ``cross_owner`` is ``True`` when the call targets a different
+    ``owner_id`` than the calling iframe (e.g. another app's ``scope=app``
+    bucket). Self-owned ``scope=app`` access stays granted by the legacy
+    ``aps.kv`` capability.
+
+    Capability strings recognised:
+
+    * ``aps.scope.admin``                       → grants everything.
+    * ``aps.scope.<scope>.<action>``            → exact match.
+    * ``aps.kv``                                → ``scope=app`` self-owned only.
+    """
+    if scope not in _SCOPES:
+        return False
+    if action not in _ACTIONS:
+        return False
+    caps = set(_host_caps_list(manifest))
+    if "aps.scope.admin" in caps:
+        return True
+    fine = f"aps.scope.{scope}.{action}"
+    if fine in caps:
+        return True
+    # Legacy: ``aps.kv`` covers self-owned scope=app reads & writes.
+    if scope == "app" and not cross_owner and ("aps.kv" in caps or "aps" in caps):
+        return True
+    return False
+
+
+__all__ = ["host_api_allows", "host_capability_allows_scope"]