Skip to content

chore(claude): add initial Claude.md #3252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
galkleinman merged 3 commits into from
Aug 13, 2025
Merged

chore(claude): add initial Claude.md #3252

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cce2b3e
chore(claude): add initial Claude.md
galkleinman Aug 13, 2025
3dccef5
fix pr comments
galkleinman Aug 13, 2025
d7a42cf
Merge branch 'main' into gk/claude-md
galkleinman Aug 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# OpenLLMetry Repository Guide

## Repository Structure
This repository contains multiple PyPI-publishable packages organized and orchestrated using Nx workspace management.

### Nx Workspace Commands
```bash
# Run tests across all packages
nx run-many -t test

# Run linting across all packages
nx run-many -t lint

# Update lock files across all packages
nx run-many -t lock

# Run specific targets on specific packages
nx run <package-name>:test
nx run <package-name>:lint

# Show project graph
nx graph

# Show what's affected by changes
nx affected:test
nx affected:lint
```

## Package Management
All packages use Poetry as the package manager. Always execute commands through Poetry:
```bash
poetry run <command>
```

Comment thread
galkleinman marked this conversation as resolved.
## Testing with VCR Cassettes
Tests utilize VCR cassettes for API calls.

### Commands
```bash
# Run tests normally (uses existing cassettes)
poetry run pytest tests/

# Re-record all cassettes (requires API keys)
poetry run pytest tests/ --record-mode=all

# Record only new test episodes
poetry run pytest tests/ --record-mode=new_episodes

# Record cassettes once (if they don't exist)
poetry run pytest tests/ --record-mode=once

# Run tests without recording (fails if cassettes missing)
poetry run pytest tests/ --record-mode=none

Comment on lines +43 to +54
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Aug 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Ensure pytest supports --record-mode flags (pytest-recording/pytest-vcr).
These flags are provided by plugins; verify the repo includes one of them so commands work.

Run this script to check for relevant plugins/deps and pytest config:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Searching for pytest VCR plugins and config..."
rg -n "pytest-recording|pytest-vcr|vcrpy" -S || true

echo "Looking for pytest configuration files..."
fd -t f -a "pyproject.toml|pytest.ini|tox.ini|setup.cfg" | while read -r f; do
  echo "== $f =="
  rg -n "record-mode|addopts|pytest_plugins|vcr" "$f" || true
done

echo "Listing pyproject poetry dependencies mentioning pytest/vcr..."
fd pyproject.toml | xargs -I{} sh -c 'echo "-> {}"; rg -n "pytest|vcr|recording" "{}" || true'

Length of output: 311274

Ensure the root project installs and enables a pytest recording plugin

It looks like only individual packages list pytest‐recording and vcrpy, but your top-level README commands run pytest … --record-mode=… from the repo root. You’ll need to add and configure one of these plugins in your root environment so those flags are recognized:

• In your root pyproject.toml (under [tool.poetry.dev-dependencies]), add:
‑ pytest-recording = "^0.13.1"
‑ vcrpy = "^7.0.0"

• Run:
poetry add --dev pytest-recording vcrpy

• Create or update pytest.ini (at the repo root) with:

[pytest]
addopts = --record-mode=all
pytest_plugins =
    pytest_recording

• Commit those changes and confirm:
poetry run pytest tests/ --record-mode=all now picks up the plugin.

🤖 Prompt for AI Agents 
In CLAUDE.md around lines 43 to 54, the README commands assume pytest recording
flags are available at the repo root but the root environment lacks
pytest-recording/vcrpy; add dev dependencies for pytest-recording and vcrpy to
the root pyproject.toml (under [tool.poetry.dev-dependencies]) or run poetry add
--dev pytest-recording vcrpy, create/update a pytest.ini at the repo root to
enable the plugin (addopts and pytest_plugins including pytest_recording), and
commit those changes so running the documented poetry run pytest tests/
--record-mode=all from the repo root recognizes the flags.

# Run specific test files
poetry run pytest tests/test_agents.py --record-mode=once
```

### Guidance
Re-record cassettes when API interactions change to ensure test accuracy.
Never commit secrets or PII. Scrub them using VCR filters (e.g., filter_headers, before_record) or your test framework's equivalent.
Store API keys only in environment variables/secure vaults; never in code or cassettes.
Typical record modes you may use: once, new_episodes, all, none (choose per test needs).
Creating new cassettes requires valid API keys (OpenAI, Anthropic, etc.); ask the user to provide them if needed.

## Semantic Conventions
The semantic convention package follows the OpenTelemetry GenAI specification:
https://opentelemetry.io/docs/specs/semconv/gen-ai/

## Instrumentation Packages
Instrumentation packages should leverage the semantic conventions package. Their purpose is to instrument AI-related libraries and generate spans and tracing data compliant with OpenTelemetry semantic conventions.

## Code Quality
Flake8 is used for code linting.