forgeui 0.1.0a2__tar.gz

forgeui-0.1.0a2/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.venv
+__pycache__
+*.py[cod]
+*.db
+*.sqlite*
+.env
+/data
+tests
+docs
+examples

forgeui-0.1.0a2/.env.example

@@ -0,0 +1,28 @@
+FORGEUI_ENVIRONMENT=development
+FORGEUI_HOST=0.0.0.0
+FORGEUI_PORT=8000
+FORGEUI_DATABASE_URL=sqlite:////data/forgeui.db
+FORGEUI_DATA_DIR=/data
+# Generate unique production values, for example: openssl rand -hex 32
+FORGEUI_SECRET_KEY=replace-with-a-long-random-value
+FORGEUI_ADMIN_TOKEN=replace-with-an-admin-token
+FORGEUI_ALLOW_PUBLIC_READ=true
+# Set true behind HTTPS. Compose defaults this to true.
+FORGEUI_SECURE_COOKIES=false
+# JSON list, not a comma-separated string.
+FORGEUI_TRUSTED_HOSTS=["localhost","127.0.0.1"]
+# Exact origins permitted to frame /embed and /artifact views. Keep self-only unless needed.
+FORGEUI_FRAME_ANCESTORS=["'self'"]
+
+# Ollama is expected to run separately. On Docker Desktop this reaches the host.
+FORGEUI_OLLAMA_BASE_URL=http://host.docker.internal:11434
+FORGEUI_OLLAMA_MODEL=qwen3.5:9b
+FORGEUI_OLLAMA_CONNECT_TIMEOUT_SECONDS=5
+FORGEUI_OLLAMA_RESPONSE_TIMEOUT_SECONDS=90
+FORGEUI_OLLAMA_MAX_CONCURRENCY=1
+FORGEUI_OLLAMA_TEMPERATURE=0.1
+FORGEUI_OLLAMA_SEED=42
+
+FORGEUI_ASSET_MODE=self-hosted
+FORGEUI_LOG_LEVEL=INFO
+FORGEUI_JSON_LOGS=false

forgeui-0.1.0a2/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync --frozen --all-extras
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy src/forgeui
+      - run: uv run bandit -q -r src/forgeui
+      - run: >-
+          uv run pytest -q -m "not browser and not docker and not ollama"
+          --cov=forgeui --cov-report=term-missing:skip-covered
+      - run: uv build
+      - run: uv run twine check dist/*
+      - name: Smoke-test base, HTTP adapter, mounted-web, and complete wheels
+        run: |
+          WHEEL=$(find dist -name 'forgeui-*.whl' -print -quit)
+          WHEEL_BYTES=$(wc -c < "$WHEEL")
+          if [ "$WHEEL_BYTES" -gt $((128 * 1024)) ]; then
+            echo "Wheel size $WHEEL_BYTES bytes exceeds the 128 KiB budget"
+            exit 1
+          fi
+          PACKAGE_SMOKE_DIR=$(mktemp -d)
+          uv venv "$PACKAGE_SMOKE_DIR/base"
+          uv pip install --python "$PACKAGE_SMOKE_DIR/base/bin/python" "$WHEEL"
+          "$PACKAGE_SMOKE_DIR/base/bin/python" -c \
+            "import importlib.util; from forgeui.a2ui import adapt_a2ui_jsonl; from forgeui.renderer import Renderer; from forgeui.validation import validate_manifest; assert importlib.util.find_spec('fastapi') is None; assert importlib.util.find_spec('httpx') is None; assert importlib.util.find_spec('sqlalchemy') is None"
+          if BASE_CLI_OUTPUT=$("$PACKAGE_SMOKE_DIR/base/bin/forgeui" serve 2>&1); then
+            echo "Base CLI unexpectedly started without the app extra"
+            exit 1
+          fi
+          if ! grep -q "forgeui\[app\]" <<< "$BASE_CLI_OUTPUT"; then
+            echo "Base CLI did not explain the missing app extra"
+            exit 1
+          fi
+          uv venv "$PACKAGE_SMOKE_DIR/http"
+          uv pip install --python "$PACKAGE_SMOKE_DIR/http/bin/python" "${WHEEL}[http]"
+          "$PACKAGE_SMOKE_DIR/http/bin/python" -c \
+            "import importlib.util; from forgeui.sources.http import HttpDataSource; assert importlib.util.find_spec('sqlalchemy') is None"
+          uv venv "$PACKAGE_SMOKE_DIR/web"
+          uv pip install --python "$PACKAGE_SMOKE_DIR/web/bin/python" "${WHEEL}[web]"
+          "$PACKAGE_SMOKE_DIR/web/bin/python" -c \
+            "import importlib.util; from forgeui.app import mount_forgeui; from forgeui.data import Database; assert importlib.util.find_spec('httpx') is None"
+          uv venv "$PACKAGE_SMOKE_DIR/app"
+          uv pip install --python "$PACKAGE_SMOKE_DIR/app/bin/python" "${WHEEL}[app]"
+          "$PACKAGE_SMOKE_DIR/app/bin/python" -c \
+            "from forgeui.app import create_app; from forgeui.data import Database; from forgeui.llm import OllamaProvider"
+
+  compatibility:
+    name: Python ${{ matrix.python-version }} compatibility
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --frozen --all-extras
+      - run: uv run pytest -q -m "not browser and not docker and not ollama"

forgeui-0.1.0a2/.github/workflows/publish.yml

@@ -0,0 +1,82 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify distribution
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Check release tag matches package version
+        run: |
+          PACKAGE_VERSION=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          RELEASE_VERSION=${GITHUB_REF_NAME#v}
+          if [ "$PACKAGE_VERSION" != "$RELEASE_VERSION" ]; then
+            echo "Release tag $GITHUB_REF_NAME does not match package version $PACKAGE_VERSION"
+            exit 1
+          fi
+      - run: uv sync --frozen --all-extras
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy src/forgeui
+      - run: uv run bandit -q -r src/forgeui
+      - run: >-
+          uv run pytest -q -m "not browser and not docker and not ollama"
+          --cov=forgeui --cov-report=term-missing:skip-covered
+      - run: uv build
+      - run: uv run twine check dist/*
+      - name: Enforce wheel budget
+        run: |
+          WHEEL=$(find dist -name 'forgeui-*.whl' -print -quit)
+          WHEEL_BYTES=$(wc -c < "$WHEEL")
+          if [ "$WHEEL_BYTES" -gt $((128 * 1024)) ]; then
+            echo "Wheel size $WHEEL_BYTES bytes exceeds the 128 KiB budget"
+            exit 1
+          fi
+      - name: Smoke-test the exact release wheel
+        run: |
+          WHEEL=$(find dist -name 'forgeui-*.whl' -print -quit)
+          RELEASE_SMOKE_DIR=$(mktemp -d)
+          uv venv "$RELEASE_SMOKE_DIR/venv"
+          uv pip install --python "$RELEASE_SMOKE_DIR/venv/bin/python" "${WHEEL}[app]"
+          "$RELEASE_SMOKE_DIR/venv/bin/python" -c \
+            "from forgeui import __version__; from forgeui.app import create_app; assert __version__ == '${GITHUB_REF_NAME#v}'"
+      - name: Store distributions
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish verified distribution
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/forgeui
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

forgeui-0.1.0a2/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.env
+.hypothesis/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+htmlcov/
+playwright-report/
+test-results/
+/data/
+*.db
+*.db-shm
+*.db-wal
+.DS_Store
+
+# Machine-specific agent instructions may contain local paths or other private context.
+AGENTS.local.md

forgeui-0.1.0a2/.impeccable.md

@@ -0,0 +1,56 @@
+## Design Context
+
+### Users
+
+ForgeUI serves two connected groups:
+
+- Operations engineers, fleet administrators, and support staff who scan device health, identify
+  exceptions, and act under time pressure. They need dense information to remain legible and
+  trustworthy at a glance.
+- Application developers who embed ForgeUI into a FastAPI service and use a small local model to
+  assemble dashboards from an approved catalog. They need the generated UI to feel intentional
+  without granting the model arbitrary styling or executable output.
+
+The first job is to turn a normalized device-health report into a useful fleet overview, resource
+pressure view, or device detail page. Existing dashboards must remain useful when Ollama is
+offline.
+
+### Brand Personality
+
+Calm, dependable, precise. The interface should create confidence through restraint, clear status
+hierarchy, exact labels, and visible system state. Urgency comes from actual warning and critical
+data, not decorative intensity. Copy is concise, direct, and helpful.
+
+### Aesthetic Direction
+
+The default visual language is a compact system-font interface with deep teal actions,
+cool-neutral page and card surfaces, 6-pixel control/card radii, restrained
+elevation, strong table structure, and a charcoal application bar with a teal rule. It should feel
+like a dependable operational tool, not an editorial showcase or a generic marketing dashboard.
+
+Support light, dark, and system themes as first-class modes. Dark mode uses distinct lifted
+surfaces instead of inverting the light palette. Use the system stack
+(`system-ui`, `-apple-system`, `Segoe UI`, `Roboto`) for predictable embedding. Avoid
+neon-on-dark styling, cyan/purple gradients, glassmorphism, excessive rounding and shadows,
+nested cards, ornamental sparklines, gradient text, oversized display headings, and large icon
+tiles.
+
+The four safe model-selectable design profiles may vary density and composition, but all inherit
+the same semantic tokens, accessible status language, typography discipline, and trusted shell:
+
+- `ops-compact`: dense, ruled, exception-first monitoring.
+- `signal-cards`: stronger visual metric and chart emphasis without decorative effects.
+- `executive-summary`: spacious synthesis with fewer simultaneous details.
+- `calm-neutral`: quiet reading and detail review.
+
+### Design Principles
+
+1. Signal before decoration. Color, weight, and motion explain state changes or urgency.
+2. Dense does not mean cramped. Use varied rhythm, hairline separators, and tabular alignment to
+   make operational data scannable.
+3. The shell is trusted. Theme controls, focus behavior, error states, and interaction patterns do
+   not depend on model output.
+4. Profiles are complete systems, not bags of knobs. The model chooses a tested bundle and cannot
+   mix arbitrary colors, classes, fonts, radii, or layout values.
+5. Accessibility is visible quality. Preserve semantic HTML, 44-pixel touch targets, keyboard
+   focus, non-color status cues, reduced motion, AA contrast, and mobile adaptations.

forgeui-0.1.0a2/.python-version

@@ -0,0 +1 @@
+3.12

forgeui-0.1.0a2/AGENTS.local.example.md

@@ -0,0 +1,6 @@
+# ForgeUI local agent rules
+
+Copy this file to `AGENTS.local.md` and add only machine-specific instructions that should not be
+published, such as absolute paths to adjacent checkouts. `AGENTS.local.md` is ignored by Git.
+
+- Treat `<absolute-path-to-adjacent-checkout>` as read-only; it may contain user changes.

forgeui-0.1.0a2/AGENTS.md

@@ -0,0 +1,14 @@
+# ForgeUI agent rules
+
+- If `AGENTS.local.md` exists, read it before starting work. It contains machine-specific rules and
+  must remain untracked.
+- ForgeUI is a standalone Python project.
+- Keep the model boundary strict: manifests never contain HTML, JavaScript, CSS, Tailwind classes, URLs, SQL, file paths, or arbitrary executable expressions.
+- Keep the component catalog, Pydantic models, JSON Schema, renderer dispatch, and prompt documentation in sync.
+- Reject invalid manifests before persistence or rendering. Do not silently weaken security rules while repairing output.
+- Prefer server-owned state, immutable manifest revisions, and trusted capability/data-source registries.
+- Keep UI behavior accessible: semantic HTML, visible focus, labelled inputs, keyboard support, reduced motion, and tested light/dark themes.
+- Treat adjacent checkouts as read-only; they may contain user changes.
+- Agents working concurrently must have disjoint file ownership.
+- Run focused tests for changed code and report exact commands and failures.
+- Avoid vague production-readiness claims. State implemented controls, checks, and remaining risks precisely.

forgeui-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to ForgeUI are documented here. Versions follow
+[PEP 440](https://peps.python.org/pep-0440/).
+
+## 0.1.0a2 — 2026-09-01
+
+First published public alpha.
+
+### Fixed
+
+- Raised light-theme timeline timestamp contrast above the WCAG AA text threshold.
+- Made the shell wordmark a 44-pixel touch target at mobile widths.
+- Added a small self-hosted favicon so standalone pages do not generate a missing-asset request.
+- Replaced the segmented theme selector with one compact system-default light/dark toggle.
+- Added trusted axis titles, tick labels, scales, and formatted summaries to operational charts.
+- Added hover/focus chart inspection with bounded keyboard stops and an accessible data summary.
+- Added explicit dashboard drill-down affordances and host-allowlisted navigation destination IDs.
+
+## 0.1.0a1 — 2026-09-01
+
+Initial release candidate.
+
+### Added
+
+- Strict `forgeui/1` manifests with a server-owned catalog, Pydantic models, JSON Schema,
+  semantic validation, graph limits, and a pure bounded expression AST.
+- Safe server rendering through Jinja2 with 46 catalog components, four complete design profiles,
+  accessible light/dark/system themes, and trusted SVG charts.
+- Stateful and stateless dashboard, standalone, desktop, mobile, embedded-card, and chat-artifact
+  surfaces using FastAPI and HTMX.
+- Immutable SQLite manifest revisions, server-owned state, optimistic concurrency, audit events,
+  device snapshots, and bounded in-process generation jobs.
+- Qwen/Ollama structured generation with strict parsing, dry rendering, duplicate detection, and
+  at most two repair attempts after the initial candidate.
+- Frozen data-contract, data-source, and capability registries for explicit host integrations.
+- A bounded Google A2UI v0.9.1 JSONL importer.
+- Three device-health example manifests, an AI-search host example, Docker/Compose support, and
+  package extras for base, web, HTTP sources, Ollama, serving, and the complete app.
+- Secretless PyPI Trusted Publishing workflow with release-version and wheel-size gates.
+
+### Security boundaries
+
+- Manifests cannot contain HTML, Jinja, JavaScript, CSS, Tailwind classes, URLs, SQL, file paths,
+  SVG paths, callbacks, or arbitrary executable expressions.
+- Invalid generated candidates are rejected before persistence and rendering.
+- Host code owns credentials, endpoints, authorization, data access, and side-effect handlers.
+
+### Known alpha limitations
+
+- SQLite persistence and the in-process job worker support one ForgeUI process/replica per database.
+- The live Ollama gauntlet requires an explicitly configured Ollama service and is not part of the
+  ordinary offline test suite.
+- Google A2UI support is an allowlisted v0.9.1 snapshot importer, not a general A2UI client.
+- APIs and the `forgeui/1` contract may change incompatibly before the first stable release.

forgeui-0.1.0a2/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+ForgeUI keeps its manifest and rendering boundary deliberately narrow. Before proposing a change,
+read [the architecture](docs/architecture.md), [manifest contract](docs/manifest.md), and
+[security boundaries](docs/security.md).
+
+## Development
+
+```bash
+uv sync --frozen --all-extras
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy src/forgeui
+uv run pytest -q --cov=forgeui --cov-fail-under=85
+uv build
+uv run twine check dist/*
+```
+
+Changes to a component must keep its catalog entry, strict Pydantic props, generated schema and
+prompt documentation, renderer template, examples, and tests synchronized. New model-controlled
+HTML, CSS, classes, URLs, paths, executable expressions, or generic transport capabilities are not
+accepted.
+
+Use focused tests while developing and run the full suite before opening a pull request. Live
+Ollama, browser, and Docker checks have explicit markers because they require external runtimes.
+
+Report security issues privately as described in [SECURITY.md](SECURITY.md).

forgeui-0.1.0a2/Dockerfile

@@ -0,0 +1,45 @@
+# syntax=docker/dockerfile:1
+# Build a small, reproducible runtime image from the committed uv lockfile.
+FROM ghcr.io/astral-sh/uv:0.12.8 AS uv
+
+FROM python:3.12-slim AS builder
+
+COPY --from=uv /uv /uvx /bin/
+WORKDIR /build
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_NO_CACHE=1
+
+COPY pyproject.toml uv.lock README.md LICENSE THIRD_PARTY_NOTICES.md ./
+RUN uv sync --frozen --no-dev --extra app --no-install-project
+
+COPY src ./src
+RUN uv sync --frozen --no-dev --extra app
+
+FROM python:3.12-slim AS runtime
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app/src \
+    VIRTUAL_ENV=/opt/venv \
+    PATH=/opt/venv/bin:$PATH \
+    FORGEUI_DATA_DIR=/data \
+    FORGEUI_DATABASE_URL=sqlite:////data/forgeui.db
+
+RUN addgroup --system --gid 10001 forgeui \
+    && adduser --system --uid 10001 --ingroup forgeui --home /nonexistent forgeui \
+    && mkdir -p /app /data \
+    && chown -R forgeui:forgeui /app /data
+
+WORKDIR /app
+COPY --from=builder --chown=forgeui:forgeui /build/.venv /opt/venv
+COPY --from=builder --chown=forgeui:forgeui /build/src /app/src
+
+USER forgeui
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/health/ready', timeout=3)"
+
+# The SQLite-backed in-process job worker requires one Uvicorn worker.
+CMD ["uvicorn", "forgeui.app:create_app", "--factory", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]

forgeui-0.1.0a2/LICENSE

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