@coval/wizard

Add Coval OTel tracing to your AI agent with one command.

The wizard reads your Python agent code, uses an LLM to figure out exactly where to inject tracing, and writes the changes for you — with diffs, backups, and validation.

Quick Start

npx @coval/wizard

That's it. Run it from your agent's project directory and follow the prompts.

What It Does

1. Detects your Python project and framework (Pipecat, LiveKit Agents, or generic)
2. Analyzes your entry point with an LLM (Anthropic, OpenAI, or Gemini) to determine the minimal changes needed
3. Shows a colored diff of proposed changes and asks for confirmation
4. Creates coval_tracing.py — a self-contained OpenTelemetry module for Coval
5. Modifies your entry point to initialize tracing (original backed up to .bak)
6. Validates by sending a test span to api.coval.dev

Supported Frameworks

Framework	Detection	Sim ID Extraction
Pipecat	pipecat-ai in deps	args.body dialin settings
LiveKit Agents	livekit-agents in deps	SIP participant attributes
Generic Python	Any .py project	Manual (TODO added)

Options

npx @coval/wizard [directory] [options]

Options:
  --yes, -y    Skip confirmation prompts (for CI/automation)

Environment Variables

Variable	Required	Description
COVAL_API_KEY	Yes	Your Coval API key (prompted if not set)
WIZARD_LLM_KEY	No	LLM API key for local dev (bypasses Coval proxy)
WIZARD_LLM_PROVIDER	No	anthropic (default), openai, or gemini
WIZARD_LLM_MODEL	No	Override the default model (e.g. gpt-4o, gemini-2.5-flash)

Development

git clone https://github.com/coval-ai/wizard
cd wizard
npm install
npm run dev -- /path/to/your/agent

Commands

npm run dev          # Run wizard locally via tsx
npm run build        # Build for distribution
npm run test         # Run tests
npm run lint         # Lint with ESLint
npm run format       # Format with Prettier
npm run check        # Run all checks (typecheck + lint + format + test)

Testing Against a Real Agent

# Anthropic (default)
COVAL_API_KEY=your-key WIZARD_LLM_KEY=sk-ant-... npm run dev -- ../your-agent/

# OpenAI
COVAL_API_KEY=your-key WIZARD_LLM_KEY=sk-... WIZARD_LLM_PROVIDER=openai npm run dev -- ../your-agent/

# Gemini
COVAL_API_KEY=your-key WIZARD_LLM_KEY=AIza... WIZARD_LLM_PROVIDER=gemini npm run dev -- ../your-agent/

How It Works

The wizard sends your entry point code to the configured LLM with a detailed system prompt containing:

• The complete coval_tracing.py reference implementation
• Framework-specific injection rules (where to place imports, setup calls, sim ID extraction)
• Strict output format (JSON with the generated files)

The LLM returns the modified entry point and a coval_tracing.py tailored to your agent. The wizard shows the diff, asks for confirmation, then writes the files.

Releases & Publishing

Releases are fully automatic on every merge to main. No manual version bumps or tags needed.

How it works

1. Merge a PR with a conventional commit title — the squash-merge commit message determines the version bump:

   Commit prefix	Bump	Example
   feat:	minor (1.x.0)	feat: add gemini support
   fix: / perf:	patch (1.0.x)	fix: handle 403 as invalid key
   feat!: / fix!:	major (x.0.0)	feat!: redesign CLI
   chore: / ci: / docs:	no release	—

2. Linear ticket prefixes are stripped automatically. A PR titled [SIM-123] feat: add something is treated identically to feat: add something.

3. A GitHub Release is created with auto-generated notes.

4. The GitHub Release triggers npm publish — the package is built and published with the release tag as the version.

License

MIT