agent-chronicle 0.1.0__tar.gz

agent_chronicle-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,36 @@
+name: Bug report
+description: Something in Chronicle behaves incorrectly (recording, replay, cut-point, judge, CLI).
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: Minimal steps or a code snippet. If it involves a fixture, attach or paste the relevant envelope.
+      placeholder: |
+        1. Record with `@boundary(...)`
+        2. Replay with `ReplayPlan().stub(...).live(...)`
+        3. ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Chronicle version
+      description: Output of `pip show agent-chronicle` (or the commit SHA).
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.11"
+    validations:
+      required: true

agent_chronicle-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & ideas
+    url: https://github.com/theagentplane/chronicle/discussions
+    about: For open-ended questions or design discussions, start a Discussion. Please open an issue or Discussion before large changes so we can align.
+  - name: Security vulnerability
+    url: https://github.com/theagentplane/chronicle/blob/main/SECURITY.md
+    about: Do not file public issues for security problems — follow SECURITY.md instead.

agent_chronicle-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Propose a new capability or improvement (framework support, replay ergonomics, judges, etc.).
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that Chronicle makes hard or impossible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should Chronicle do? API sketches welcome.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches or workarounds you've tried.
+    validations:
+      required: false

agent_chronicle-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+<!-- Keep PRs small and focused on one thing (see CONTRIBUTING.md). -->
+
+## Summary
+
+<!-- What does this change and why? -->
+
+## Related issue
+
+<!-- e.g. Closes #123 -->
+
+## Checklist
+
+- [ ] Tests added or updated, and `pytest -v` passes locally
+- [ ] `ruff check .` is clean
+- [ ] Docs / CHANGELOG updated if user-facing
+- [ ] If the Envelope schema changed: bumped at least a minor version and included a fixture migration path (see RELEASING.md)
+- [ ] Commits are signed off for the [DCO](https://developercertificate.org/) (`git commit -s`)

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

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref to save runner minutes.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install "ruff>=0.6"
+      - name: Lint
+        run: ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (editable, with dev extras)
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        # Layer 2 uses a mock judge, so the full suite runs without any API key.
+        run: pytest -v

agent_chronicle-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+# Publishing a GitHub Release triggers a build and upload to PyPI.
+# See RELEASING.md for the one-time PyPI Trusted Publisher setup.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          pip install "build>=1.2"
+          python -m build
+      - name: Check metadata
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing (OIDC) — no API tokens stored. Matches the `pypi`
+    # environment and `release.yml` workflow name configured on PyPI.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_chronicle-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.chronicle/runs/
+*.sqlite
+.DS_Store
+**/.DS_Store

agent_chronicle-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-22
+
+### Added
+- `@boundary` decorator: record in live mode, stub in replay mode, run live at a
+  cut-point. One annotation, three behaviors.
+- Immutable, append-only Envelope capturing contextual metadata, input state,
+  action/result, and graph linkage.
+- Real model-version and sampling-parameter capture on the `@boundary` path, plus
+  an `extract_metadata` hook for explicit overrides.
+- `EnvelopeStore` (JSONL) and a side execution graph builder.
+- Verification Test Bench: Layer 1 structural replay (never calls the LLM) and
+  Layer 2 LLM-as-judge evaluation.
+- Cut-point replay via `ReplayPlan` (stub upstream, run target live, observe
+  downstream).
+- Secret redaction: opt-in `session.redactors` / `default_redactors()` that mask
+  API keys, tokens, and JWTs before an envelope is stored or committed.
+- Trace visualizer (`chronicle show-graph --ui / --html`).
+- CLI: `record`, `extract`, `replay`, `verify`, `show-graph`, `schema`,
+  `list-fixtures`.
+- OpenInference / Arize Phoenix normalization and optional LangGraph node
+  wrapping.
+
+[Unreleased]: https://github.com/theagentplane/chronicle/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/theagentplane/chronicle/releases/tag/v0.1.0

agent_chronicle-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,72 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**[INSERT CONTACT EMAIL]**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

agent_chronicle-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to Chronicle
+
+Thanks for your interest in contributing! Chronicle is record-and-replay for
+agent decision graphs, and contributions of all sizes are welcome.
+
+## Getting started
+
+```bash
+git clone https://github.com/theagentplane/chronicle.git
+cd chronicle
+pip install -e ".[dev]"
+
+python scripts/run.py demo     # interactive walkthrough
+pytest -v                      # full test suite
+pytest -m layer1 -v            # deterministic replay only
+```
+
+## Ground rules
+
+- Keep pull requests small and focused on one thing.
+- Every change needs tests, and CI (lint + tests) must be green before merge.
+- Match the existing code style; run `ruff check .` before pushing.
+- Open an issue or a GitHub Discussion before large changes so we can align.
+
+## Developer Certificate of Origin (DCO)
+
+This project uses the [DCO](https://developercertificate.org/) instead of a CLA.
+It's a lightweight, one-line attestation that you have the right to submit your
+contribution under the project's MIT license. Sign off every commit:
+
+```bash
+git commit -s -m "Your message"
+```
+
+That appends a line like `Signed-off-by: Your Name <you@example.com>` to the
+commit. We recommend enabling the DCO GitHub App on the repo so it's enforced
+automatically on every PR.
+
+## Reviewer checklist (record-and-replay specifics)
+
+Because this is a replay tool, reviewers pay special attention to:
+
+- **Layer 1 replay must never touch the network or call the LLM.** A stray live
+  call in "deterministic" replay silently invalidates every regression test.
+- **Envelopes are immutable and append-only.** Don't introduce code that mutates
+  a stored envelope in place.
+- **No un-redacted production data in fixtures.** See `SECURITY.md` — captured
+  prompts and retrieved chunks are sensitive. Scrub before committing.
+- **Graph linkage stays correct** across retries and parallel invocations
+  (`parent_envelope_id`, `sequence`, `invocation_index`).
+- **Cut-point tests** genuinely stub upstream from the fixture and only run the
+  target boundary live.
+- **Envelope schema changes** ship with a version bump and a fixture migration
+  path so previously committed regressions still load.
+
+## Reporting bugs and requesting features
+
+- Bugs: open a GitHub Issue with a minimal reproduction.
+- Ideas and questions: use GitHub Discussions.
+- Security issues: do **not** open a public issue — see `SECURITY.md`.

agent_chronicle-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tisha Chawla and Susheem Koul
+
+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.