admina-framework 0.9.1__tar.gz → 0.9.3__tar.gz

{admina_framework-0.9.1/admina_framework.egg-info → admina_framework-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina-framework
-Version: 0.9.1
+Version: 0.9.3
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>
@@ -43,10 +43,10 @@ Requires-Dist: boto3<2,>=1.34; extra == "proxy"
 Requires-Dist: minio<8,>=7.2; extra == "proxy"
 Requires-Dist: clickhouse-connect<1,>=0.7; extra == "proxy"
 Requires-Dist: typer<1,>=0.9; extra == "proxy"
+Requires-Dist: numpy<2,>=1.24; extra == "proxy"
+Requires-Dist: scikit-learn<2,>=1.3; extra == "proxy"
 Provides-Extra: nlp
 Requires-Dist: spacy<4,>=3.8; extra == "nlp"
-Requires-Dist: scikit-learn<2,>=1.3; extra == "nlp"
-Requires-Dist: numpy<2,>=1.24; extra == "nlp"
 Provides-Extra: telemetry
 Requires-Dist: opentelemetry-api<2,>=1.20; extra == "telemetry"
 Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "telemetry"
@@ -120,20 +120,22 @@ report = kit.gap_analysis(risk_category="high", current_compliance={...})
 ### Install from PyPI
 
 ```bash
-# SDK only (lightweight, pure Python)
-pip install admina-framework
-
-# Proxy + infrastructure deps
+# Recommended for new users: SDK + proxy + dashboard.
+# Lets you run `admina dev` and see the dashboard out of the box.
 pip install "admina-framework[proxy]"
 
-# Everything (proxy + NLP + telemetry)
+# Everything (proxy + NLP + telemetry). Use this if you also want
+# spaCy-based NER for PII detection or OpenTelemetry export.
 pip install "admina-framework[full]"
+python -m spacy download en_core_web_sm   # for [full] only
 
-# After [nlp] / [full] install: download the spaCy NER model
-python -m spacy download en_core_web_sm
-
-# Optional: Rust-accelerated engine (auto-detected at runtime)
+# Optional: Rust-accelerated engine (auto-detected at runtime).
 pip install admina-core
+
+# Advanced: SDK only (no proxy, no dashboard, no `admina dev`).
+# Use this when embedding the SDK into another service and you don't
+# need the local dev server.
+pip install admina-framework
 ```
 
 > The PyPI distribution name is `admina-framework`; the Python import
@@ -151,28 +153,27 @@ pip install admina-core
 git clone https://github.com/admina-org/admina.git
 cd admina
 
-# Option 1: SDK only (lightweight)
-pip install -e .
-python -c "from admina import GovernedModel; print('SDK ready')"
-
-# Note: To use the OllamaAdapter, install Ollama (https://ollama.ai)
-# and pull a model first: ollama pull llama3.1:8b
-
-# Option 2: Proxy + infra deps
+# Recommended: proxy + dashboard + infra deps (enables `admina dev`)
 pip install -e ".[proxy]"
 
-# Option 3: Everything (proxy + NLP + telemetry)
+# Everything (proxy + NLP + telemetry)
 pip install -e ".[full]"
 
-# Option 4: Full stack (proxy + dashboard + infra via Docker)
+# CLI workflow
+admina init my-project   # Scaffold a governed AI project
+cd my-project            # admina dev runs from the project directory
+admina dev               # Start the local proxy + dashboard
+
+# Full stack via Docker (no [proxy] extra required)
 ./scripts/bootstrap-secrets.sh   # Auto-generate .env with random credentials
 docker compose up --build        # Credentials printed at bootstrap
 
-# Option 5: CLI
+# Note: To use the OllamaAdapter, install Ollama (https://ollama.ai)
+# and pull a model first: ollama pull llama3.1:8b
+
+# Advanced: SDK only (no proxy, no dashboard)
 pip install -e .
-admina init my-project   # Scaffold a governed AI project
-cd my-project            # admina dev runs from the project directory
-admina dev               # Start local dev stack
+python -c "from admina import GovernedModel; print('SDK ready')"
 ```
 
 Dashboard: [http://localhost:3000](http://localhost:3000) | API docs: [http://localhost:8080/docs](http://localhost:8080/docs)

{admina_framework-0.9.1 → admina_framework-0.9.3}/README.md

@@ -62,20 +62,22 @@ report = kit.gap_analysis(risk_category="high", current_compliance={...})
 ### Install from PyPI
 
 ```bash
-# SDK only (lightweight, pure Python)
-pip install admina-framework
-
-# Proxy + infrastructure deps
+# Recommended for new users: SDK + proxy + dashboard.
+# Lets you run `admina dev` and see the dashboard out of the box.
 pip install "admina-framework[proxy]"
 
-# Everything (proxy + NLP + telemetry)
+# Everything (proxy + NLP + telemetry). Use this if you also want
+# spaCy-based NER for PII detection or OpenTelemetry export.
 pip install "admina-framework[full]"
+python -m spacy download en_core_web_sm   # for [full] only
 
-# After [nlp] / [full] install: download the spaCy NER model
-python -m spacy download en_core_web_sm
-
-# Optional: Rust-accelerated engine (auto-detected at runtime)
+# Optional: Rust-accelerated engine (auto-detected at runtime).
 pip install admina-core
+
+# Advanced: SDK only (no proxy, no dashboard, no `admina dev`).
+# Use this when embedding the SDK into another service and you don't
+# need the local dev server.
+pip install admina-framework
 ```
 
 > The PyPI distribution name is `admina-framework`; the Python import
@@ -93,28 +95,27 @@ pip install admina-core
 git clone https://github.com/admina-org/admina.git
 cd admina
 
-# Option 1: SDK only (lightweight)
-pip install -e .
-python -c "from admina import GovernedModel; print('SDK ready')"
-
-# Note: To use the OllamaAdapter, install Ollama (https://ollama.ai)
-# and pull a model first: ollama pull llama3.1:8b
-
-# Option 2: Proxy + infra deps
+# Recommended: proxy + dashboard + infra deps (enables `admina dev`)
 pip install -e ".[proxy]"
 
-# Option 3: Everything (proxy + NLP + telemetry)
+# Everything (proxy + NLP + telemetry)
 pip install -e ".[full]"
 
-# Option 4: Full stack (proxy + dashboard + infra via Docker)
+# CLI workflow
+admina init my-project   # Scaffold a governed AI project
+cd my-project            # admina dev runs from the project directory
+admina dev               # Start the local proxy + dashboard
+
+# Full stack via Docker (no [proxy] extra required)
 ./scripts/bootstrap-secrets.sh   # Auto-generate .env with random credentials
 docker compose up --build        # Credentials printed at bootstrap
 
-# Option 5: CLI
+# Note: To use the OllamaAdapter, install Ollama (https://ollama.ai)
+# and pull a model first: ollama pull llama3.1:8b
+
+# Advanced: SDK only (no proxy, no dashboard)
 pip install -e .
-admina init my-project   # Scaffold a governed AI project
-cd my-project            # admina dev runs from the project directory
-admina dev               # Start local dev stack
+python -c "from admina import GovernedModel; print('SDK ready')"
 ```
 
 Dashboard: [http://localhost:3000](http://localhost:3000) | API docs: [http://localhost:8080/docs](http://localhost:8080/docs)

{admina_framework-0.9.1 → admina_framework-0.9.3}/admina/__init__.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 
 from admina.sdk import ComplianceKit, GovernedAgent, GovernedData, GovernedModel
 
-__version__ = "0.9.1"
+__version__ = "0.9.3"
 
 __all__ = [
     "__version__",

{admina_framework-0.9.1 → admina_framework-0.9.3}/admina/cli/main.py

@@ -262,20 +262,61 @@ def init(
         else:
             click.echo("  ⚠ docker compose pull failed (you can run it later)")
 
-    # 5. Print next steps
-    click.echo(f"""
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Project ready!
+    # 5. Print next steps — tailored to what the user actually has installed.
+    click.echo(_format_next_steps(project_name))
 
-  Next steps:
-    cd {project_name}
-    admina dev          # local mode (no Docker): proxy + dashboard on :3000
-    admina dev --stack  # full Docker stack (proxy, redis, clickhouse, minio, grafana)
-    python main.py      # run example (works without admina dev)
 
-  Docs: https://admina.org/docs
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-""")
+def _format_next_steps(project_name: str) -> str:
+    """Build the post-init "Next steps" message based on detected extras.
+
+    Honest output: only suggest commands that will work with the user's
+    current install. Missing prerequisites are surfaced explicitly with
+    the exact upgrade command.
+    """
+    proxy_ok = _proxy_extra_installed()
+    docker_ok = shutil.which("docker") is not None
+
+    lines: list[str] = [
+        "",
+        "  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "  Project ready!",
+        "",
+        "  Next steps:",
+        f"    cd {project_name}",
+        "    python main.py                # SDK example — works with any install",
+    ]
+    if proxy_ok:
+        lines.append("    admina dev                    # local proxy + dashboard on :3000")
+    else:
+        lines.extend(
+            [
+                "",
+                "  To run the local proxy + dashboard (admina dev), install the [proxy] extra:",
+                "    pip install 'admina-framework[proxy]' --upgrade",
+            ]
+        )
+    if docker_ok:
+        lines.append(
+            "    admina dev --stack            # full Docker stack "
+            "(proxy + redis + clickhouse + minio + grafana)"
+        )
+    else:
+        lines.extend(
+            [
+                "",
+                "  To run the full Docker stack (admina dev --stack), install Docker:",
+                "    https://docs.docker.com/get-docker/",
+            ]
+        )
+    lines.extend(
+        [
+            "",
+            "  Docs: https://admina.org/docs",
+            "  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+            "",
+        ]
+    )
+    return "\n".join(lines)
 
 
 # ── admina dev helpers ─────────────────────────────────────
@@ -482,6 +523,46 @@ def _list_local_ipv4() -> list[str]:
     return sorted(ips, key=lambda ip: (ip != "127.0.0.1", ip))
 
 
+def _proxy_extra_installed() -> bool:
+    """True if uvicorn + fastapi (the [proxy] extra) are importable."""
+    try:
+        import fastapi  # noqa: F401
+        import uvicorn  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def _require_proxy_extra_for_local_dev() -> None:
+    """Exit cleanly with an actionable message when [proxy] is missing.
+
+    Local-mode `admina dev` shells out to uvicorn, which lives only in the
+    [proxy] extra. Without an early check, the user sees a cryptic
+    `No module named uvicorn` from python -m uvicorn.
+    """
+    if _proxy_extra_installed():
+        return
+    click.echo("", err=True)
+    click.echo("  admina dev (local mode) requires the [proxy] extra.", err=True)
+    click.echo("  Install one of:", err=True)
+    click.echo(
+        "    pip install 'admina-framework[proxy]' --upgrade",
+        err=True,
+    )
+    click.echo(
+        "    pip install 'admina-framework[full]' --upgrade   # adds NLP + telemetry",
+        err=True,
+    )
+    click.echo("", err=True)
+    click.echo(
+        "  Or run the full Docker stack (no [proxy] extra required):",
+        err=True,
+    )
+    click.echo("    admina dev --stack", err=True)
+    click.echo("", err=True)
+    raise SystemExit(1)
+
+
 def _run_local(
     project_dir: Path,
     vault: SecretVault,
@@ -491,6 +572,8 @@ def _run_local(
     host: str,
 ) -> None:
     """Run proxy + dashboard as a single uvicorn process (no Docker)."""
+    _require_proxy_extra_for_local_dev()
+
     # Auto-detect free port: if preferred is taken (Docker Desktop, Grafana,
     # another node dev server on :3000…), fall back to the next free port.
     try:
@@ -1032,6 +1115,8 @@ def doctor() -> None:
             issues.append(f"Missing: pip install {pkg_name}")
 
     # ── Optional extras ──────────────────────────────────────
+    # Each group lists (import_name, pypi_name) tuples. numpy + scikit-learn
+    # are part of [proxy] (LoopBreaker requires them), not [nlp].
     click.echo("\n  Optional extras:")
     extras = {
         "proxy": [
@@ -1042,16 +1127,17 @@ def doctor() -> None:
             ("redis", "redis"),
             ("minio", "minio"),
             ("clickhouse_connect", "clickhouse-connect"),
+            ("numpy", "numpy"),
+            ("sklearn", "scikit-learn"),
         ],
         "nlp": [
             ("spacy", "spacy"),
-            ("sklearn", "scikit-learn"),
-            ("numpy", "numpy"),
         ],
         "telemetry": [
             ("opentelemetry", "opentelemetry-api"),
         ],
     }
+    extras_status: dict[str, str] = {}
     for group, mods in extras.items():
         present = 0
         for mod_name, _ in mods:
@@ -1062,12 +1148,25 @@ def doctor() -> None:
                 pass
         if present == len(mods):
             click.echo(f"    [{group}]{' ' * (16 - len(group))} {ok_mark}  ({present}/{len(mods)})")
+            extras_status[group] = "ok"
         elif present > 0:
             click.echo(
                 f"    [{group}]{' ' * (16 - len(group))} {warn_mark} ({present}/{len(mods)})"
             )
+            extras_status[group] = "partial"
         else:
             click.echo(f"    [{group}]{' ' * (16 - len(group))} --    not installed")
+            extras_status[group] = "missing"
+
+    if extras_status.get("proxy") != "ok":
+        click.echo(
+            f"    {warn_mark}  admina dev (local mode) needs the [proxy] extra — "
+            "pip install 'admina-framework[proxy]' --upgrade"
+        )
+        issues.append(
+            "admina dev (local mode) requires the [proxy] extra — "
+            "run: pip install 'admina-framework[proxy]' --upgrade"
+        )
 
     # ── spaCy NER model ──────────────────────────────────────
     click.echo("\n  NLP engine:")
@@ -1078,12 +1177,28 @@ def doctor() -> None:
             spacy.load("en_core_web_sm")
             click.echo(f"    en_core_web_sm       {ok_mark}")
         except OSError:
+            # PII still works in regex-only mode without the spaCy model, so
+            # this is a soft warning rather than a blocking issue.
             click.echo(
-                f"    en_core_web_sm       {warn_mark}  (run: python -m spacy download en_core_web_sm)"
+                f"    en_core_web_sm       {warn_mark}  not loadable "
+                "(PII falls back to regex-only — install for NER coverage)"
+            )
+            # The model is not on PyPI — it ships as a direct wheel URL
+            # from explosion/spacy-models on GitHub. `python -m spacy
+            # download` is the canonical command but needs pip in the
+            # venv; for uv venvs (which omit pip) point at the wheel URL.
+            model_ver = "3.8.0"  # matches spacy>=3.8,<4 pinned in [nlp]
+            wheel_url = (
+                "https://github.com/explosion/spacy-models/releases/download/"
+                f"en_core_web_sm-{model_ver}/en_core_web_sm-{model_ver}-py3-none-any.whl"
             )
-            issues.append("spaCy model not installed — PII uses regex-only mode")
+            click.echo(f"        Install with:  {sys.executable} -m spacy download en_core_web_sm")
+            click.echo(f"        For uv venvs:  uv pip install {wheel_url}")
     except ImportError:
-        click.echo("    spacy                --    not installed (PII disabled)")
+        click.echo(
+            "    spacy                --    not installed "
+            "(PII falls back to regex-only — install [nlp] extra for NER)"
+        )
 
     # ── Rust engine ──────────────────────────────────────────
     click.echo("\n  Governance engine:")

{admina_framework-0.9.1 → admina_framework-0.9.3}/admina/dashboard/static/index.html

@@ -932,36 +932,43 @@ function dashboard() {
 
     // ── Fetch all data ─────────────────────────────────
     async refresh() {
-      try {
-        const [scoreRes, compRes, sovRes, statsRes, feedRes, infraRes, modelsRes, oisgRes] = await Promise.all([
-          fetch('/api/dashboard/score').then(r => r.json()),
-          fetch('/api/dashboard/compliance').then(r => r.json()),
-          fetch('/api/dashboard/sovereignty').then(r => r.json()),
-          fetch('/api/stats').then(r => r.json()),
-          fetch('/api/dashboard/feed?limit=50').then(r => r.json()),
-          fetch('/api/dashboard/infra').then(r => r.json()),
-          fetch('/api/dashboard/models').then(r => r.json()),
-          fetch('/api/dashboard/oisg').then(r => r.json()).catch(() => ({})),
-        ]);
-
-        this.score = scoreRes;
-        this.complianceData = compRes;
-        this.sovereignty = sovRes;
-        this.stats = statsRes;
-        this.infraData = infraRes;
-        this.modelData = modelsRes;
-        this.oisg = oisgRes;
-        this.healthy = true;
-        this.lastUpdate = new Date().toLocaleTimeString();
-
-        // Seed the feed with historical events if WS hasn't provided any yet
-        if (this.feedEvents.length === 0 && feedRes.events && feedRes.events.length > 0) {
-          this.feedEvents = feedRes.events.slice(0, 50).map(e => this._formatFeedEvent(e));
-        }
-      } catch (err) {
-        console.error('Dashboard refresh failed:', err);
-        this.healthy = false;
-        this.lastUpdate = 'error';
+      // allSettled so one failing endpoint never blanks the whole dashboard.
+      const okJson = async (url) => {
+        const r = await fetch(url);
+        if (!r.ok) throw new Error(`${url} -> ${r.status}`);
+        return r.json();
+      };
+      const results = await Promise.allSettled([
+        okJson('/api/dashboard/score'),
+        okJson('/api/dashboard/compliance'),
+        okJson('/api/dashboard/sovereignty'),
+        okJson('/api/stats'),
+        okJson('/api/dashboard/feed?limit=50'),
+        okJson('/api/dashboard/infra'),
+        okJson('/api/dashboard/models'),
+        okJson('/api/dashboard/oisg'),
+      ]);
+      const [scoreRes, compRes, sovRes, statsRes, feedRes, infraRes, modelsRes, oisgRes] =
+        results.map(r => r.status === 'fulfilled' ? r.value : null);
+
+      if (scoreRes) this.score = scoreRes;
+      if (compRes) this.complianceData = compRes;
+      if (sovRes) this.sovereignty = sovRes;
+      if (statsRes) this.stats = statsRes;
+      if (infraRes) this.infraData = infraRes;
+      if (modelsRes) this.modelData = modelsRes;
+      if (oisgRes) this.oisg = oisgRes;
+
+      const failed = results.filter(r => r.status === 'rejected');
+      if (failed.length) {
+        failed.forEach(r => console.warn('[Admina] endpoint failed:', r.reason));
+      }
+      this.healthy = failed.length === 0;
+      this.lastUpdate = new Date().toLocaleTimeString();
+
+      // Seed the feed with historical events if WS hasn't provided any yet
+      if (this.feedEvents.length === 0 && feedRes?.events?.length > 0) {
+        this.feedEvents = feedRes.events.slice(0, 50).map(e => this._formatFeedEvent(e));
       }
     },
 

{admina_framework-0.9.1 → admina_framework-0.9.3}/admina/domains/data_sovereignty/pii.py

@@ -21,7 +21,12 @@ import logging
 import os
 import re
 
-import spacy
+# spaCy is part of the [nlp] extra. When absent, PIIRedactor falls back
+# to regex-only mode (still covers EMAIL/PHONE/SSN/IBAN/IP/credit-card/EU IDs).
+try:
+    import spacy as _spacy
+except ImportError:
+    _spacy = None  # type: ignore[assignment]
 
 logger = logging.getLogger("admina.pii_redactor")
 
@@ -152,12 +157,24 @@ class PIIRedactor:
     def __init__(self, config=None):
         # Resolve NLP model: config.ner_model > ADMINA_SPACY_MODEL env var > default
         model_name = getattr(config, "ner_model", None) or SPACY_MODEL
-        try:
-            self.nlp = spacy.load(model_name)
-            logger.info("[OK] spaCy model loaded: %s", model_name)
-        except OSError:
-            logger.warning("[WARN] spaCy model '%s' not found, using regex-only mode", model_name)
+        if _spacy is None:
+            logger.info(
+                "spaCy not installed — PII redaction running in regex-only mode "
+                "(install admina-framework[nlp] for NER-based detection)"
+            )
             self.nlp = None
+        else:
+            try:
+                self.nlp = _spacy.load(model_name)
+                logger.info("[OK] spaCy model loaded: %s", model_name)
+            except OSError:
+                logger.warning(
+                    "spaCy model '%s' not found — using regex-only mode "
+                    "(run: python -m spacy download %s)",
+                    model_name,
+                    model_name,
+                )
+                self.nlp = None
 
         # Build active categories: start from PII_CATEGORIES defaults, then
         # disable any category not listed in config.categories (if provided).

{admina_framework-0.9.1 → admina_framework-0.9.3}/admina/plugins/registry.py

@@ -284,6 +284,13 @@ class PluginRegistry:
             mod = importlib.util.module_from_spec(spec)
             sys.modules[mod_name] = mod
             spec.loader.exec_module(mod)
+        except ModuleNotFoundError as exc:
+            logger.warning(
+                "Skipping plugin %s — optional dependency %r not installed",
+                py_file.stem,
+                exc.name or "?",
+            )
+            return 0
         except (ImportError, AttributeError, RuntimeError):
             logger.warning("Failed to import plugin file %s", py_file, exc_info=True)
             return 0
@@ -294,6 +301,13 @@ class PluginRegistry:
         """Import a module by dotted path and register all plugin classes."""
         try:
             mod = importlib.import_module(mod_path)
+        except ModuleNotFoundError as exc:
+            logger.warning(
+                "Skipping plugin module %r — optional dependency %r not installed",
+                mod_path,
+                exc.name or "?",
+            )
+            return 0
         except ImportError:
             logger.warning("Failed to import plugin module %r", mod_path, exc_info=True)
             return 0

{admina_framework-0.9.1 → admina_framework-0.9.3}/admina/proxy/api/dashboard.py

@@ -450,9 +450,13 @@ def create_dashboard_endpoints(
 
         # Upstream MCP
         http = get_http_client() if get_http_client else None
-        if http is not None:
-            upstream = get_settings().UPSTREAM_MCP_URL
+        upstream = get_settings().UPSTREAM_MCP_URL if get_settings else ""
+        if http is None or not upstream.startswith(("http://", "https://")):
+            services["upstream_mcp"] = {"status": "not_configured"}
+        else:
             try:
+                import httpx
+
                 t0 = time.perf_counter()
                 resp = await http.get(f"{upstream}/health", timeout=3.0)
                 latency = round((time.perf_counter() - t0) * 1000, 2)
@@ -461,13 +465,11 @@ def create_dashboard_endpoints(
                     "latency_ms": latency,
                     "url": upstream,
                 }
-            except (OSError, RuntimeError):
+            except (OSError, RuntimeError, httpx.HTTPError):
                 services["upstream_mcp"] = {
                     "status": "unreachable",
                     "url": upstream,
                 }
-        else:
-            services["upstream_mcp"] = {"status": "not_configured"}
 
         healthy_count = sum(1 for s in services.values() if s.get("status") == "healthy")
         return {

{admina_framework-0.9.1 → admina_framework-0.9.3/admina_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina-framework
-Version: 0.9.1
+Version: 0.9.3
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>
@@ -43,10 +43,10 @@ Requires-Dist: boto3<2,>=1.34; extra == "proxy"
 Requires-Dist: minio<8,>=7.2; extra == "proxy"
 Requires-Dist: clickhouse-connect<1,>=0.7; extra == "proxy"
 Requires-Dist: typer<1,>=0.9; extra == "proxy"
+Requires-Dist: numpy<2,>=1.24; extra == "proxy"
+Requires-Dist: scikit-learn<2,>=1.3; extra == "proxy"
 Provides-Extra: nlp
 Requires-Dist: spacy<4,>=3.8; extra == "nlp"
-Requires-Dist: scikit-learn<2,>=1.3; extra == "nlp"
-Requires-Dist: numpy<2,>=1.24; extra == "nlp"
 Provides-Extra: telemetry
 Requires-Dist: opentelemetry-api<2,>=1.20; extra == "telemetry"
 Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "telemetry"
@@ -120,20 +120,22 @@ report = kit.gap_analysis(risk_category="high", current_compliance={...})
 ### Install from PyPI
 
 ```bash
-# SDK only (lightweight, pure Python)
-pip install admina-framework
-
-# Proxy + infrastructure deps
+# Recommended for new users: SDK + proxy + dashboard.
+# Lets you run `admina dev` and see the dashboard out of the box.
 pip install "admina-framework[proxy]"
 
-# Everything (proxy + NLP + telemetry)
+# Everything (proxy + NLP + telemetry). Use this if you also want
+# spaCy-based NER for PII detection or OpenTelemetry export.
 pip install "admina-framework[full]"
+python -m spacy download en_core_web_sm   # for [full] only
 
-# After [nlp] / [full] install: download the spaCy NER model
-python -m spacy download en_core_web_sm
-
-# Optional: Rust-accelerated engine (auto-detected at runtime)
+# Optional: Rust-accelerated engine (auto-detected at runtime).
 pip install admina-core
+
+# Advanced: SDK only (no proxy, no dashboard, no `admina dev`).
+# Use this when embedding the SDK into another service and you don't
+# need the local dev server.
+pip install admina-framework
 ```
 
 > The PyPI distribution name is `admina-framework`; the Python import
@@ -151,28 +153,27 @@ pip install admina-core
 git clone https://github.com/admina-org/admina.git
 cd admina
 
-# Option 1: SDK only (lightweight)
-pip install -e .
-python -c "from admina import GovernedModel; print('SDK ready')"
-
-# Note: To use the OllamaAdapter, install Ollama (https://ollama.ai)
-# and pull a model first: ollama pull llama3.1:8b
-
-# Option 2: Proxy + infra deps
+# Recommended: proxy + dashboard + infra deps (enables `admina dev`)
 pip install -e ".[proxy]"
 
-# Option 3: Everything (proxy + NLP + telemetry)
+# Everything (proxy + NLP + telemetry)
 pip install -e ".[full]"
 
-# Option 4: Full stack (proxy + dashboard + infra via Docker)
+# CLI workflow
+admina init my-project   # Scaffold a governed AI project
+cd my-project            # admina dev runs from the project directory
+admina dev               # Start the local proxy + dashboard
+
+# Full stack via Docker (no [proxy] extra required)
 ./scripts/bootstrap-secrets.sh   # Auto-generate .env with random credentials
 docker compose up --build        # Credentials printed at bootstrap
 
-# Option 5: CLI
+# Note: To use the OllamaAdapter, install Ollama (https://ollama.ai)
+# and pull a model first: ollama pull llama3.1:8b
+
+# Advanced: SDK only (no proxy, no dashboard)
 pip install -e .
-admina init my-project   # Scaffold a governed AI project
-cd my-project            # admina dev runs from the project directory
-admina dev               # Start local dev stack
+python -c "from admina import GovernedModel; print('SDK ready')"
 ```
 
 Dashboard: [http://localhost:3000](http://localhost:3000) | API docs: [http://localhost:8080/docs](http://localhost:8080/docs)

{admina_framework-0.9.1 → admina_framework-0.9.3}/pyproject.toml

@@ -19,7 +19,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "admina-framework"
-version = "0.9.1"
+version = "0.9.3"
 description = "Admina — governed AI development framework"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -80,6 +80,9 @@ proxy = [
     "minio>=7.2,<8",
     "clickhouse-connect>=0.7,<1",
     "typer>=0.9,<1",
+    # Required by the LoopBreaker (core proxy guardrail — not an NLP add-on).
+    "numpy>=1.24,<2",
+    "scikit-learn>=1.3,<2",
 ]
 nlp = [
     # spacy 3.7.x ships an old blis (0.7.11) that fails to build on Python 3.13
@@ -92,8 +95,6 @@ nlp = [
     # `admina-framework[nlp]`, run:
     #   python -m spacy download en_core_web_sm
     # The PIIRedactor logs a clear error if the model is missing.
-    "scikit-learn>=1.3,<2",
-    "numpy>=1.24,<2",
 ]
 telemetry = [
     "opentelemetry-api>=1.20,<2",

{admina_framework-0.9.1 → admina_framework-0.9.3}/tests/test_domains.py

@@ -295,6 +295,23 @@ class TestEngineBridge:
         assert hasattr(pii, "redact")
         assert hasattr(pii, "get_stats")
 
+    def test_pii_factory_without_spacy_installed(self, monkeypatch):
+        """Regression: admina dev must boot even when spaCy is not installed.
+
+        Simulates a user who ran `pip install admina-framework[proxy]` without
+        the [nlp] extra. The PII bridge must fall back to regex-only mode
+        instead of crashing the proxy lifespan with ModuleNotFoundError.
+        """
+        from admina.domains.data_sovereignty import pii as pii_mod
+
+        monkeypatch.setattr(pii_mod, "_spacy", None)
+
+        redactor = pii_mod.PIIRedactor()
+        assert redactor.nlp is None
+        r = redactor.redact("Contact john@example.com")
+        assert "john@example.com" not in r["redacted_text"]
+        assert r["count"] >= 1
+
     def test_loop_breaker_factory(self):
         from admina.proxy.engine_bridge import get_loop_breaker
 

{admina_framework-0.9.1 → admina_framework-0.9.3}/admina_framework.egg-info/requires.txt

@@ -8,8 +8,6 @@ admina-framework[nlp,proxy,telemetry]
 
 [nlp]
 spacy<4,>=3.8
-scikit-learn<2,>=1.3
-numpy<2,>=1.24
 
 [proxy]
 fastapi<1,>=0.104
@@ -23,6 +21,8 @@ boto3<2,>=1.34
 minio<8,>=7.2
 clickhouse-connect<1,>=0.7
 typer<1,>=0.9
+numpy<2,>=1.24
+scikit-learn<2,>=1.3
 
 [telemetry]
 opentelemetry-api<2,>=1.20