agentdelta 0.1.0__tar.gz

agentdelta-0.1.0/.aider.conf.yml

@@ -0,0 +1,24 @@
+# aider configuration for agentdelta
+# https://aider.chat/docs/config/aider_conf.html
+
+# Always include these files for architectural context
+read:
+  - ARCHITECTURE.md
+  - CLAUDE.md
+  - src/agentdelta/trace.py
+  - src/agentdelta/diff.py
+
+# Auto-lint after edits
+lint: true
+lint-cmd: "ruff check {files} && ruff format --check {files}"
+
+# Auto-test after edits
+auto-test: false
+test-cmd: "pytest tests/ -x -q"
+
+# Model guidance
+model: claude-sonnet-4-5
+
+# Conventions
+attribute-author: false
+attribute-co-author: true

agentdelta-0.1.0/.claude/commands/add-adapter.md

@@ -0,0 +1,32 @@
+Scaffold a new instrumentation adapter for a framework not yet supported by agentdelta.
+
+Usage: /project:add-adapter <framework_name>
+
+Framework name from $ARGUMENTS (e.g. "autogen", "crewai", "smolagents", "pydantic-ai").
+
+Generate the following:
+
+1. `src/agentdelta/instrument_<framework>.py` — adapter module:
+   - A class `<Framework>AgentdeltaAdapter` that wraps the framework's event/callback API
+   - Must emit `TraceNode` objects to an `AgentTrace` for each: agent start, LLM call, tool call, tool return, agent end
+   - Use `NodeType.START`, `NodeType.LLM`, `NodeType.TOOL_CALL`, `NodeType.TOOL_RETURN`, `NodeType.END`
+   - Include a `record_<framework>()` context manager mirroring the LangChain `record()` API
+
+2. Export from `src/agentdelta/__init__.py`:
+   - Add to `__all__` alphabetically
+
+3. `tests/test_instrument_<framework>.py` — at least 3 tests:
+   - Callback captures LLM output as a NodeType.LLM node
+   - Callback captures tool calls as NodeType.TOOL_CALL nodes
+   - record() context manager saves a valid JSONL file on exit
+
+4. Update `README.md` Quick Start section with a snippet for the new framework
+
+5. Update `pyproject.toml` optional dependencies:
+   - Add `[<framework>]` extra with the framework package pinned to `>=` minimum supported version
+
+Context:
+- See `src/agentdelta/instrument.py` for the LangChain reference implementation
+- AgentTrace.add_node() and add_edge() are the only write methods needed
+- Keep content fields under 2000 chars for LLM nodes, 500 chars for tool nodes
+- The adapter does NOT need to import agentdelta internals other than trace.py

agentdelta-0.1.0/.claude/commands/diff.md

@@ -0,0 +1,21 @@
+Diff two agentdelta trace files and report any behavioral regression.
+
+Usage: /project:diff <baseline.jsonl> <candidate.jsonl> [--format rich|json|markdown] [--exit-code]
+
+Steps:
+1. Run: `agentdelta diff $ARGUMENTS`
+2. Parse the output:
+   - "REGRESSION DETECTED" → a ForkPoint was found; show the fork step, tool change, and similarity score
+   - "No regression" → traces are equivalent; show match percentage
+3. If a fork is detected, explain in plain English what changed:
+   - Tool change (e.g. get_weather → web_search): mention latency/reliability implications
+   - Reasoning divergence: mention that the LLM reasoning path changed even if the final answer is the same
+   - Step count difference: mention added/removed tool calls
+4. Suggest a remediation if asked: tighten the system prompt, pin the model version, or add a unit test fixture for this trace pair.
+
+Context:
+- Traces are JSONL files — one JSON object per line (trace_meta, node, edge records)
+- Fork threshold default: 0.70 cosine similarity
+- Match threshold default: 0.85 cosine similarity
+- The embedding model is all-MiniLM-L6-v2, runs locally, no API key needed
+- `has_regression` is True iff fork_point is not None

agentdelta-0.1.0/.claude/commands/inspect.md

@@ -0,0 +1,22 @@
+Inspect an agentdelta trace file and summarize the agent's execution path.
+
+Usage: /project:inspect <trace.jsonl>
+
+Steps:
+1. Run: `agentdelta inspect $ARGUMENTS`
+2. Present a clean summary:
+   - Total steps and run_id
+   - Sequence of node types (start → llm → tool_call → tool_return → ... → end)
+   - Each tool call: name and truncated arguments
+   - Each LLM step: first 100 chars of reasoning
+   - Any metadata fields present
+3. Highlight anything unusual:
+   - More than 10 steps (complex agent run)
+   - Repeated tool calls (possible loop)
+   - Missing start or end node
+   - Very short LLM reasoning (< 20 chars — may be truncated or empty)
+
+Context:
+- Trace format: each line is JSON with "type": "node"|"edge"|"trace_meta"
+- Node types: start, llm, tool_call, tool_return, end
+- Node IDs are content-addressed (SHA-256[:16]) — same content = same ID across runs

agentdelta-0.1.0/.claude/commands/record.md

@@ -0,0 +1,41 @@
+Generate boilerplate code to record an agent run with agentdelta.
+
+Usage: /project:record [framework] [agent_variable_name]
+
+Arguments: $ARGUMENTS (optional: framework name like "langchain", "langgraph", "custom")
+
+Generate a self-contained Python snippet that:
+
+For LangChain/LangGraph (default):
+```python
+from agentdelta import record
+
+# Baseline (before your change)
+with record("baseline.jsonl", run_id="v1.0") as cb:
+    agent.invoke({"input": "..."}, config={"callbacks": [cb]})
+
+# Candidate (after your change)
+with record("candidate.jsonl", run_id="v1.1") as cb:
+    agent.invoke({"input": "..."}, config={"callbacks": [cb]})
+```
+
+For custom/framework-agnostic:
+```python
+from agentdelta import AgentTrace
+from agentdelta.trace import TraceNode, TraceEdge, NodeType, EdgeType
+
+trace = AgentTrace(run_id="my_run")
+trace.add_node(TraceNode(step=1, node_type=NodeType.START, content="user input here"))
+trace.add_node(TraceNode(step=2, node_type=NodeType.LLM, content="reasoning text here"))
+trace.add_node(TraceNode(step=3, node_type=NodeType.TOOL_CALL, content="tool_name(args)"))
+trace.add_node(TraceNode(step=4, node_type=NodeType.TOOL_RETURN, content="tool result"))
+trace.add_node(TraceNode(step=5, node_type=NodeType.END, content="final output"))
+trace.save("my_run.jsonl")
+```
+
+Then show the diff command: `agentdelta diff baseline.jsonl candidate.jsonl`
+
+Context:
+- AgentdeltaCallback is LangChain BaseCallbackHandler-compatible (no import of BaseCallbackHandler needed)
+- record() saves the trace on context exit, even if the agent raises an exception
+- run_id appears in the diff report header — use something meaningful (version, git hash, etc.)

agentdelta-0.1.0/.coderabbit.yaml

@@ -0,0 +1,32 @@
+language: en
+early_access: false
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: false
+  auto_review:
+    enabled: true
+    drafts: false
+  path_filters:
+    - "!assets/**"
+    - "!*.md"
+  path_instructions:
+    - path: "src/agentdelta/diff.py"
+      instructions: |
+        This is the core fork-detection algorithm. Be strict about:
+        - Threshold defaults must not change without a migration note
+        - New status values must be added to the literal type in StepDiff
+        - Fork detection must remain O(n) per alignment pair
+    - path: "src/agentdelta/embed.py"
+      instructions: |
+        Thread safety: _get_model() uses double-checked locking. Any change
+        to the singleton pattern must preserve thread safety.
+    - path: "tests/**"
+      instructions: |
+        Ensure new tests use fixtures from conftest.py rather than
+        building traces inline. CLI tests must use click.testing.CliRunner.
+chat:
+  auto_reply: true

agentdelta-0.1.0/.continue/config.json

@@ -0,0 +1,44 @@
+{
+  "name": "agentdelta",
+  "version": "0.1.0",
+  "schema": "v1",
+  "context": [
+    {
+      "provider": "file",
+      "params": {
+        "nRetrieve": 20,
+        "nFinal": 5
+      }
+    },
+    {
+      "provider": "code"
+    }
+  ],
+  "docs": [
+    {
+      "title": "agentdelta Architecture",
+      "startUrl": "file://./ARCHITECTURE.md",
+      "faviconUrl": ""
+    }
+  ],
+  "customCommands": [
+    {
+      "name": "diff",
+      "prompt": "Run agentdelta diff on the two trace files I specify. Explain the fork point in plain English, whether it represents a behavioral regression, and what likely caused it (prompt change, model upgrade, tool order change). Files: {input}",
+      "description": "Diff two agentdelta trace files and explain any fork"
+    },
+    {
+      "name": "add-adapter",
+      "prompt": "Scaffold a new agentdelta instrumentation adapter for the framework: {input}. Follow the pattern in src/agentdelta/instrument.py. Create the adapter file, export it from __init__.py, and write at least 3 tests.",
+      "description": "Scaffold a new framework instrumentation adapter"
+    }
+  ],
+  "rules": [
+    "This is agentdelta — a semantic diff engine for AI agent traces.",
+    "All embeddings must go through _get_model() in embed.py. Never import SentenceTransformer directly.",
+    "TraceNode.id is content-addressed (SHA-256). Never assign it manually.",
+    "Library code must not use print() — use rich.console.Console.",
+    "All public API must have type annotations and docstrings.",
+    "fork_threshold=0.70 and match_threshold=0.85 are the algorithmic defaults — don't change without tests."
+  ]
+}

agentdelta-0.1.0/.cursor/rules/redline.mdc

@@ -0,0 +1,43 @@
+---
+description: redline coding rules and architecture context
+globs: ["src/**/*.py", "tests/**/*.py"]
+alwaysApply: true
+---
+
+# redline — Cursor Rules
+
+## What this project does
+Semantic diff engine for AI agent behavior. Records agent traces as JSONL, embeds steps with `all-MiniLM-L6-v2`, aligns two traces by cosine similarity, detects the first semantic fork point.
+
+## Module map
+- `trace.py` — data model (TraceNode, TraceEdge, AgentTrace, NodeType, EdgeType)
+- `embed.py` — thread-safe sentence-transformer singleton + sliding-window alignment
+- `diff.py` — diff_traces() → DiffResult, ForkPoint, StepDiff
+- `instrument.py` — LangChain callback + record() context manager
+- `report.py` — Rich/JSON/Markdown formatters
+- `cli.py` — Click CLI (diff, inspect commands)
+
+## Invariants — never break these
+- TraceNode.id is SHA-256[:16] of "{node_type}:{content}" — must stay content-addressed
+- embed_trace() is idempotent — safe to call twice on the same trace
+- fork_threshold=0.70 and match_threshold=0.85 are the defaults; don't change without tests
+- has_regression is True iff fork_point is not None — no other state
+- All embeddings come from the thread-safe _get_model() singleton in embed.py
+
+## Code style
+- Python 3.10+, fully type-annotated, mypy strict mode
+- Ruff lint rules: E W F I UP B S N SIM RUF PT
+- No print() in library code — use rich.console.Console
+- All public functions and classes must have Google-style docstrings
+- Tests: pytest, CliRunner for CLI tests, no mocking of embed model (use short test traces)
+
+## When adding a new output format
+1. Add `to_<format>(result: DiffResult) -> str` in report.py
+2. Add format name to --format Choice in cli.py
+3. Add at least 2 tests in tests/test_report.py
+
+## When adding a new instrumentation adapter
+1. Create src/redline/instrument_<framework>.py
+2. Implement a context manager mirroring record() in instrument.py
+3. Export from __init__.py, add to __all__ alphabetically
+4. Add tests in tests/test_instrument_<framework>.py

agentdelta-0.1.0/.editorconfig

@@ -0,0 +1,24 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.yml]
+indent_size = 2
+
+[*.yaml]
+indent_size = 2
+
+[*.toml]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

agentdelta-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# Global owner — reviews all PRs by default
+* @sandeep-alluru
+
+# Core algorithm — extra scrutiny
+src/agentdelta/diff.py @sandeep-alluru
+src/agentdelta/embed.py @sandeep-alluru

agentdelta-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: sandeep-alluru

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

@@ -0,0 +1,56 @@
+name: Bug Report
+description: Something is broken
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill in as much detail as you can.
+
+  - type: input
+    id: version
+    attributes:
+      label: agentdelta version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.11.5"
+    validations:
+      required: true
+
+  - type: textarea
+    id: command
+    attributes:
+      label: Command run
+      description: The exact command or Python code that triggered the bug
+      render: bash
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include the full error message and traceback if applicable
+      render: text
+    validations:
+      required: true
+
+  - type: textarea
+    id: trace_format
+    attributes:
+      label: Trace file snippet (optional)
+      description: A minimal .jsonl trace that reproduces the issue (redact any sensitive content)
+      render: json

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

@@ -0,0 +1,36 @@
+name: Feature Request
+description: Propose a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this solve? Who experiences it?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you've thought about
+
+  - type: dropdown
+    id: contribution
+    attributes:
+      label: Are you willing to implement this?
+      options:
+        - "Yes — I'll open a PR"
+        - "Maybe — if someone helps"
+        - "No — just requesting"
+    validations:
+      required: true

agentdelta-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## What changed
+
+<!-- One paragraph summary of what this PR does -->
+
+## Why
+
+<!-- Motivation: bug it fixes, feature it adds, or issue it closes -->
+Closes #
+
+## Type of change
+
+- [ ] `fix:` Bug fix
+- [ ] `feat:` New feature
+- [ ] `refactor:` Refactor (no behavior change)
+- [ ] `docs:` Documentation only
+- [ ] `test:` Tests only
+- [ ] `chore:` Dependency bump, CI config, etc.
+- [ ] `perf:` Performance improvement
+
+## Testing done
+
+<!-- How did you verify this works? Which test files cover it? -->
+
+- [ ] `make test` passes locally
+- [ ] `make lint` passes locally
+- [ ] `make typecheck` passes locally
+- [ ] New tests added for changed behavior
+
+## Checklist
+
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] Public API changes have docstrings
+- [ ] No secrets, API keys, or trace data committed
+- [ ] README updated if CLI flags or behavior changed

agentdelta-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,47 @@
+# GitHub Copilot Instructions — agentdelta
+
+agentdelta is a semantic diff engine for AI agent behavior. It records agent execution traces as JSONL, embeds each step with `all-MiniLM-L6-v2`, and detects the first semantic fork point between two runs.
+
+## Architecture
+
+| Module | Purpose |
+|---|---|
+| `trace.py` | Data model: `NodeType`, `EdgeType`, `TraceNode`, `TraceEdge`, `AgentTrace` |
+| `embed.py` | Sentence-transformer singleton + `align_traces()` sliding-window alignment |
+| `diff.py` | `diff_traces()` → `DiffResult`, `ForkPoint`, `StepDiff` |
+| `instrument.py` | `AgentdeltaCallback` (LangChain) + `record()` context manager |
+| `report.py` | `print_diff()`, `to_json()`, `to_markdown()` formatters |
+| `cli.py` | Click CLI: `agentdelta diff` and `agentdelta inspect` |
+
+## Key invariants
+
+- `TraceNode.id` is SHA-256[:16] of `"{node_type}:{content}"` — content-addressed, deterministic
+- `embed_trace()` mutates nodes in-place; idempotent
+- `fork_threshold=0.70` — cosine similarity below this → ForkPoint
+- `match_threshold=0.85` — cosine similarity above this → "match" (no change)
+- `has_regression` is `True` iff `fork_point is not None`
+- Node content is truncated: LLM ≤2000 chars, tool ≤500 chars
+
+## Code style
+
+- Python 3.10+, type-annotated, mypy strict
+- Ruff rules: E, W, F, I, UP, B, S, N, SIM, RUF, PT; ignore S101 (assert in tests), N806
+- No `print()` in library code — use `rich.console.Console`
+- All public classes and functions must have docstrings
+- Tests use `pytest`; CLI tests use `click.testing.CliRunner`
+
+## Trace JSONL format
+
+```jsonl
+{"type": "trace_meta", "run_id": "v1.0"}
+{"type": "node", "id": "...", "step": 1, "node_type": "start", "content": "...", "metadata": {}}
+{"type": "edge", "source_step": 1, "target_step": 2, "edge_type": "sequence", "label": ""}
+```
+
+## Adding a new output format
+
+Add `to_<format>(result: DiffResult) -> str` to `report.py`, add to `--format` choices in `cli.py`, add tests.
+
+## Adding a new instrumentation adapter
+
+Create `src/agentdelta/instrument_<framework>.py`. See `instrument.py` (LangChain) as reference. Export from `__init__.py`. Add tests.

agentdelta-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - ci

agentdelta-0.1.0/.github/labels.yml

@@ -0,0 +1,98 @@
+# Bug reports
+- name: bug
+  color: "d73a4a"
+  description: "Something isn't working"
+
+- name: fix
+  color: "d73a4a"
+  description: "A bug fix"
+
+# Features
+- name: enhancement
+  color: "a2eeef"
+  description: "New feature or request"
+
+- name: feature
+  color: "a2eeef"
+  description: "New feature"
+
+- name: feat
+  color: "a2eeef"
+  description: "New feature (conventional commit)"
+
+# Documentation
+- name: documentation
+  color: "0075ca"
+  description: "Improvements or additions to documentation"
+
+- name: docs
+  color: "0075ca"
+  description: "Documentation update"
+
+# Maintenance
+- name: chore
+  color: "e4e669"
+  description: "Build process, dependencies, or tooling"
+
+- name: dependencies
+  color: "0366d6"
+  description: "Pull requests that update a dependency"
+
+- name: ci
+  color: "e4e669"
+  description: "CI/CD changes"
+
+- name: refactor
+  color: "fef2c0"
+  description: "Code refactoring without behavior change"
+
+# Tests
+- name: test
+  color: "bfd4f2"
+  description: "Adding missing tests or correcting existing tests"
+
+# Version bumps
+- name: major
+  color: "ee0701"
+  description: "Breaking change — bumps major version"
+
+- name: minor
+  color: "fbca04"
+  description: "Non-breaking new feature — bumps minor version"
+
+- name: patch
+  color: "0075ca"
+  description: "Backwards compatible bug fix — bumps patch version"
+
+# Meta
+- name: good first issue
+  color: "7057ff"
+  description: "Good for newcomers"
+
+- name: help wanted
+  color: "008672"
+  description: "Extra attention is needed"
+
+- name: security
+  color: "ee0701"
+  description: "Security vulnerability"
+
+- name: pinned
+  color: "e11d48"
+  description: "Pinned issue — do not close"
+
+- name: duplicate
+  color: "cfd3d7"
+  description: "This issue or pull request already exists"
+
+- name: invalid
+  color: "e4e4e7"
+  description: "This doesn't seem right"
+
+- name: wontfix
+  color: "e4e4e7"
+  description: "This will not be worked on"
+
+- name: question
+  color: "d876e3"
+  description: "Further information is requested"

agentdelta-0.1.0/.github/release-drafter.yml

@@ -0,0 +1,58 @@
+name-template: "v$RESOLVED_VERSION"
+tag-template: "v$RESOLVED_VERSION"
+categories:
+  - title: "🚀 New Features"
+    labels:
+      - "feature"
+      - "enhancement"
+      - "feat"
+  - title: "🐛 Bug Fixes"
+    labels:
+      - "fix"
+      - "bugfix"
+      - "bug"
+  - title: "🧰 Maintenance"
+    labels:
+      - "chore"
+      - "dependencies"
+      - "ci"
+      - "refactor"
+  - title: "📖 Documentation"
+    labels:
+      - "documentation"
+      - "docs"
+  - title: "🧪 Tests"
+    labels:
+      - "test"
+      - "tests"
+change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
+change-prefix: ""
+no-changes-template: "No changes."
+version-resolver:
+  major:
+    labels:
+      - "major"
+      - "breaking"
+  minor:
+    labels:
+      - "minor"
+      - "feature"
+      - "enhancement"
+      - "feat"
+  patch:
+    labels:
+      - "patch"
+      - "fix"
+      - "bugfix"
+      - "documentation"
+      - "chore"
+      - "dependencies"
+      - "ci"
+      - "refactor"
+  default: patch
+template: |
+  ## What's Changed
+
+  $CHANGES
+
+  **Full Changelog**: https://github.com/sandeep-alluru/agentdelta/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION