atif-make 0.1.0__tar.gz

atif_make-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: publish
+
+# Publishes to PyPI when a version tag is pushed:
+#
+#     git tag v0.1.0 && git push origin v0.1.0
+#
+# Authentication uses PyPI Trusted Publishing (OIDC), so no API token is stored
+# anywhere. GitHub mints a short-lived identity for this workflow and PyPI
+# verifies it against the publisher configured for the project.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Required for trusted publishing; nothing else needs write access.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Refuse to publish a tag that disagrees with the version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(uv version --short)
+          if [ "$tag" != "$pkg" ]; then
+            echo "tag $tag does not match project version $pkg" >&2
+            exit 1
+          fi
+
+      - run: uv build
+      - run: uv publish --trusted-publishing always

atif_make-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install ${{ matrix.python-version }}
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest -q
+
+      # The spec suite validates output against harbor's reference ATIF models.
+      # It pulls a large dependency tree, so it runs on one version only.
+      - name: Validate against the ATIF reference models
+        if: matrix.python-version == '3.12'
+        run: uv run --python 3.12 --extra spec pytest -q tests/test_spec_compliance.py

atif_make-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+# Never commit converted transcripts — they contain real session content.
+*.trajectory.json
+dist/

atif_make-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: atif-make
+Version: 0.1.0
+Summary: Convert agent logs (Claude Code, Codex, Copilot, HAR) into ATIF v1.7 trajectories.
+License: MIT
+Requires-Python: >=3.12
+Provides-Extra: spec
+Requires-Dist: harbor>=0.21.0; extra == 'spec'
+Description-Content-Type: text/markdown
+
+# atif-make
+
+Make [ATIF v1.7](https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md)
+trajectories from agent logs — Claude Code, Codex, Copilot CLI, and HAR captures.
+
+Zero runtime dependencies. Python 3.12+.
+
+## Install
+
+```sh
+uv tool install atif-make          # puts `atif-make` on your PATH
+```
+
+Or as a library in a project:
+
+```sh
+uv add atif-make
+```
+
+For a browser view of what you convert, see the companion
+[`atif-view`](https://github.com/jammastergirish/atif-view), which depends on this package.
+
+`uv tool install` builds an isolated environment, so nothing lands in your
+project or system Python. To follow local edits instead, use
+`uv tool install --editable .`; to remove it, `uv tool uninstall atif-make`.
+
+Running from a checkout without installing works too: `uv run atif-make ...`.
+
+```sh
+atif-make ~/.claude/projects/my-project/session.jsonl   # convert one log
+atif-make index --stats                                 # what do I have, across agents?
+```
+
+## Commands
+
+```
+atif-make <file>                 convert (shorthand for `atif-make convert`)
+atif-make convert <file>         convert one log
+atif-make convert <dir|archive>  convert every log inside
+atif-make index [roots...]       scan for sessions across agents
+atif-make formats                list supported input formats
+```
+
+| Flag | Command | Meaning |
+|---|---|---|
+| `-o, --output` | convert | output path (default `<input>.trajectory.json`) |
+| `-f, --format` | convert | force the input format instead of detecting it |
+| `--json` | convert | write one self-contained document to stdout |
+| `--bundle OUT.zip` | convert | zip the trajectory with its images and subagents |
+| `--split-subagents` | convert | write subagents as sibling files, not embedded |
+| `--indent N` | convert | JSON indent (default 2) |
+| `-q, --quiet` | convert | suppress progress output |
+| `--stats` | index | print a per-agent summary |
+| `--add` | index | merge into the existing index instead of replacing it |
+
+## Supported inputs
+
+Most agents write *two* unrelated log shapes — what the CLI streams, and what it
+persists on disk — and they are not interchangeable. atif-make reads both.
+
+| Format | Source |
+|---|---|
+| `claude-code-transcript` | `~/.claude/projects/<project>/<session>.jsonl` |
+| `claude-code-stream` | `claude -p --output-format stream-json` |
+| `codex-rollout` | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |
+| `codex-exec` | `codex exec --json` |
+| `copilot-cli` | Copilot CLI session logs |
+| `har` | Anthropic Messages, OpenAI Chat Completions, OpenAI Responses |
+| `atif` | An ATIF trajectory that is already converted |
+
+Directories, `.zip` and `.tar.gz` (also `.tgz`, `.tar.bz2`, `.tar.xz`) are read
+as containers: every log inside is found and converted. That closes the loop on
+`--bundle` — the zip atif-make hands you to send someone opens again in atif-make,
+images and all.
+
+Archives are extracted to a temporary directory, once per run. Members naming
+absolute paths or climbing out with `..` are refused rather than quietly
+sanitised, and an archive that expands past 8 GB or 20,000 entries is rejected
+outright.
+
+Format is detected from content, never from the extension. `atif` exists so a
+trajectory someone sends you opens like anything else — it is loaded, not
+reparsed, and unknown fields from a newer ATIF minor version are dropped rather
+than rejected.
+
+## What it gets right
+
+These are the things that are easy to get wrong, and that silently corrupt a
+trajectory when you do:
+
+**Split messages.** Claude Code writes one API response as several JSONL lines
+that share a `message.id` — thinking, text, and each parallel `tool_use` arrive
+separately, with the *same* `usage` object repeated on every line. Treating those
+as separate turns inflates step counts and multiplies token totals. atif-make
+coalesces them and counts usage once.
+
+**Out-of-order tool results.** Parallel calls come back interleaved, and a slow
+call can return several turns after it was issued. Pairing results to calls by
+*position* drops some and misattributes others. atif-make pairs by `tool_use_id`.
+
+**Byte-capped detection.** A JSONL preamble (hook events, rate-limit notices) can
+push the identifying line kilobytes into a file. atif-make scans whole lines.
+
+**Subagent structure.** Claude Code links a delegated agent through a `.meta.json`
+sidecar (`toolUseId`) and an `agentId` field on the result line — not through
+anything in the result *text*. atif-make links by call id, so refs actually resolve
+instead of leaving orphaned subagents.
+
+**Images.** Codex embeds screenshots as base64 data URLs and Claude Code as
+base64 content blocks — 24 of the sessions on one test machine carried them, and
+a single Codex session held 65 images totalling 14 MB. Dropping them loses the
+thing the agent was actually looking at, and inlining them makes an unreadable
+document. atif-make writes them to `images/` and references them by relative path,
+which is what the spec asks for.
+
+**Malformed timestamps.** ATIF requires ISO 8601. A truncated or hand-edited log
+can carry something else, and passing it through would make the whole trajectory
+fail validation, so an unparseable timestamp is dropped rather than emitted.
+
+**HAR tool results.** In a HAR capture a tool's output is not in the response that
+called it — it appears in the *next* request's message history. atif-make harvests
+results across entries and pairs them back by id, while emitting the shared
+conversation prefix only once.
+
+## Output — a trajectory is a directory, not a file
+
+ATIF references images and split subagents by path *relative to the trajectory
+file*, so anything with attachments is inherently multi-file:
+
+```
+session.trajectory.json                 the document
+session.trajectory.<agent-id>.json      subagents, with --split-subagents
+images/<sha>.png                        images, referenced as "images/<sha>.png"
+```
+
+Images are de-duplicated by content hash, so the same screenshot pasted five
+times is stored once.
+
+Three ways out, depending on where it's going:
+
+```sh
+atif-make session.jsonl -o out/t.json      # directory form: t.json + images/
+atif-make session.jsonl --json             # one self-contained doc; images inlined as data: URIs
+atif-make session.jsonl --bundle send.zip  # zip of the whole directory — for sending someone
+```
+
+`--json` is the exception that proves the rule: stdout has no directory to put
+siblings in, so images become data URIs to keep the document standalone.
+
+Output carries `timestamp`, `reasoning_content`, per-step `metrics`, multimodal
+`ContentPart` message content, and subagents either embedded
+(`subagent_trajectories`) or split into sibling files with resolvable
+`trajectory_path` refs.
+
+## Viewing
+
+Conversion is all this package does. To browse trajectories in a browser,
+install the companion [`atif-view`](https://github.com/jammastergirish/atif-view), which depends on this
+package and reads the index below.
+
+## Where sessions come from
+
+`atif-make index` scans your own machine — nothing is uploaded, and no network call
+is ever made. By default it looks in:
+
+```
+~/.claude/projects/     Claude Code sessions
+~/.codex/sessions/      Codex sessions
+```
+
+The result is cached at `~/.atif-make/index.json`. Indexing reads only each file's
+leading lines, so a 143 MB rollout costs the same as a 4 KB one; full conversion
+happens lazily, when you actually open a session.
+
+Scan somewhere else, or add a single file someone sent you:
+
+```sh
+atif-make index ~/work/logs                    # replace the index with this scan
+atif-make index --add received.trajectory.json # merge one file into the existing index
+atif-make index --add received-bundle.zip      # or a whole bundle
+```
+
+`--add` merges; without it, `index` replaces. Both raw logs and already-converted
+ATIF trajectories can be added.
+
+## Tests
+
+```sh
+uv run pytest                      # unit tests, all synthetic fixtures
+uv sync --extra spec               # pulls harbor (large)
+uv run --extra spec pytest         # + validate against the reference ATIF models
+```
+
+The `spec` suite validates every fixture against harbor's own pydantic models —
+ground truth for whether the output is really ATIF, rather than what atif-make
+believes ATIF to be.

atif_make-0.1.0/README.md

@@ -0,0 +1,196 @@
+# atif-make
+
+Make [ATIF v1.7](https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md)
+trajectories from agent logs — Claude Code, Codex, Copilot CLI, and HAR captures.
+
+Zero runtime dependencies. Python 3.12+.
+
+## Install
+
+```sh
+uv tool install atif-make          # puts `atif-make` on your PATH
+```
+
+Or as a library in a project:
+
+```sh
+uv add atif-make
+```
+
+For a browser view of what you convert, see the companion
+[`atif-view`](https://github.com/jammastergirish/atif-view), which depends on this package.
+
+`uv tool install` builds an isolated environment, so nothing lands in your
+project or system Python. To follow local edits instead, use
+`uv tool install --editable .`; to remove it, `uv tool uninstall atif-make`.
+
+Running from a checkout without installing works too: `uv run atif-make ...`.
+
+```sh
+atif-make ~/.claude/projects/my-project/session.jsonl   # convert one log
+atif-make index --stats                                 # what do I have, across agents?
+```
+
+## Commands
+
+```
+atif-make <file>                 convert (shorthand for `atif-make convert`)
+atif-make convert <file>         convert one log
+atif-make convert <dir|archive>  convert every log inside
+atif-make index [roots...]       scan for sessions across agents
+atif-make formats                list supported input formats
+```
+
+| Flag | Command | Meaning |
+|---|---|---|
+| `-o, --output` | convert | output path (default `<input>.trajectory.json`) |
+| `-f, --format` | convert | force the input format instead of detecting it |
+| `--json` | convert | write one self-contained document to stdout |
+| `--bundle OUT.zip` | convert | zip the trajectory with its images and subagents |
+| `--split-subagents` | convert | write subagents as sibling files, not embedded |
+| `--indent N` | convert | JSON indent (default 2) |
+| `-q, --quiet` | convert | suppress progress output |
+| `--stats` | index | print a per-agent summary |
+| `--add` | index | merge into the existing index instead of replacing it |
+
+## Supported inputs
+
+Most agents write *two* unrelated log shapes — what the CLI streams, and what it
+persists on disk — and they are not interchangeable. atif-make reads both.
+
+| Format | Source |
+|---|---|
+| `claude-code-transcript` | `~/.claude/projects/<project>/<session>.jsonl` |
+| `claude-code-stream` | `claude -p --output-format stream-json` |
+| `codex-rollout` | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |
+| `codex-exec` | `codex exec --json` |
+| `copilot-cli` | Copilot CLI session logs |
+| `har` | Anthropic Messages, OpenAI Chat Completions, OpenAI Responses |
+| `atif` | An ATIF trajectory that is already converted |
+
+Directories, `.zip` and `.tar.gz` (also `.tgz`, `.tar.bz2`, `.tar.xz`) are read
+as containers: every log inside is found and converted. That closes the loop on
+`--bundle` — the zip atif-make hands you to send someone opens again in atif-make,
+images and all.
+
+Archives are extracted to a temporary directory, once per run. Members naming
+absolute paths or climbing out with `..` are refused rather than quietly
+sanitised, and an archive that expands past 8 GB or 20,000 entries is rejected
+outright.
+
+Format is detected from content, never from the extension. `atif` exists so a
+trajectory someone sends you opens like anything else — it is loaded, not
+reparsed, and unknown fields from a newer ATIF minor version are dropped rather
+than rejected.
+
+## What it gets right
+
+These are the things that are easy to get wrong, and that silently corrupt a
+trajectory when you do:
+
+**Split messages.** Claude Code writes one API response as several JSONL lines
+that share a `message.id` — thinking, text, and each parallel `tool_use` arrive
+separately, with the *same* `usage` object repeated on every line. Treating those
+as separate turns inflates step counts and multiplies token totals. atif-make
+coalesces them and counts usage once.
+
+**Out-of-order tool results.** Parallel calls come back interleaved, and a slow
+call can return several turns after it was issued. Pairing results to calls by
+*position* drops some and misattributes others. atif-make pairs by `tool_use_id`.
+
+**Byte-capped detection.** A JSONL preamble (hook events, rate-limit notices) can
+push the identifying line kilobytes into a file. atif-make scans whole lines.
+
+**Subagent structure.** Claude Code links a delegated agent through a `.meta.json`
+sidecar (`toolUseId`) and an `agentId` field on the result line — not through
+anything in the result *text*. atif-make links by call id, so refs actually resolve
+instead of leaving orphaned subagents.
+
+**Images.** Codex embeds screenshots as base64 data URLs and Claude Code as
+base64 content blocks — 24 of the sessions on one test machine carried them, and
+a single Codex session held 65 images totalling 14 MB. Dropping them loses the
+thing the agent was actually looking at, and inlining them makes an unreadable
+document. atif-make writes them to `images/` and references them by relative path,
+which is what the spec asks for.
+
+**Malformed timestamps.** ATIF requires ISO 8601. A truncated or hand-edited log
+can carry something else, and passing it through would make the whole trajectory
+fail validation, so an unparseable timestamp is dropped rather than emitted.
+
+**HAR tool results.** In a HAR capture a tool's output is not in the response that
+called it — it appears in the *next* request's message history. atif-make harvests
+results across entries and pairs them back by id, while emitting the shared
+conversation prefix only once.
+
+## Output — a trajectory is a directory, not a file
+
+ATIF references images and split subagents by path *relative to the trajectory
+file*, so anything with attachments is inherently multi-file:
+
+```
+session.trajectory.json                 the document
+session.trajectory.<agent-id>.json      subagents, with --split-subagents
+images/<sha>.png                        images, referenced as "images/<sha>.png"
+```
+
+Images are de-duplicated by content hash, so the same screenshot pasted five
+times is stored once.
+
+Three ways out, depending on where it's going:
+
+```sh
+atif-make session.jsonl -o out/t.json      # directory form: t.json + images/
+atif-make session.jsonl --json             # one self-contained doc; images inlined as data: URIs
+atif-make session.jsonl --bundle send.zip  # zip of the whole directory — for sending someone
+```
+
+`--json` is the exception that proves the rule: stdout has no directory to put
+siblings in, so images become data URIs to keep the document standalone.
+
+Output carries `timestamp`, `reasoning_content`, per-step `metrics`, multimodal
+`ContentPart` message content, and subagents either embedded
+(`subagent_trajectories`) or split into sibling files with resolvable
+`trajectory_path` refs.
+
+## Viewing
+
+Conversion is all this package does. To browse trajectories in a browser,
+install the companion [`atif-view`](https://github.com/jammastergirish/atif-view), which depends on this
+package and reads the index below.
+
+## Where sessions come from
+
+`atif-make index` scans your own machine — nothing is uploaded, and no network call
+is ever made. By default it looks in:
+
+```
+~/.claude/projects/     Claude Code sessions
+~/.codex/sessions/      Codex sessions
+```
+
+The result is cached at `~/.atif-make/index.json`. Indexing reads only each file's
+leading lines, so a 143 MB rollout costs the same as a 4 KB one; full conversion
+happens lazily, when you actually open a session.
+
+Scan somewhere else, or add a single file someone sent you:
+
+```sh
+atif-make index ~/work/logs                    # replace the index with this scan
+atif-make index --add received.trajectory.json # merge one file into the existing index
+atif-make index --add received-bundle.zip      # or a whole bundle
+```
+
+`--add` merges; without it, `index` replaces. Both raw logs and already-converted
+ATIF trajectories can be added.
+
+## Tests
+
+```sh
+uv run pytest                      # unit tests, all synthetic fixtures
+uv sync --extra spec               # pulls harbor (large)
+uv run --extra spec pytest         # + validate against the reference ATIF models
+```
+
+The `spec` suite validates every fixture against harbor's own pydantic models —
+ground truth for whether the output is really ATIF, rather than what atif-make
+believes ATIF to be.

atif_make-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "atif-make"
+version = "0.1.0"
+description = "Convert agent logs (Claude Code, Codex, Copilot, HAR) into ATIF v1.7 trajectories."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+# Deliberately zero runtime dependencies: this runs against local session logs
+# and should stay trivially installable anywhere.
+dependencies = []
+
+[project.scripts]
+atif-make = "atif_make.cli:main"
+
+[project.optional-dependencies]
+# `harbor` carries the reference ATIF pydantic models. It pulls a large tree
+# (litellm, fastapi, supabase), so it is kept out of the default test path and
+# used only by the spec-compliance suite.
+spec = ["harbor>=0.21.0"]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/atif_make"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

atif_make-0.1.0/src/atif_make/__init__.py

@@ -0,0 +1,15 @@
+"""atif-make — convert agent logs into ATIF v1.7 trajectories."""
+
+from .atif import SCHEMA_VERSION, Trajectory
+from .convert import AGENTS, PARSERS, convert
+from .detect import FORMATS, detect_format
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "Trajectory",
+    "convert",
+    "detect_format",
+    "FORMATS",
+    "PARSERS",
+    "AGENTS",
+]

atif_make-0.1.0/src/atif_make/archive.py

@@ -0,0 +1,109 @@
+"""Reading logs out of archives and directories.
+
+mkatif produces zip bundles, so it has to be able to open them again — and a
+colleague is as likely to send a `.tar.gz` of a session directory as a bare
+file. Archives are extracted to a temporary directory once per process and
+reused, since a viewer may open several trajectories from the same bundle.
+
+Extraction is the dangerous part of this file. Archive members can name absolute
+paths or climb out with `..` (the "zip slip" / CVE-2007-4559 family), and a
+small archive can expand to fill a disk. Both are refused rather than sanitised
+quietly, so a malformed bundle fails loudly instead of writing somewhere odd.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path
+
+# A session log can legitimately be very large — a 143 MB rollout is real — so
+# the ceiling is high enough for a genuine bundle and low enough to stop a bomb.
+MAX_TOTAL_BYTES = 8 * 1024 * 1024 * 1024
+MAX_MEMBERS = 20_000
+
+TAR_SUFFIXES = (".tar", ".tar.gz", ".tgz", ".tar.bz2", ".tbz2", ".tar.xz", ".txz")
+
+_cache: dict[Path, Path] = {}
+_temp_dirs: list[tempfile.TemporaryDirectory] = []
+
+
+def is_archive(path: Path) -> bool:
+    name = path.name.lower()
+    if name.endswith(".zip"):
+        return zipfile.is_zipfile(path)
+    if any(name.endswith(s) for s in TAR_SUFFIXES):
+        return tarfile.is_tarfile(path)
+    # Fall back to content sniffing for archives with an unhelpful name.
+    try:
+        if zipfile.is_zipfile(path):
+            return True
+        return tarfile.is_tarfile(path)
+    except (OSError, tarfile.TarError):
+        return False
+
+
+def _safe_target(root: Path, member: str) -> Path:
+    """Resolve an archive member under root, refusing anything that escapes."""
+    if member.startswith("/") or ".." in Path(member).parts:
+        raise ValueError(f"unsafe path in archive: {member}")
+    target = (root / member).resolve()
+    if not str(target).startswith(str(root.resolve())):
+        raise ValueError(f"archive member escapes destination: {member}")
+    return target
+
+
+def extract(path: Path) -> Path:
+    """Extract an archive to a temporary directory and return its root."""
+    resolved = path.resolve()
+    cached = _cache.get(resolved)
+    if cached is not None and cached.exists():
+        return cached
+
+    holder = tempfile.TemporaryDirectory(prefix="mkatif-")
+    _temp_dirs.append(holder)  # keep alive for the life of the process
+    root = Path(holder.name)
+
+    if zipfile.is_zipfile(path):
+        with zipfile.ZipFile(path) as archive:
+            members = archive.infolist()
+            if len(members) > MAX_MEMBERS:
+                raise ValueError(f"archive has too many entries ({len(members)})")
+            total = sum(m.file_size for m in members)
+            if total > MAX_TOTAL_BYTES:
+                raise ValueError(f"archive expands to {total} bytes, refusing")
+            for member in members:
+                if member.is_dir():
+                    continue
+                target = _safe_target(root, member.filename)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with archive.open(member) as src, target.open("wb") as dst:
+                    shutil.copyfileobj(src, dst)
+    else:
+        with tarfile.open(path) as archive:
+            members = archive.getmembers()
+            if len(members) > MAX_MEMBERS:
+                raise ValueError(f"archive has too many entries ({len(members)})")
+            total = sum(m.size for m in members if m.isreg())
+            if total > MAX_TOTAL_BYTES:
+                raise ValueError(f"archive expands to {total} bytes, refusing")
+            for member in members:
+                if not (member.isreg() or member.isdir()):
+                    # Skip links and devices outright; nothing here needs them.
+                    continue
+                _safe_target(root, member.name)
+            # `filter="data"` is Python's own hardening for the same class of bug.
+            archive.extractall(root, filter="data")
+
+    _cache[resolved] = root
+    return root
+
+
+def cleanup() -> None:
+    """Drop every extracted directory. Mainly for tests."""
+    for holder in _temp_dirs:
+        holder.cleanup()
+    _temp_dirs.clear()
+    _cache.clear()