open-ux 0.1.1__tar.gz

open_ux-0.1.1/.gitignore

@@ -0,0 +1,56 @@
+# Generated by hatch-vcs
+packages/mcp/src/open_ux/_version.py
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+*.pem
+id_rsa
+id_ed25519
+.fly/
+
+# Hosted ops live in the private repo. Copy locally to deploy; do not commit.
+/fly.toml
+/railway.toml
+
+# Local hosted store
+data/
+*.sqlite
+*.sqlite-journal
+
+# Editor / agent local (never publish chats or transcripts)
+.cursor/
+.claude/
+.codex/
+agent-transcripts/
+*.jsonl
+
+# OS / editors
+.DS_Store
+*.swp
+.idea/
+.vscode/

open_ux-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yonatan Lev Ari
+
+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.

open_ux-0.1.1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: open-ux
+Version: 0.1.1
+Summary: Cited UX rules agents audit against — shared cited guidelines
+Project-URL: Homepage, https://open-ux.dev
+Project-URL: Repository, https://github.com/3dyonic/open-ux
+Project-URL: Issues, https://github.com/3dyonic/open-ux/issues
+Author: 3dyonic
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp<5,>=2.13
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: pydantic>=2
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Open UX
+
+![Open UX](https://raw.githubusercontent.com/3dyonic/open-ux/master/docs/readme-hero.svg)
+
+**Cited UX rules agents can list, fetch, and audit against.**
+
+Stop inventing UX guidance from memory. Open UX is a shared, open-source catalog of UX rules with citations, plus tools so an agent can find the right criteria and apply them to work it already has.
+
+**Hosted:** [open-ux.dev](https://open-ux.dev) · **License:** [MIT](https://github.com/3dyonic/open-ux/blob/master/LICENSE)
+
+## What it is
+
+A curated, machine-readable store of UX guidelines and a small tool surface so an agent can:
+
+1. **Browse situations** — pick a compose job (Situation Card) that matches the work
+2. **Fetch criteria** — get cited rules for that job (`rule`, `pass_when`, `fail_when`)
+3. **Apply locally** — the client judges the artifact; the host never takes the file and never returns pass/fail
+
+There is no server-side LLM. One shared catalog for every caller — an account unlocks the hosted API; it does not give you a private rulebook.
+
+## What it is not
+
+* A generative design copilot or “does this look good?” scorer
+* A WCAG / accessibility compliance checker (we do not claim conformance, contrast audits, or screen-reader naming)
+* A closed corpus — the catalog and server are open source; you can self-host the same tools
+
+## Features
+
+* **Cited catalog** — one JSON file per rule, with sources you can follow
+* **Public catalog site** — browse rules in the browser at [`/catalog`](https://open-ux.dev/catalog)
+* **Agent tools** — list / search / get guidelines; suggest situations; audit by need (job or ids)
+* **Hosted or self-host** — waitlist + API key on the hosted service, or stdio locally with no auth
+* **Privacy-minded hosted mode** — we do not store UI payloads or prompts; see [Privacy](https://open-ux.dev/privacy)
+
+## Quick start
+
+### Hosted
+
+1. Request access at [open-ux.dev/invite](https://open-ux.dev/invite)
+2. After approval, redeem your invite for a bearer API key (`uxmcp_…`)
+3. Point your MCP client at the hosted `/mcp` endpoint with that key
+4. Call `list_guidelines` or `audit` with a job (no file upload)
+
+Tools return **401** without a key.
+
+### Self-host
+
+```bash
+pip install open-ux
+python -m open_ux validate-catalog
+python -m open_ux stdio
+OPEN_UX_MODE=hosted python -m open_ux http
+```
+
+Browse the local site at `http://127.0.0.1:8080/catalog`. Point MCP clients at local stdio, or at hosted `/mcp` with a `uxmcp_` key.
+
+### Contribute from this repo
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e "packages/mcp[dev]"
+python -m open_ux validate-catalog
+python -m open_ux stdio
+```
+
+### Tests
+
+```bash
+cd packages/mcp && python -m pytest
+```
+
+### Claude plugin
+
+Thin client in [`clients/claude`](https://github.com/3dyonic/open-ux/tree/master/clients/claude). It connects to the catalog; it does not ship a second copy of the rules.
+
+## Agent tools
+
+| Tool | Purpose |
+| -- | -- |
+| `list_situations` | Page Situation Cards (optional container filter) |
+| `get_situation` | One Card plus facets / rule pointers |
+| `suggest_situations` | Rank Cards from task text (allowlisted) |
+| `list_guidelines` | Paged catalog index |
+| `search_guidelines` | Filter index by query / jobs / lane |
+| `get_guideline` | Full rule body by id |
+| `audit` | Say the need (`jobs` Card/container or `guideline_ids`); get matching criteria |
+
+`audit` accepts optional `query` and `limit` (default 10, max 50). It does **not** take a file target and does **not** return a host verdict. If nothing matches, you get an empty list and a note.
+
+## Catalog layout
+
+```
+catalog/
+  rules/{category}/{source}/   one JSON file per rule
+  index.json                   generated index
+  jobs.json                    Situation tree
+  schema.json                  rule schema
+  MANIFEST.md                  human map (no rule bodies)
+```
+
+Rules are never forked per tenant. Soft size budget ~50–100 KB; hard ceiling ~384 KB. Details: [`catalog/README.md`](https://github.com/3dyonic/open-ux/blob/master/catalog/README.md).
+
+## Repository layout
+
+```
+packages/mcp      Python server (FastMCP)
+catalog/          shared rules + schema
+clients/claude    thin Claude plugin
+docs/             privacy, assets
+```
+
+Python package: `open-ux` · npm / plugin scope: `@3dyonic/open-ux`
+
+## Hosted vs self-host
+
+|  | Hosted HTTP | Self-host (stdio) |
+| -- | -- | -- |
+| Auth | Waitlist → invite → bearer `uxmcp_` | None |
+| Rate limits | Per-key and per-IP on `/mcp` | None |
+| Telemetry | Aggregated usage (key hash, tools, rule ids) | Off |
+
+Privacy on the hosted product: [open-ux.dev/privacy](https://open-ux.dev/privacy) (Eng constraints also in [`docs/PRIVACY.md`](https://github.com/3dyonic/open-ux/blob/master/docs/PRIVACY.md)).
+
+## Contributing
+
+Issues and pull requests are welcome. Keep the catalog cited — every rule should point at a real source. Prefer small, reviewable PRs: one concern per change (catalog rows, server behavior, or docs).
+
+Before opening a PR:
+
+```bash
+python -m open_ux validate-catalog
+cd packages/mcp && python -m pytest
+```
+
+## License
+
+[MIT](https://github.com/3dyonic/open-ux/blob/master/LICENSE)

open_ux-0.1.1/README.md

@@ -0,0 +1,137 @@
+# Open UX
+
+![Open UX](docs/readme-hero.svg)
+
+**Cited UX rules agents can list, fetch, and audit against.**
+
+Stop inventing UX guidance from memory. Open UX is a shared, open-source catalog of UX rules with citations, plus tools so an agent can find the right criteria and apply them to work it already has.
+
+**Hosted:** [open-ux.dev](https://open-ux.dev) · **License:** [MIT](LICENSE)
+
+## What it is
+
+A curated, machine-readable store of UX guidelines and a small tool surface so an agent can:
+
+1. **Browse situations** — pick a compose job (Situation Card) that matches the work
+2. **Fetch criteria** — get cited rules for that job (`rule`, `pass_when`, `fail_when`)
+3. **Apply locally** — the client judges the artifact; the host never takes the file and never returns pass/fail
+
+There is no server-side LLM. One shared catalog for every caller — an account unlocks the hosted API; it does not give you a private rulebook.
+
+## What it is not
+
+* A generative design copilot or “does this look good?” scorer
+* A WCAG / accessibility compliance checker (we do not claim conformance, contrast audits, or screen-reader naming)
+* A closed corpus — the catalog and server are open source; you can self-host the same tools
+
+## Features
+
+* **Cited catalog** — one JSON file per rule, with sources you can follow
+* **Public catalog site** — browse rules in the browser at [`/catalog`](https://open-ux.dev/catalog)
+* **Agent tools** — list / search / get guidelines; suggest situations; audit by need (job or ids)
+* **Hosted or self-host** — waitlist + API key on the hosted service, or stdio locally with no auth
+* **Privacy-minded hosted mode** — we do not store UI payloads or prompts; see [Privacy](https://open-ux.dev/privacy)
+
+## Quick start
+
+### Hosted
+
+1. Request access at [open-ux.dev/invite](https://open-ux.dev/invite)
+2. After approval, redeem your invite for a bearer API key (`uxmcp_…`)
+3. Point your MCP client at the hosted `/mcp` endpoint with that key
+4. Call `list_guidelines` or `audit` with a job (no file upload)
+
+Tools return **401** without a key.
+
+### Self-host
+
+```bash
+pip install open-ux
+python -m open_ux validate-catalog
+python -m open_ux stdio
+OPEN_UX_MODE=hosted python -m open_ux http
+```
+
+Browse the local site at `http://127.0.0.1:8080/catalog`. Point MCP clients at local stdio, or at hosted `/mcp` with a `uxmcp_` key.
+
+### Contribute from this repo
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e "packages/mcp[dev]"
+python -m open_ux validate-catalog
+python -m open_ux stdio
+```
+
+### Tests
+
+```bash
+cd packages/mcp && python -m pytest
+```
+
+### Claude plugin
+
+Thin client in [`clients/claude`](clients/claude). It connects to the catalog; it does not ship a second copy of the rules.
+
+## Agent tools
+
+| Tool | Purpose |
+| -- | -- |
+| `list_situations` | Page Situation Cards (optional container filter) |
+| `get_situation` | One Card plus facets / rule pointers |
+| `suggest_situations` | Rank Cards from task text (allowlisted) |
+| `list_guidelines` | Paged catalog index |
+| `search_guidelines` | Filter index by query / jobs / lane |
+| `get_guideline` | Full rule body by id |
+| `audit` | Say the need (`jobs` Card/container or `guideline_ids`); get matching criteria |
+
+`audit` accepts optional `query` and `limit` (default 10, max 50). It does **not** take a file target and does **not** return a host verdict. If nothing matches, you get an empty list and a note.
+
+## Catalog layout
+
+```
+catalog/
+  rules/{category}/{source}/   one JSON file per rule
+  index.json                   generated index
+  jobs.json                    Situation tree
+  schema.json                  rule schema
+  MANIFEST.md                  human map (no rule bodies)
+```
+
+Rules are never forked per tenant. Soft size budget ~50–100 KB; hard ceiling ~384 KB. Details: [`catalog/README.md`](catalog/README.md).
+
+## Repository layout
+
+```
+packages/mcp      Python server (FastMCP)
+catalog/          shared rules + schema
+clients/claude    thin Claude plugin
+docs/             privacy, assets
+```
+
+Python package: `open-ux` · npm / plugin scope: `@3dyonic/open-ux`
+
+## Hosted vs self-host
+
+|  | Hosted HTTP | Self-host (stdio) |
+| -- | -- | -- |
+| Auth | Waitlist → invite → bearer `uxmcp_` | None |
+| Rate limits | Per-key and per-IP on `/mcp` | None |
+| Telemetry | Aggregated usage (key hash, tools, rule ids) | Off |
+
+Privacy on the hosted product: [open-ux.dev/privacy](https://open-ux.dev/privacy) (Eng constraints also in [`docs/PRIVACY.md`](docs/PRIVACY.md)).
+
+## Contributing
+
+Issues and pull requests are welcome. Keep the catalog cited — every rule should point at a real source. Prefer small, reviewable PRs: one concern per change (catalog rows, server behavior, or docs).
+
+Before opening a PR:
+
+```bash
+python -m open_ux validate-catalog
+cd packages/mcp && python -m pytest
+```
+
+## License
+
+[MIT](LICENSE)

open_ux-0.1.1/hatch_build.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    """Ship repo catalog/ in the wheel and sdist (not copied into git src/)."""
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        in_tree = Path(self.root) / "src" / "open_ux" / "data" / "catalog"
+        repo = Path(self.root).resolve().parent.parent / "catalog"
+        if (in_tree / "schema.json").is_file():
+            catalog = in_tree
+        elif (repo / "schema.json").is_file():
+            catalog = repo
+        else:
+            raise RuntimeError(
+                "catalog/schema.json not found; expected repo catalog/ or "
+                "sdist src/open_ux/data/catalog"
+            )
+        dest = (
+            "src/open_ux/data/catalog"
+            if self.target_name == "sdist"
+            else "open_ux/data/catalog"
+        )
+        build_data.setdefault("force_include", {})
+        build_data["force_include"][str(catalog)] = dest
+        if self.target_name == "sdist":
+            repo_readme = Path(self.root).resolve().parent.parent / "README.md"
+            if repo_readme.is_file():
+                build_data["force_include"][str(repo_readme)] = "README.md"

open_ux-0.1.1/hatch_metadata.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+_REPO = "https://github.com/3dyonic/open-ux"
+_RAW = "https://raw.githubusercontent.com/3dyonic/open-ux/master"
+
+_PYPI_LINKS = (
+    ("](docs/readme-hero.svg)", f"]({_RAW}/docs/readme-hero.svg)"),
+    ("](LICENSE)", f"]({_REPO}/blob/master/LICENSE)"),
+    ("](catalog/README.md)", f"]({_REPO}/blob/master/catalog/README.md)"),
+    ("](clients/claude)", f"]({_REPO}/tree/master/clients/claude)"),
+    ("](docs/PRIVACY.md)", f"]({_REPO}/blob/master/docs/PRIVACY.md)"),
+)
+
+
+def _for_pypi(text: str) -> str:
+    for src, dest in _PYPI_LINKS:
+        text = text.replace(src, dest)
+    return text
+
+
+class CustomMetadataHook(MetadataHookInterface):
+    """Use the public root README as the package description."""
+
+    def update(self, metadata: dict) -> None:
+        repo_readme = Path(self.root).resolve().parent.parent / "README.md"
+        local_readme = Path(self.root) / "README.md"
+        if repo_readme.is_file() and repo_readme.resolve() != local_readme.resolve():
+            readme = repo_readme
+        elif local_readme.is_file():
+            readme = local_readme
+        else:
+            raise RuntimeError("README.md not found for package metadata")
+        metadata["readme"] = {
+            "content-type": "text/markdown",
+            "text": _for_pypi(readme.read_text(encoding="utf-8")),
+        }

open_ux-0.1.1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "open-ux"
+dynamic = ["version", "readme"]
+description = "Cited UX rules agents audit against — shared cited guidelines"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "3dyonic" }]
+dependencies = [
+  "fastmcp>=2.13,<5",
+  "jsonschema>=4.23,<5",
+  "starlette>=0.40",
+  "uvicorn>=0.30",
+  "pydantic>=2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://open-ux.dev"
+Repository = "https://github.com/3dyonic/open-ux"
+Issues = "https://github.com/3dyonic/open-ux/issues"
+
+[project.scripts]
+open-ux = "open_ux.__main__:main"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+search_parent_directories = true
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/open_ux/_version.py"
+
+[tool.hatch.metadata.hooks.custom]
+path = "hatch_metadata.py"
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/open_ux"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/open_ux/static/favicon.svg" = "open_ux/static/favicon.svg"
+"src/open_ux/static/logo-mark.svg" = "open_ux/static/logo-mark.svg"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

open_ux-0.1.1/src/open_ux/__init__.py

@@ -0,0 +1,13 @@
+"""Open UX — cited UX rules agents audit against."""
+
+from __future__ import annotations
+
+try:
+    from open_ux._version import __version__
+except ImportError:  # pragma: no cover - editable tree before first build
+    try:
+        from importlib.metadata import version
+
+        __version__ = version("open-ux")
+    except Exception:
+        __version__ = "0.0.0"

open_ux-0.1.1/src/open_ux/__main__.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="open-ux", description="Open UX server")
+    parser.add_argument(
+        "mode",
+        nargs="?",
+        choices=("stdio", "http", "validate-catalog", "approve-invite"),
+        default=os.environ.get("OPEN_UX_MODE", "stdio"),
+    )
+    parser.add_argument("email", nargs="?", default="")
+    parser.add_argument("--host", default=os.environ.get("HOST", "0.0.0.0"))
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("PORT", os.environ.get("OPEN_UX_PORT", "8080"))),
+    )
+    args = parser.parse_args(argv)
+
+    if args.mode == "validate-catalog":
+        from open_ux.catalog import load_catalog
+
+        catalog = load_catalog()
+        print(
+            f"catalog ok version={catalog.version} "
+            f"guidelines={len(catalog.guidelines)} bytes={catalog.size_bytes}"
+        )
+        return 0
+
+    if args.mode == "approve-invite":
+        if not args.email:
+            print("usage: open-ux approve-invite EMAIL", file=sys.stderr)
+            return 2
+        from open_ux.auth import AuthError, approve_invite
+
+        try:
+            issued = approve_invite(args.email)
+        except AuthError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+        print(
+            json.dumps(
+                {
+                    "email": issued.email,
+                    "token": issued.token,
+                    "token_prefix": "inv_",
+                    "redeem_url": issued.redeem_url,
+                    "expires_at": issued.expires_at,
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    if args.mode == "stdio":
+        from open_ux.server import create_mcp
+
+        create_mcp(hosted=False).run(transport="stdio")
+        return 0
+
+    from open_ux.http_app import serve_http
+
+    serve_http(host=args.host, port=args.port)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

open_ux-0.1.1/src/open_ux/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = None