axor-telemetry 0.1.0__tar.gz

axor_telemetry-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Checkout axor-core
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository_owner }}/axor-core
+          path: axor-core
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          pip install -e axor-core/
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches package version
+        run: |
+          python - << 'EOF'
+          import pathlib
+          import re
+          import sys
+          import tomllib
+
+          ref = "${{ github.ref_name }}"
+          m = re.fullmatch(r"v(\d+\.\d+\.\d+)", ref)
+          if not m:
+              print(f"Tag {ref!r} must match vX.Y.Z")
+              sys.exit(1)
+
+          tag_version = m.group(1)
+          data = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
+          pkg_version = data["project"]["version"]
+
+          if tag_version != pkg_version:
+              print(f"Version mismatch: tag={tag_version}, pyproject={pkg_version}")
+              sys.exit(1)
+
+          print(f"Version check passed: {pkg_version}")
+          EOF
+
+      - name: Build
+        run: |
+          pip install hatchling build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

axor_telemetry-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+dist/
+build/
+*.egg-info/
+.venv/

axor_telemetry-0.1.0/LICENSE

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

axor_telemetry-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: axor-telemetry
+Version: 0.1.0
+Summary: Anonymous telemetry pipeline for axor-core: MinHash embedder, local/HTTP sinks, opt-in consent CLI
+Project-URL: Repository, https://github.com/Bucha11/axor-telemetry
+Project-URL: Bug Tracker, https://github.com/Bucha11/axor-telemetry/issues
+Project-URL: Changelog, https://github.com/Bucha11/axor-telemetry/releases
+License: MIT
+License-File: LICENSE
+Keywords: agents,axor,minhash,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: core
+Requires-Dist: axor-core>=0.3.0; extra == 'core'
+Provides-Extra: dev
+Requires-Dist: axor-core>=0.3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# axor-telemetry
+
+Anonymous telemetry pipeline for [axor-core](https://github.com/Bucha11/axor-core).
+
+**Opt-in only.** Nothing is sent without explicit user consent.
+
+## What gets sent (when consent is given)
+
+- `signal_chosen` (e.g. `focused_generative`)
+- `classifier_used`, `confidence`
+- MinHash fingerprint of the raw input (128 ints, non-reversible)
+- `tokens_spent`, `policy_adjusted`
+- `axor_version`
+
+**Not sent:** raw task text, file contents, user or session identifiers,
+tool arguments, secrets.
+
+## Install
+
+```bash
+pip install axor-telemetry[core]
+```
+
+## CLI
+
+```bash
+python -m axor_telemetry consent   # interactive opt-in
+python -m axor_telemetry status    # show current config
+python -m axor_telemetry preview   # show the last queued record
+python -m axor_telemetry on        # non-interactive: set local mode
+python -m axor_telemetry off       # disable
+```
+
+Config lives at `~/.axor/config.toml` under `[telemetry]`.
+
+## Modes
+
+| mode     | behavior |
+|----------|----------|
+| `off`    | Default. Pipeline does nothing. |
+| `local`  | Writes to `~/.axor/telemetry_queue.jsonl`. Never sent anywhere. |
+| `remote` | Writes local queue + ships batches to `telemetry.useaxor.net/v1/records`. Retry-on-next-start if offline. |
+
+## Programmatic usage
+
+```python
+from axor_telemetry import TelemetryPipeline, MinHashEmbedder, FileTelemetrySink
+
+pipeline = TelemetryPipeline(
+    embedder=MinHashEmbedder(),
+    sink=FileTelemetrySink(queue_path="~/.axor/telemetry_queue.jsonl"),
+)
+```
+
+Inject `pipeline` into `GovernedSession` (see axor-cli integration).

axor_telemetry-0.1.0/README.md

@@ -0,0 +1,55 @@
+# axor-telemetry
+
+Anonymous telemetry pipeline for [axor-core](https://github.com/Bucha11/axor-core).
+
+**Opt-in only.** Nothing is sent without explicit user consent.
+
+## What gets sent (when consent is given)
+
+- `signal_chosen` (e.g. `focused_generative`)
+- `classifier_used`, `confidence`
+- MinHash fingerprint of the raw input (128 ints, non-reversible)
+- `tokens_spent`, `policy_adjusted`
+- `axor_version`
+
+**Not sent:** raw task text, file contents, user or session identifiers,
+tool arguments, secrets.
+
+## Install
+
+```bash
+pip install axor-telemetry[core]
+```
+
+## CLI
+
+```bash
+python -m axor_telemetry consent   # interactive opt-in
+python -m axor_telemetry status    # show current config
+python -m axor_telemetry preview   # show the last queued record
+python -m axor_telemetry on        # non-interactive: set local mode
+python -m axor_telemetry off       # disable
+```
+
+Config lives at `~/.axor/config.toml` under `[telemetry]`.
+
+## Modes
+
+| mode     | behavior |
+|----------|----------|
+| `off`    | Default. Pipeline does nothing. |
+| `local`  | Writes to `~/.axor/telemetry_queue.jsonl`. Never sent anywhere. |
+| `remote` | Writes local queue + ships batches to `telemetry.useaxor.net/v1/records`. Retry-on-next-start if offline. |
+
+## Programmatic usage
+
+```python
+from axor_telemetry import TelemetryPipeline, MinHashEmbedder, FileTelemetrySink
+
+pipeline = TelemetryPipeline(
+    embedder=MinHashEmbedder(),
+    sink=FileTelemetrySink(queue_path="~/.axor/telemetry_queue.jsonl"),
+)
+```
+
+Inject `pipeline` into `GovernedSession` (see axor-cli integration).

axor_telemetry-0.1.0/axor_telemetry/__init__.py

@@ -0,0 +1,31 @@
+"""
+axor-telemetry
+──────────────
+Anonymous telemetry pipeline for axor-core. Opt-in only.
+
+Public surface:
+- MinHashEmbedder    — pure-Python 128-dim char-3 MinHash fingerprint
+- FileTelemetrySink  — JSONL queue at ~/.axor/telemetry_queue.jsonl
+- HTTPTelemetrySink  — POST batches with retry-on-next-start
+- TelemetryPipeline  — trace → anonymize → dispatch
+- TelemetryConfig    — resolved mode + endpoint from env + config.toml
+"""
+
+from axor_telemetry.embedder import MinHashEmbedder
+from axor_telemetry.sinks.file_sink import FileTelemetrySink
+from axor_telemetry.sinks.http_sink import HTTPTelemetrySink
+from axor_telemetry.pipeline import TelemetryPipeline, build_pipeline
+from axor_telemetry.config import TelemetryConfig, TelemetryMode
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MinHashEmbedder",
+    "FileTelemetrySink",
+    "HTTPTelemetrySink",
+    "TelemetryPipeline",
+    "build_pipeline",
+    "TelemetryConfig",
+    "TelemetryMode",
+    "__version__",
+]

axor_telemetry-0.1.0/axor_telemetry/__main__.py

@@ -0,0 +1,4 @@
+from axor_telemetry.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

axor_telemetry-0.1.0/axor_telemetry/cli.py

@@ -0,0 +1,165 @@
+"""
+CLI for axor-telemetry: `python -m axor_telemetry <command>`.
+
+Commands:
+  consent  — interactive opt-in; writes mode + endpoint to ~/.axor/config.toml
+  status   — show current effective config (env + file merged)
+  preview  — print the last queued record so the user sees exactly what goes out
+  on       — non-interactive: set mode=local
+  off      — disable telemetry
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from axor_telemetry.config import TelemetryConfig, TelemetryMode
+
+
+def cmd_consent(args: argparse.Namespace, stream=sys.stdout, prompt_input=input) -> int:
+    current = TelemetryConfig.load()
+    stream.write(_consent_text(current))
+    stream.flush()
+    try:
+        answer = prompt_input("> ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        stream.write("\naborted. no change.\n")
+        return 1
+
+    if answer in ("r", "remote"):
+        new = TelemetryConfig(mode=TelemetryMode.REMOTE, endpoint=current.endpoint,
+                              queue_path=current.queue_path,
+                              fingerprint_kind=current.fingerprint_kind)
+    elif answer in ("l", "local"):
+        new = TelemetryConfig(mode=TelemetryMode.LOCAL, endpoint=current.endpoint,
+                              queue_path=current.queue_path,
+                              fingerprint_kind=current.fingerprint_kind)
+    else:
+        new = TelemetryConfig(mode=TelemetryMode.OFF, endpoint=current.endpoint,
+                              queue_path=current.queue_path,
+                              fingerprint_kind=current.fingerprint_kind)
+
+    path = new.write()
+    stream.write(f"saved to {path}: mode={new.mode.value}\n")
+    return 0
+
+
+def cmd_status(args: argparse.Namespace, stream=sys.stdout) -> int:
+    cfg = TelemetryConfig.load()
+    stream.write(f"mode:             {cfg.mode.value}\n")
+    stream.write(f"endpoint:         {cfg.endpoint}\n")
+    stream.write(f"queue_path:       {cfg.queue_path}\n")
+    stream.write(f"fingerprint_kind: {cfg.fingerprint_kind}\n")
+    queue = Path(cfg.queue_path).expanduser()
+    if queue.is_file():
+        try:
+            size = queue.stat().st_size
+        except OSError:
+            size = 0
+        stream.write(f"queue_bytes:      {size}\n")
+    return 0
+
+
+def cmd_preview(args: argparse.Namespace, stream=sys.stdout) -> int:
+    cfg = TelemetryConfig.load()
+    queue = Path(cfg.queue_path).expanduser()
+    if not queue.is_file():
+        stream.write("queue is empty (no records have been generated yet).\n")
+        return 0
+    last = None
+    try:
+        with queue.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    last = line
+    except OSError as exc:
+        stream.write(f"failed to read queue: {exc}\n")
+        return 1
+    if not last:
+        stream.write("queue file exists but is empty.\n")
+        return 0
+    try:
+        record = json.loads(last)
+        stream.write(json.dumps(record, indent=2, ensure_ascii=False) + "\n")
+    except json.JSONDecodeError:
+        stream.write(last + "\n")
+    return 0
+
+
+def cmd_on(args: argparse.Namespace, stream=sys.stdout) -> int:
+    current = TelemetryConfig.load()
+    mode = TelemetryMode.REMOTE if args.remote else TelemetryMode.LOCAL
+    new = TelemetryConfig(mode=mode, endpoint=current.endpoint,
+                          queue_path=current.queue_path,
+                          fingerprint_kind=current.fingerprint_kind)
+    path = new.write()
+    stream.write(f"telemetry is now {mode.value}. config: {path}\n")
+    return 0
+
+
+def cmd_off(args: argparse.Namespace, stream=sys.stdout) -> int:
+    current = TelemetryConfig.load()
+    new = TelemetryConfig(mode=TelemetryMode.OFF, endpoint=current.endpoint,
+                          queue_path=current.queue_path,
+                          fingerprint_kind=current.fingerprint_kind)
+    path = new.write()
+    stream.write(f"telemetry disabled. config: {path}\n")
+    return 0
+
+
+def _consent_text(current: TelemetryConfig) -> str:
+    return (
+        "axor telemetry is opt-in. Nothing has been sent yet.\n"
+        "\n"
+        "What gets collected (when enabled):\n"
+        "  - chosen classification (e.g. focused_generative)\n"
+        "  - classifier name + confidence\n"
+        "  - a 128-int MinHash fingerprint of the raw input (non-reversible)\n"
+        "  - tokens spent, whether policy was adjusted mid-run\n"
+        "\n"
+        "What is NEVER collected:\n"
+        "  - raw task text, file contents, tool arguments, secrets\n"
+        "  - user/session identifiers\n"
+        "\n"
+        f"Current mode: {current.mode.value}\n"
+        f"Endpoint (remote mode): {current.endpoint}\n"
+        "\n"
+        "Choose:\n"
+        "  [l] local  — write records to a local JSONL queue, never send anywhere\n"
+        "  [r] remote — also ship to the project telemetry server (retry on next start if offline)\n"
+        "  [n] off    — do nothing (default)\n"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="python -m axor_telemetry")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("consent", help="interactive opt-in prompt")
+    sub.add_parser("status",  help="show current effective config")
+    sub.add_parser("preview", help="print the last queued record")
+    on_parser = sub.add_parser("on", help="enable telemetry (local by default)")
+    on_parser.add_argument("--remote", action="store_true", help="enable remote shipping")
+    sub.add_parser("off", help="disable telemetry")
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    dispatch = {
+        "consent": cmd_consent,
+        "status":  cmd_status,
+        "preview": cmd_preview,
+        "on":      cmd_on,
+        "off":     cmd_off,
+    }
+    return dispatch[args.cmd](args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

axor_telemetry-0.1.0/axor_telemetry/config.py

@@ -0,0 +1,145 @@
+"""
+Telemetry configuration — resolved from env and ~/.axor/config.toml.
+
+Priority (highest first):
+  1. env vars AXOR_TELEMETRY, AXOR_TELEMETRY_ENDPOINT, AXOR_TELEMETRY_QUEUE
+  2. ~/.axor/config.toml [telemetry] section
+  3. defaults (off, stock endpoint, ~/.axor/telemetry_queue.jsonl)
+"""
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+_CONFIG_PATH = Path("~/.axor/config.toml").expanduser()
+_DEFAULT_QUEUE = "~/.axor/telemetry_queue.jsonl"
+_DEFAULT_ENDPOINT = "https://telemetry.useaxor.net/v1/records"
+
+
+class TelemetryMode(str, Enum):
+    OFF    = "off"
+    LOCAL  = "local"
+    REMOTE = "remote"
+
+
+@dataclass(frozen=True)
+class TelemetryConfig:
+    mode: TelemetryMode = TelemetryMode.OFF
+    endpoint: str       = _DEFAULT_ENDPOINT
+    queue_path: str     = _DEFAULT_QUEUE
+    fingerprint_kind: str = "minhash_v1"
+
+    @property
+    def enabled(self) -> bool:
+        return self.mode is not TelemetryMode.OFF
+
+    @property
+    def ships_remote(self) -> bool:
+        return self.mode is TelemetryMode.REMOTE
+
+    @classmethod
+    def load(cls, config_path: Path | None = None) -> "TelemetryConfig":
+        """Resolve config from env + TOML file. Returns defaults when nothing is set."""
+        path = config_path or _CONFIG_PATH
+        data: dict = {}
+        if path.is_file():
+            try:
+                with path.open("rb") as fh:
+                    data = tomllib.load(fh).get("telemetry", {}) or {}
+            except (OSError, tomllib.TOMLDecodeError):
+                data = {}
+
+        env_mode = os.environ.get("AXOR_TELEMETRY")
+        mode_raw = env_mode or data.get("mode") or "off"
+        try:
+            mode = TelemetryMode(mode_raw.lower())
+        except ValueError:
+            mode = TelemetryMode.OFF
+
+        endpoint   = os.environ.get("AXOR_TELEMETRY_ENDPOINT")   or data.get("endpoint")   or _DEFAULT_ENDPOINT
+        queue_path = os.environ.get("AXOR_TELEMETRY_QUEUE")      or data.get("queue_path") or _DEFAULT_QUEUE
+        fingerprint_kind = data.get("fingerprint_kind") or "minhash_v1"
+
+        return cls(
+            mode=mode,
+            endpoint=endpoint,
+            queue_path=queue_path,
+            fingerprint_kind=fingerprint_kind,
+        )
+
+    def write(self, config_path: Path | None = None) -> Path:
+        """
+        Persist [telemetry] section to ~/.axor/config.toml, preserving other
+        sections already present. Atomic: writes to tmp file then renames.
+        """
+        path = config_path or _CONFIG_PATH
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        existing = ""
+        if path.is_file():
+            try:
+                existing = path.read_text(encoding="utf-8")
+            except OSError:
+                existing = ""
+
+        section = self._render_section()
+        new_text = _replace_section(existing, "telemetry", section)
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_text(new_text, encoding="utf-8")
+        os.replace(tmp, path)
+        try:
+            path.chmod(0o600)
+        except OSError:
+            pass
+        return path
+
+    def _render_section(self) -> str:
+        return (
+            "[telemetry]\n"
+            f'mode = "{self.mode.value}"\n'
+            f'endpoint = "{_escape_toml(self.endpoint)}"\n'
+            f'queue_path = "{_escape_toml(self.queue_path)}"\n'
+            f'fingerprint_kind = "{_escape_toml(self.fingerprint_kind)}"\n'
+        )
+
+
+def _escape_toml(s: str) -> str:
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _replace_section(text: str, section: str, new_block: str) -> str:
+    """
+    Rewrite a single `[section]` block in a TOML document. If missing, append.
+    Preserves all other sections verbatim.
+    """
+    lines = text.splitlines(keepends=True)
+    out: list[str] = []
+    i = 0
+    replaced = False
+    header = f"[{section}]"
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+        if stripped == header:
+            # skip until next header or EOF
+            j = i + 1
+            while j < len(lines) and not lines[j].lstrip().startswith("["):
+                j += 1
+            out.append(new_block)
+            if j < len(lines):
+                out.append("\n")
+            i = j
+            replaced = True
+            continue
+        out.append(line)
+        i += 1
+    if not replaced:
+        if out and not out[-1].endswith("\n"):
+            out.append("\n")
+        if out:
+            out.append("\n")
+        out.append(new_block)
+    return "".join(out)