awclassify 0.1.0__tar.gz

awclassify-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright 2026 Aitherium
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

awclassify-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: awclassify
+Version: 0.1.0
+Summary: Classify any document — type, visibility, audience, topics. Aither World Classify.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Aitherium/awclassify
+Project-URL: Documentation, https://github.com/Aitherium/awclassify#readme
+Project-URL: Repository, https://github.com/Aitherium/awclassify.git
+Project-URL: Issues, https://github.com/Aitherium/awclassify/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# awclassify
+
+**Aither World Classify** — classify any document: *what it is*, *who may
+read it*, *who it is for*, *what it is about*. A standalone, zero-dependency
+CLI + client, public and pip-installable, for the Aither World stack.
+
+```bash
+pip install awclassify
+
+awclassify classify report.md
+# doc_type    report
+# visibility  internal
+# audience    other
+# topics      -
+# engine      rules   classified=False
+#
+# NOT VERIFIED: rules-only classification. Pass --server for the full
+# engine. Per the fail-closed contract, do not publish on this alone.
+```
+
+## What it answers
+
+| field | meaning | vocabulary |
+|---|---|---|
+| `doc_type` | what it is | deck, blog, prd, transcript, report, memo, decision, spec, docs, guide, code, data, email, social, minutes, contract, research, other |
+| `visibility` | who may read it | public, internal, confidential |
+| `audience` | who it is for | customers, investors, partners, general_public, internal, agents, regulatory, other |
+| `topics` | what it is about | 1–5 free-form tags |
+
+## The fail-closed contract
+
+A classification you cannot verify is **NOT public**.
+
+- `classified: False` means the output is heuristic only — do not publish
+  the document on it.
+- The rules path never asserts `public` from a filename alone; an explicit
+  marker (`public/`, `.public.`) is required.
+- When the server cannot be reached, the client returns
+  `classified: False, visibility: internal` with the reason — never a
+  fabricated answer.
+
+To publish a document you need the server-verified answer:
+
+```bash
+awclassify classify deck.json --server https://your-platform/doc-classify \
+  --token "$PLATFORM_BEARER" --json | jq .visibility
+# "public"  ← only now may a stranger read it
+```
+
+## Modes
+
+- **Local rules** (default, offline): deterministic classification from the
+  filename, title and source type. Zero network, zero dependencies.
+- **Server**: `--server URL` posts the document to any classify-shaped
+  surface — the AitherOS platform's `/classify`, or anything implementing
+  the same contract — for the full LLM-powered classification with
+  confidence scores. `--require-server` makes an unreachable surface an
+  error instead of a downgrade.
+
+```bash
+awclassify taxonomy                      # the fixed vocabulary, offline
+awclassify taxonomy --server URL         # ...and diff it against the server's
+```
+
+## Why it exists
+
+A $35K revenue figure shipped in a public slide deck because nothing asked
+what the document was or who could see it. `awclassify` makes that answer
+exist as data before anything ships — one command, no credentials required
+for the local tier.
+
+## Relationship to the platform
+
+`awclassify` is the **client brick**. The service half — the engine
+(`lib.knowledge.DocClassifier`), the genesis `/doc-classify` router, and the
+Nexus-ingest integration — lives in the AitherOS platform as
+`aitherclassify`. The taxonomy parity between the two copies is asserted by
+the platform's `check_classify_taxonomy_parity` gate.
+
+## Development
+
+```bash
+python -m pytest tests/
+```

awclassify-0.1.0/README.md

@@ -0,0 +1,84 @@
+# awclassify
+
+**Aither World Classify** — classify any document: *what it is*, *who may
+read it*, *who it is for*, *what it is about*. A standalone, zero-dependency
+CLI + client, public and pip-installable, for the Aither World stack.
+
+```bash
+pip install awclassify
+
+awclassify classify report.md
+# doc_type    report
+# visibility  internal
+# audience    other
+# topics      -
+# engine      rules   classified=False
+#
+# NOT VERIFIED: rules-only classification. Pass --server for the full
+# engine. Per the fail-closed contract, do not publish on this alone.
+```
+
+## What it answers
+
+| field | meaning | vocabulary |
+|---|---|---|
+| `doc_type` | what it is | deck, blog, prd, transcript, report, memo, decision, spec, docs, guide, code, data, email, social, minutes, contract, research, other |
+| `visibility` | who may read it | public, internal, confidential |
+| `audience` | who it is for | customers, investors, partners, general_public, internal, agents, regulatory, other |
+| `topics` | what it is about | 1–5 free-form tags |
+
+## The fail-closed contract
+
+A classification you cannot verify is **NOT public**.
+
+- `classified: False` means the output is heuristic only — do not publish
+  the document on it.
+- The rules path never asserts `public` from a filename alone; an explicit
+  marker (`public/`, `.public.`) is required.
+- When the server cannot be reached, the client returns
+  `classified: False, visibility: internal` with the reason — never a
+  fabricated answer.
+
+To publish a document you need the server-verified answer:
+
+```bash
+awclassify classify deck.json --server https://your-platform/doc-classify \
+  --token "$PLATFORM_BEARER" --json | jq .visibility
+# "public"  ← only now may a stranger read it
+```
+
+## Modes
+
+- **Local rules** (default, offline): deterministic classification from the
+  filename, title and source type. Zero network, zero dependencies.
+- **Server**: `--server URL` posts the document to any classify-shaped
+  surface — the AitherOS platform's `/classify`, or anything implementing
+  the same contract — for the full LLM-powered classification with
+  confidence scores. `--require-server` makes an unreachable surface an
+  error instead of a downgrade.
+
+```bash
+awclassify taxonomy                      # the fixed vocabulary, offline
+awclassify taxonomy --server URL         # ...and diff it against the server's
+```
+
+## Why it exists
+
+A $35K revenue figure shipped in a public slide deck because nothing asked
+what the document was or who could see it. `awclassify` makes that answer
+exist as data before anything ships — one command, no credentials required
+for the local tier.
+
+## Relationship to the platform
+
+`awclassify` is the **client brick**. The service half — the engine
+(`lib.knowledge.DocClassifier`), the genesis `/doc-classify` router, and the
+Nexus-ingest integration — lives in the AitherOS platform as
+`aitherclassify`. The taxonomy parity between the two copies is asserted by
+the platform's `check_classify_taxonomy_parity` gate.
+
+## Development
+
+```bash
+python -m pytest tests/
+```

awclassify-0.1.0/awclassify/__init__.py

@@ -0,0 +1,25 @@
+"""awclassify — Aither World Classify.
+
+Classify any document the way the platform does: WHAT it is (doc_type),
+WHO may read it (visibility), WHO it is for (audience), and WHAT it is
+about (topics). A standalone, zero-dependency client for a classify-shaped
+server, with a deterministic local classifier that works with no network.
+
+Two modes:
+  - local rules  — offline, deterministic, from filename/title/source.
+                  NEVER asserts "public" without an explicit marker.
+  - server       — POST the document to a classify-shaped surface
+                  (the AitherOS platform's /classify, or any server
+                  speaking the same contract) for the full LLM-powered
+                  classification with confidence scores.
+
+Fail-closed contract: a classification you cannot verify is NOT public.
+`classified: False` with `visibility: internal` is the honest answer to
+"can I ship this" until the server says otherwise.
+"""
+
+from awclassify.rules import classify_rules
+from awclassify.taxonomy import AUDIENCES, DOC_TYPES, VISIBILITIES
+
+__version__ = "0.1.0"
+__all__ = ["classify_rules", "DOC_TYPES", "VISIBILITIES", "AUDIENCES", "__version__"]

awclassify-0.1.0/awclassify/__main__.py

@@ -0,0 +1,8 @@
+"""python -m awclassify — same as the `awclassify` console script."""
+
+import sys
+
+from awclassify.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

awclassify-0.1.0/awclassify/_doctor.py

@@ -0,0 +1,161 @@
+"""Stack-aware `doctor` for awclassify.
+
+GENERATED BY gen_aw_doctor.py -- DO NOT EDIT.
+Regenerate it with the generator named above; a hand-edit here is reverted by
+the next run and fails the parity gate.
+
+Why a doctor exists at all: the aw* bricks are designed to COMPOSE, so the
+interesting failures live BETWEEN them. "awclassify is installed" is not the useful
+fact -- "awclassify is installed and the thing it pairs with is not" is. This reports
+the whole stack, not just itself.
+
+stdlib only, on purpose: a diagnostic that cannot run because a dependency is
+missing is worthless precisely when you need it.
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+
+#: Frozen from the Aither World registry at generation time. A shipped
+#: package cannot read the registry, and a doctor that guessed at the family
+#: would go stale in silence. Regenerate to update.
+SELF = 'awclassify'
+FAMILY = ['awask', 'awavatar', 'awbac', 'awbrain', 'awbrowse', 'awdecide', 'awdelphi', 'awdit', 'awembed', 'awevolve', 'awfind', 'awflow', 'awfocus', 'awgit', 'awgraph', 'awgym', 'awiam', 'awkno', 'awm', 'awmail', 'awnboard', 'awnest', 'awnet', 'awpool', 'awpredict', 'awprism', 'awprove', 'awreason', 'awrecover', 'awrecurse', 'awrelay', 'awrena', 'awrepl', 'awreport', 'awresearch', 'awrise', 'awrouter', 'awrtifact', 'awrun', 'awscreen', 'awseal', 'awsettings', 'awshare', 'awsprite', 'awstorage', 'awswarm', 'awtax', 'awtoll', 'awtunnel', 'awvision', 'awvoice', 'awwall', 'gawbbonet']
+PAIRS_WITH = ['adk', 'awkno']
+
+#: This brick's OWN config, read out of its source at generation time.
+#: ENV_REQUIRED is `os.environ["X"]` -- absent, that is a KeyError the moment
+#: the line runs. ENV_OPTIONAL is `os.getenv("X")`, which returns None and lets
+#: the caller cope. Only this brick's namespace is listed: reporting the
+#: platform-wide vars it also touches would be noise, and a doctor that floods
+#: gets ignored.
+ENV_REQUIRED = []
+ENV_OPTIONAL = []
+
+
+def _installed(mod: str) -> "str | None":
+    """Version if importable, else None. Never raises -- a broken sibling must
+    not take the diagnostic down with it."""
+    try:
+        if importlib.util.find_spec(mod) is None:
+            return None
+    except (ImportError, ValueError):
+        return None
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version(mod)
+        except PackageNotFoundError:
+            return "installed"
+    except Exception:
+        return "installed"
+
+
+def report(out=None) -> int:
+    """Print the stack picture. 0 = this brick and its pairs are present."""
+    out = out or sys.stdout
+    print(f"{SELF} doctor", file=out)
+
+    mine = _installed(SELF)
+    print(f"  self       {SELF} {mine or 'NOT IMPORTABLE'}", file=out)
+    shim = shutil.which(SELF)
+    print(f"  command    {shim or 'not on PATH'}", file=out)
+
+    # The stack. Siblings this brick pairs with are called out separately,
+    # because a missing pair is a REASON, while a missing unrelated brick is
+    # just a fact about your machine.
+    missing_pairs, present = [], []
+    for name in FAMILY:
+        v = _installed(name)
+        if v:
+            present.append(name)
+        elif name in PAIRS_WITH:
+            missing_pairs.append(name)
+    print(f"  stack      {len(present)}/{len(FAMILY)} aw* packages installed",
+          file=out)
+    if present:
+        print(f"             {' '.join(sorted(present))}", file=out)
+
+    missing_req = [v for v in ENV_REQUIRED if not os.environ.get(v)]
+    if ENV_REQUIRED or ENV_OPTIONAL:
+        have = sum(1 for v in ENV_REQUIRED + ENV_OPTIONAL if os.environ.get(v))
+        total = len(ENV_REQUIRED) + len(ENV_OPTIONAL)
+        print(f"  config     {have}/{total} of this brick's own vars set", file=out)
+        if missing_req:
+            # Not a preference. os.environ[...] raises the moment it runs.
+            print(f"             MISSING REQUIRED: {' '.join(missing_req)}", file=out)
+
+    local = _local_checks()
+    for line in local:
+        print(f"  {line}", file=out)
+
+    if mine is None:
+        print(f"\nverdict: {SELF} itself is not importable. Reinstall it before "
+              f"anything else here means much.", file=out)
+        return 1
+    if missing_req:
+        print(f"\nverdict: {SELF} is missing required config "
+              f"({', '.join(missing_req)}). Those are read with os.environ[...], "
+              f"so the code path that needs them raises rather than degrades.",
+              file=out)
+        return 1
+    if missing_pairs:
+        print(f"\nverdict: {SELF} works, but pairs with "
+              f"{', '.join(sorted(missing_pairs))} which "
+              f"{'is' if len(missing_pairs) == 1 else 'are'} not installed. "
+              f"That is a capability you are missing, not an error.", file=out)
+        return 0
+    print(f"\nverdict: {SELF} and everything it pairs with are present.", file=out)
+    return 0
+
+
+def _local_checks() -> "list[str]":
+    """Per-brick checks, if this package defines them.
+
+    Kept as a HOOK rather than generated guesses: the generator knows the family
+    from the registry, but it does not know what awclassify needs at runtime, and a
+    doctor that invented config requirements would be confidently wrong. A
+    package supplies `_doctor_local()` returning display lines; absent, the
+    stack picture above still stands on its own.
+    """
+    try:
+        mod = importlib.import_module(f"{SELF}.doctor_local")
+    except Exception:
+        return []
+    try:
+        return list(mod._doctor_local())
+    except Exception as exc:                       # noqa: BLE001
+        return [f"local     checks raised {type(exc).__name__}: {exc}"]
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    # --self-test delegates to a SIBLING module when one exists.
+    #
+    # This file is generated and a fresh run replaces it, so a self-test
+    # written HERE is deleted by the next regeneration. awdelphi learned that
+    # the expensive way: 125 lines exercising four real failure paths --
+    # convergence, roster anonymization, resume, gateway-down -- lived in this
+    # file and were destroyed by a routine regeneration, silently, leaving a
+    # --self-test flag that reported PASS while asserting nothing.
+    #
+    # So the seam is a separate module the generator never writes. A package
+    # with real machinery to prove puts it in _selftest.py; everything else
+    # keeps the honest answer below rather than a self-test that only ever
+    # passes.
+    argv = list(argv if argv is not None else __import__("sys").argv[1:])
+    if "--self-test" in argv:
+        try:
+            from . import _selftest as _st
+        except Exception:
+            print("no _selftest module: this doctor reports the stack, and has",
+                  "no machinery of its own to prove")
+            return 0
+        return int(_st.run())
+    return report()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

awclassify-0.1.0/awclassify/cli.py

@@ -0,0 +1,161 @@
+"""awclassify CLI.
+
+    awclassify classify <file> [--server URL] [--token T] [--json]
+    awclassify taxonomy [--server URL] [--json]
+
+`classify` always runs the deterministic local rules first (offline, never
+raises). With `--server` the document is also posted to a classify-shaped
+surface for the full LLM-powered classification — and the server's answer
+is the one printed when it arrives. Without a server (or when the server is
+unreachable) the rules classification is printed with an explicit "not
+verified" warning: rules never assert "public", and `classified: False`
+means you must not ship the document as public on this output alone.
+
+Exit codes: 0 a classification was produced; 1 the file could not be read
+or `--require-server` was given and the surface was unreachable.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from awclassify import __version__
+from awclassify.client import ClassifyClient
+from awclassify.rules import classify_rules
+from awclassify.taxonomy import AUDIENCES, DOC_TYPES, VISIBILITIES
+
+MAX_READ_CHARS = 500_000
+
+
+def _read_document(path: str) -> str:
+    data = Path(path).read_bytes()
+    # Decode as UTF-8 with a tolerant fallback (decks and reports are usually
+    # UTF-8; a binary file produces a rules-only result with a clear reason).
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        text = data.decode("utf-8", errors="replace")
+    return text[:MAX_READ_CHARS]
+
+
+def _print_human(result: dict, warned: bool) -> None:
+    print(f"doc_type    {result.get('doc_type', 'other')}")
+    print(f"visibility  {result.get('visibility', 'internal')}")
+    print(f"audience    {result.get('audience', 'other')}")
+    print(f"topics      {', '.join(result.get('topics') or []) or '-'}")
+    print(f"engine      {result.get('engine', 'none')}   "
+          f"classified={result.get('classified', False)}")
+    if result.get("reasons"):
+        print("reasons")
+        for r in result["reasons"]:
+            print(f"  - {r}")
+    if warned:
+        print("\nNOT VERIFIED: rules-only classification. Pass --server for the full")
+        print("engine. Per the fail-closed contract, do not publish on this alone.")
+
+
+def cmd_classify(args) -> int:
+    try:
+        content = _read_document(args.file)
+    except OSError as e:
+        print(f"awclassify: cannot read {args.file}: {e}", file=sys.stderr)
+        return 1
+
+    result = classify_rules(content, filename=Path(args.file).name)
+    warned = False
+
+    if args.server:
+        client = ClassifyClient(surface=args.server, token=args.token,
+                                internal_key=args.internal_key)
+        server = client.classify(content, title=args.title,
+                                 source_type=args.source_type)
+        if server.get("classified"):
+            result = server  # the server's verified answer wins
+        else:
+            warned = True
+            result = server if server.get("engine") != "none" else result
+            if args.require_server:
+                for r in server.get("reasons", []):
+                    print(f"awclassify: server: {r}", file=sys.stderr)
+                return 1
+    else:
+        warned = True  # rules-only is always "not verified"
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        _print_human(result, warned)
+    return 0
+
+
+def cmd_taxonomy(args) -> int:
+    local = {"doc_types": DOC_TYPES, "visibilities": VISIBILITIES,
+             "audiences": AUDIENCES}
+    if args.server:
+        # Fetch the server's taxonomy (public endpoint) and report drift.
+        import urllib.error
+        import urllib.request
+        try:
+            req = urllib.request.Request(args.server.rstrip("/") + "/taxonomy")  # noqa: S310 — user-configured
+            with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310
+                server = json.loads(resp.read().decode("utf-8"))
+            for key in local:
+                if local[key] != server.get(key, []):
+                    print(f"warning: {key} differs from the server", file=sys.stderr)
+        except (urllib.error.URLError, OSError, json.JSONDecodeError) as e:
+            print(f"awclassify: cannot fetch server taxonomy: {e}", file=sys.stderr)
+    if args.json:
+        print(json.dumps(local, indent=2))
+    else:
+        for key in local:
+            print(f"{key}: {', '.join(local[key])}")
+    return 0
+
+
+def main(argv=None) -> int:
+    # GENERATED doctor intercept (gen_aw_doctor.py) -- do not edit
+    _dv = locals().get("argv")
+    if (_dv if _dv is not None else __import__("sys").argv[1:])[:1] == ["doctor"]:
+        from ._doctor import report
+        return report()
+    # GENERATED repo-state intercept (gen_aw_doctor.py) -- do not edit
+    try:
+        from awgit import state as _aw_state
+    except Exception:
+        _aw_state = None
+    if _aw_state is not None:
+        _sv = locals().get("argv")
+        if _aw_state.cli_banner(_sv if _sv is not None else __import__("sys").argv[1:]):
+            return 0
+    parser = argparse.ArgumentParser(
+        prog="awclassify",
+        description="Classify a document: type, visibility, audience, topics.",
+    )
+    parser.add_argument("--version", action="version", version=f"awclassify {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser("classify", help="classify a document")
+    c.add_argument("file")
+    c.add_argument("--server", default="", help="classify-shaped server URL")
+    c.add_argument("--token", default="", help="Bearer token for the server")
+    c.add_argument("--internal-key", default="", dest="internal_key",
+                   help="X-Internal-Key for a self-hosted platform server")
+    c.add_argument("--title", default="")
+    c.add_argument("--source-type", default="", dest="source_type")
+    c.add_argument("--require-server", action="store_true",
+                   help="exit 1 when the server is unreachable")
+    c.add_argument("--json", action="store_true")
+    c.set_defaults(func=cmd_classify)
+
+    t = sub.add_parser("taxonomy", help="print the fixed vocabulary")
+    t.add_argument("--server", default="")
+    t.add_argument("--json", action="store_true")
+    t.set_defaults(func=cmd_taxonomy)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

awclassify-0.1.0/awclassify/client.py

@@ -0,0 +1,86 @@
+"""Client for a classify-shaped server.
+
+Zero dependencies (stdlib urllib). Speaks the contract of the platform's
+`/classify` surface — POST a document, get back the classification — and of
+any server that implements the same shape:
+
+    POST /classify
+    {"content": "...", "title": "...", "source_type": "..."}
+    -> {"classification": {doc_type, visibility, audience, topics, ...}}
+
+Auth is optional: a Bearer token (platform sessions), or an internal key
+(sent as X-Internal-Key + X-Caller-Type: platform for self-hosted platform
+servers). On ANY failure the client returns the fail-closed shape
+(classified=False, visibility="internal") with the reason — it never
+fabricates a classification.
+"""
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict
+
+DEFAULT_SURFACE = "http://127.0.0.1:8001/doc-classify"
+# NOT /classify: on the AitherOS platform that path is the INTENT classifier's
+# (first handler wins, measured 2026-08-29) — the document surface is
+# /doc-classify. Any classify-shaped server may of course use any path.
+
+FAIL_CLOSED = {
+    "classified": False,
+    "engine": "none",
+    "visibility": "internal",
+    "reasons": ["client: surface unreachable"],
+}
+
+
+class ClassifyClient:
+    """Minimal client for POST /classify on a classify-shaped server."""
+
+    def __init__(self, surface: str = "", token: str = "",
+                 internal_key: str = "", timeout: float = 200.0):
+        # 200s default: a classify-shaped server's LLM round trip is minutes,
+        # not seconds (measured live 2026-08-29 on the platform: ~2 min).
+        self.surface = (surface or DEFAULT_SURFACE).rstrip("/")
+        self.token = token
+        self.internal_key = internal_key
+        self.timeout = timeout
+
+    def classify(
+        self,
+        content: str,
+        *,
+        title: str = "",
+        source_type: str = "",
+        filename: str = "",
+    ) -> Dict[str, Any]:
+        """Classify a document. Fail-closed shape on ANY failure."""
+        payload = json.dumps({
+            "content": content,
+            "title": title,
+            "source_type": source_type,
+            "filename": filename,
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            self.surface,
+            data=payload,
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            method="POST",
+        )
+        if self.token:
+            req.add_header("Authorization", f"Bearer {self.token}")
+        if self.internal_key:
+            req.add_header("X-Internal-Key", self.internal_key)
+            req.add_header("X-Caller-Type", "platform")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:  # noqa: S310 — surface is user-configured
+                data = json.loads(resp.read().decode("utf-8"))
+            if isinstance(data, dict) and isinstance(data.get("classification"), dict):
+                return data["classification"]
+            if isinstance(data, dict) and "doc_type" in data:
+                return data
+            return dict(FAIL_CLOSED, reasons=["client: unexpected response shape"])
+        except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError) as e:
+            return dict(FAIL_CLOSED, reasons=[f"client: {type(e).__name__}: {e}"])

awclassify-0.1.0/awclassify/rules.py

@@ -0,0 +1,99 @@
+"""Deterministic local classifier — the offline tier of awclassify.
+
+A standalone twin of the platform engine's rules path
+(`lib.knowledge.DocClassifier.rules_classify`), deliberately without any
+monorepo import so this package ships to strangers. The parity gate keeps
+the taxonomy in step; the rules here are the same shape and intent.
+
+CONTRACT:
+  - `classified` is always False in the rules result: rules are heuristics,
+    not verification — a stranger must not ship on them.
+  - visibility NEVER becomes "public" from a filename alone. An explicit
+    PUBLIC marker is required.
+  - every decision is recorded in `reasons`.
+"""
+
+import re
+from typing import Dict, List
+
+#: Explicit markers that let the rules path assert "public" — the ONLY
+#: filename/source evidence this module trusts for publicity.
+PUBLIC_MARKERS = (".public.", "public/", "PUBLIC.md", "-public")
+
+_TYPE_RULES = [
+    (re.compile(r"\.deck\.json$|_deck\.py$|\.pptx?$|slides", re.I), "deck"),
+    (re.compile(r"transcript|session-log|conversation-log|chat-log", re.I), "transcript"),
+    (re.compile(r"\bprd\b|\.prd|product-requirements|requirements\.md", re.I), "prd"),
+    (re.compile(r"decision|adr-|ADR_", re.I), "decision"),
+    (re.compile(r"^blog|/blog|posts?/", re.I), "blog"),
+    (re.compile(r"minutes|meeting-notes|notes\.md", re.I), "minutes"),
+    (re.compile(r"^docs?/|documentation|manual|guide", re.I), "docs"),
+    (re.compile(r"contract|agreement|terms|license", re.I), "contract"),
+    (re.compile(r"\.(py|ts|tsx|js|go|rs|java|c|cpp|sh)$", re.I), "code"),
+    (re.compile(r"\.(csv|json|yaml|yml|xml|parquet|sql)$", re.I), "data"),
+    (re.compile(r"research|experiment|benchmark|evaluation", re.I), "research"),
+    (re.compile(r"report|summary|status", re.I), "report"),
+    (re.compile(r"spec|api[-_.]?doc|design[-_.]?doc", re.I), "spec"),
+    (re.compile(r"memo|brief", re.I), "memo"),
+]
+
+_AUDIENCE_RULES = [
+    (re.compile(r"^customers?/|customer-facing|sales", re.I), "customers"),
+    (re.compile(r"investor|pitch|fundraising|cap-table", re.I), "investors"),
+    (re.compile(r"partner|integrat", re.I), "partners"),
+    (re.compile(r"regulatory|compliance|audit", re.I), "regulatory"),
+    (re.compile(r"^internal|internal-", re.I), "internal"),
+]
+
+
+def classify_rules(
+    content: str = "",
+    *,
+    filename: str = "",
+    title: str = "",
+    source_type: str = "",
+) -> Dict:
+    """Deterministic classification from filenames, titles and source types.
+
+    Zero I/O, zero network, zero dependencies. Never raises. Always returns
+    the full result shape with `classified: False` and `reasons` — the same
+    shape a classify-shaped server returns, so consumers handle one contract.
+    """
+    haystack = " ".join(filter(None, [filename, title, source_type]))
+    reasons: List[str] = []
+
+    doc_type = "other"
+    for pat, t in _TYPE_RULES:
+        if pat.search(haystack):
+            doc_type = t
+            reasons.append(f"rules: type={t} (matched {pat.pattern})")
+            break
+
+    audience = "other"
+    for pat, a in _AUDIENCE_RULES:
+        if pat.search(haystack):
+            audience = a
+            reasons.append(f"rules: audience={a}")
+            break
+
+    topics: List[str] = []
+    if any(k in haystack.lower() for k in ("revenue", "sales", "deal", "customer")):
+        topics.append("business")
+    if any(k in haystack.lower() for k in ("agent", "ai", "llm", "model")):
+        topics.append("ai")
+
+    visibility = "internal"
+    if any(m in haystack for m in PUBLIC_MARKERS):
+        visibility = "public"
+        reasons.append("rules: visibility=public (explicit PUBLIC marker)")
+
+    return {
+        "doc_type": doc_type,
+        "visibility": visibility,
+        "audience": audience,
+        "topics": topics,
+        "confidence": 0.55 if reasons else 0.0,
+        "engine": "rules",
+        "classified": False,
+        "reasons": reasons or ["rules: no evidence matched"],
+    }

awclassify-0.1.0/awclassify/taxonomy.py

@@ -0,0 +1,22 @@
+"""The fixed classification vocabulary — standalone copy.
+
+This file is the PUBLIC copy of the taxonomy. The platform engine's copy
+lives in `lib.knowledge.DocClassifier`; the parity gate
+(`check_classify_taxonomy_parity.py`) asserts the two stay in step, because
+two copies of a rule set drift — the same shape as the shared browser
+inference worker, and the reason that lesson is a gate here rather than a
+comment.
+"""
+
+DOC_TYPES = [
+    "deck", "blog", "prd", "report", "transcript", "memo", "decision",
+    "spec", "docs", "guide", "code", "data", "email", "social", "minutes",
+    "contract", "research", "other",
+]
+
+VISIBILITIES = ["public", "internal", "confidential"]
+
+AUDIENCES = [
+    "customers", "investors", "partners", "general_public", "internal",
+    "agents", "regulatory", "other",
+]

awclassify-0.1.0/awclassify.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: awclassify
+Version: 0.1.0
+Summary: Classify any document — type, visibility, audience, topics. Aither World Classify.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Aitherium/awclassify
+Project-URL: Documentation, https://github.com/Aitherium/awclassify#readme
+Project-URL: Repository, https://github.com/Aitherium/awclassify.git
+Project-URL: Issues, https://github.com/Aitherium/awclassify/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# awclassify
+
+**Aither World Classify** — classify any document: *what it is*, *who may
+read it*, *who it is for*, *what it is about*. A standalone, zero-dependency
+CLI + client, public and pip-installable, for the Aither World stack.
+
+```bash
+pip install awclassify
+
+awclassify classify report.md
+# doc_type    report
+# visibility  internal
+# audience    other
+# topics      -
+# engine      rules   classified=False
+#
+# NOT VERIFIED: rules-only classification. Pass --server for the full
+# engine. Per the fail-closed contract, do not publish on this alone.
+```
+
+## What it answers
+
+| field | meaning | vocabulary |
+|---|---|---|
+| `doc_type` | what it is | deck, blog, prd, transcript, report, memo, decision, spec, docs, guide, code, data, email, social, minutes, contract, research, other |
+| `visibility` | who may read it | public, internal, confidential |
+| `audience` | who it is for | customers, investors, partners, general_public, internal, agents, regulatory, other |
+| `topics` | what it is about | 1–5 free-form tags |
+
+## The fail-closed contract
+
+A classification you cannot verify is **NOT public**.
+
+- `classified: False` means the output is heuristic only — do not publish
+  the document on it.
+- The rules path never asserts `public` from a filename alone; an explicit
+  marker (`public/`, `.public.`) is required.
+- When the server cannot be reached, the client returns
+  `classified: False, visibility: internal` with the reason — never a
+  fabricated answer.
+
+To publish a document you need the server-verified answer:
+
+```bash
+awclassify classify deck.json --server https://your-platform/doc-classify \
+  --token "$PLATFORM_BEARER" --json | jq .visibility
+# "public"  ← only now may a stranger read it
+```
+
+## Modes
+
+- **Local rules** (default, offline): deterministic classification from the
+  filename, title and source type. Zero network, zero dependencies.
+- **Server**: `--server URL` posts the document to any classify-shaped
+  surface — the AitherOS platform's `/classify`, or anything implementing
+  the same contract — for the full LLM-powered classification with
+  confidence scores. `--require-server` makes an unreachable surface an
+  error instead of a downgrade.
+
+```bash
+awclassify taxonomy                      # the fixed vocabulary, offline
+awclassify taxonomy --server URL         # ...and diff it against the server's
+```
+
+## Why it exists
+
+A $35K revenue figure shipped in a public slide deck because nothing asked
+what the document was or who could see it. `awclassify` makes that answer
+exist as data before anything ships — one command, no credentials required
+for the local tier.
+
+## Relationship to the platform
+
+`awclassify` is the **client brick**. The service half — the engine
+(`lib.knowledge.DocClassifier`), the genesis `/doc-classify` router, and the
+Nexus-ingest integration — lives in the AitherOS platform as
+`aitherclassify`. The taxonomy parity between the two copies is asserted by
+the platform's `check_classify_taxonomy_parity` gate.
+
+## Development
+
+```bash
+python -m pytest tests/
+```

awclassify-0.1.0/awclassify.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+awclassify/__init__.py
+awclassify/__main__.py
+awclassify/_doctor.py
+awclassify/cli.py
+awclassify/client.py
+awclassify/rules.py
+awclassify/taxonomy.py
+awclassify.egg-info/PKG-INFO
+awclassify.egg-info/SOURCES.txt
+awclassify.egg-info/dependency_links.txt
+awclassify.egg-info/entry_points.txt
+awclassify.egg-info/requires.txt
+awclassify.egg-info/top_level.txt
+tests/test_standalone.py

awclassify-0.1.0/awclassify.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

awclassify-0.1.0/awclassify.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+awclassify = awclassify.cli:main

awclassify-0.1.0/awclassify.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7.0

awclassify-0.1.0/awclassify.egg-info/top_level.txt

@@ -0,0 +1 @@
+awclassify

awclassify-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "awclassify"
+version = "0.1.0"
+description = "Classify any document — type, visibility, audience, topics. Aither World Classify."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+awclassify = "awclassify.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Aitherium/awclassify"
+Documentation = "https://github.com/Aitherium/awclassify#readme"
+Repository = "https://github.com/Aitherium/awclassify.git"
+Issues = "https://github.com/Aitherium/awclassify/issues"
+
+[tool.setuptools]
+packages = ["awclassify"]
+license-files = ["LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501", "E402", "E741"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

awclassify-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

awclassify-0.1.0/tests/test_standalone.py

@@ -0,0 +1,143 @@
+"""Standalone awclassify tests — no network, no server, no monorepo imports.
+
+The rules contract (the fail-closed half) and the CLI plumbing are pinned
+here so the public brick cannot regress without a failing test.
+"""
+
+import json
+from unittest import mock
+
+from awclassify import classify_rules
+from awclassify.client import ClassifyClient
+from awclassify.taxonomy import AUDIENCES, DOC_TYPES, VISIBILITIES
+
+# ---------------------------------------------------------------------------
+# BOUNDARY — the brick must be standalone
+# ---------------------------------------------------------------------------
+
+def test_no_monorepo_imports():
+    from pathlib import Path
+
+    import awclassify.client
+    import awclassify.rules
+    pkg = Path(awclassify.rules.__file__).resolve().parent  # the awclassify/ dir
+    for py in pkg.glob("*.py"):  # the SHIPPED modules — tests excluded by design
+        src = py.read_text(encoding="utf-8")
+        for name in ("from lib", "import lib", "from services", "AitherOS/"):
+            assert name not in src, f"{py.name} must not reference {name!r}"
+
+
+def test_taxonomy_is_wellformed():
+    assert len(DOC_TYPES) >= 10
+    assert "deck" in DOC_TYPES and "other" in DOC_TYPES
+    assert VISIBILITIES == ["public", "internal", "confidential"]
+    assert "investors" in AUDIENCES
+    assert len(set(DOC_TYPES)) == len(DOC_TYPES)
+
+
+# ---------------------------------------------------------------------------
+# RULES CONTRACT
+# ---------------------------------------------------------------------------
+
+def test_rules_never_public_from_filename_alone():
+    r = classify_rules("", filename="investor-pitch-traction-revenue.deck.json")
+    assert r["doc_type"] == "deck"
+    assert r["visibility"] == "internal"
+    assert r["classified"] is False
+    assert r["engine"] == "rules"
+
+
+def test_rules_explicit_public_marker_is_the_only_public_path():
+    assert classify_rules("", filename="docs/public/guide.md")["visibility"] == "public"
+    assert classify_rules("", filename="docs/public-guide.md")["visibility"] == "internal"
+    assert classify_rules("", filename="public-deck-notes.md")["visibility"] == "internal"
+
+
+def test_rules_detects_types():
+    assert classify_rules("", filename="blog/launch.md")["doc_type"] == "blog"
+    assert classify_rules("", filename="session-transcript.txt")["doc_type"] == "transcript"
+    assert classify_rules("", filename="PRD-thing.md")["doc_type"] == "prd"
+    assert classify_rules("", filename="train.py")["doc_type"] == "code"
+    assert classify_rules("", filename="export.csv")["doc_type"] == "data"
+
+
+def test_rules_result_shape_matches_server_contract():
+    r = classify_rules("")
+    for key in ("doc_type", "visibility", "audience", "topics",
+                "confidence", "engine", "classified", "reasons"):
+        assert key in r
+    assert isinstance(r["reasons"], list) and r["reasons"]
+
+
+# ---------------------------------------------------------------------------
+# CLIENT FAIL-CLOSED
+# ---------------------------------------------------------------------------
+
+def test_client_fails_closed_on_unreachable_surface():
+    out = ClassifyClient(surface="http://127.0.0.1:1/classify").classify("x")
+    assert out["classified"] is False
+    assert out["visibility"] == "internal"
+    assert out["engine"] == "none"
+    assert any("client" in r for r in out["reasons"])
+
+
+def test_client_parses_classification_shape():
+    def _fake_urlopen(req, timeout=None):
+        class _R:
+            def read(self):
+                return json.dumps({"classification": {
+                    "doc_type": "deck", "visibility": "internal",
+                    "audience": "investors", "topics": ["revenue"],
+                    "engine": "llm", "classified": True,
+                }}).encode()
+            def __enter__(self):
+                return self
+            def __exit__(self, *a):
+                return False
+        return _R()
+
+    with mock.patch("urllib.request.urlopen", _fake_urlopen):
+        out = ClassifyClient(surface="http://x/classify").classify("deck")
+    assert out["classified"] is True
+    assert out["doc_type"] == "deck"
+    assert out["visibility"] == "internal"
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def test_cli_classify_rules_only(tmp_path):
+    from awclassify.cli import main
+    f = tmp_path / "x.deck.json"
+    f.write_text("deck about revenue", encoding="utf-8")
+    rc = main(["classify", str(f)])
+    assert rc == 0
+
+
+def test_cli_classify_json(tmp_path):
+    from awclassify.cli import main
+    f = tmp_path / "x.deck.json"
+    f.write_text("deck", encoding="utf-8")
+    rc = main(["classify", str(f), "--json"])
+    assert rc == 0
+
+
+def test_cli_require_server_unreachable_exits_1(tmp_path):
+    from awclassify.cli import main
+    f = tmp_path / "x.deck.json"
+    f.write_text("deck", encoding="utf-8")
+    rc = main(["classify", str(f), "--server", "http://127.0.0.1:1/classify",
+               "--require-server"])
+    assert rc == 1
+
+
+def test_cli_missing_file_exits_1(tmp_path):
+    from awclassify.cli import main
+    rc = main(["classify", str(tmp_path / "nope.md")])
+    assert rc == 1
+
+
+def test_cli_taxonomy():
+    from awclassify.cli import main
+    assert main(["taxonomy"]) == 0