@meldscience/meld/README.md

pipeable one-shot prompt scripting toolkit

# Oneshot

A set of simple command-line tools for working with AI prompts and code context.

## Installation

```bash
npm install -g @meldscience/oneshot
```

## Tools

### meld

Process a markdown file containing embedded commands and replace them with their output.

```bash
meld input.meld.md [options]
```

#### Input Format
```markdown
# My Prompt

Here's what the system looks like:

@cmd[tree src]

And here's the relevant code:

@cmd[cat src/main.ts]
```

#### Options
- `-o, --outfile <path>` - Output file path (default: input.meld.generated.md)
- `--dry-run` - Print commands that would be executed without running them

#### Examples

Process a prompt file:
```bash
meld myprompt.meld.md
# Creates myprompt.meld.generated.md
```

Specify output location:
```bash
meld myprompt.meld.md -o output.md
```

### oneshot

Send a prompt to one or more AI models with optional variations.

```bash
oneshot [model...] prompt.md [options]
```

The tool will send to all specified models in parallel. For example:
```bash
oneshot gpt-4 claude-3 claude-2 prompt.md
```

#### Options
- `-o, --outfile <path>` - Save output to file (default: stdout)
- `--system <prompt>` - System prompt
- `--system-file <path>` - System prompt from file
- `--variations <json>` - Variation prompts as JSON array
- `--variations-file <path>` - Variation prompts from file (JSON or YAML)
- `--iterations <number>` - Number of responses per variation (default: 1)

#### Examples

Basic usage:
```bash
oneshot claude-3 prompt.md
```

With system prompt:
```bash
oneshot gpt-4 prompt.md --system "You are a helpful programming assistant"
```

With variations from command line:
```bash
oneshot claude-3 prompt.md --variations '["Review as architect", "Review as developer"]'
```

With variations from file:
```yaml
# roles.yaml
architect: "Review this system as a software architect"
developer: "Review this system as a senior developer"
security: "Review this system focusing on security implications"
```

```bash
oneshot claude-3 prompt.md --variations-file roles.yaml
```

Save output to file:
```bash
oneshot claude-3 prompt.md -o response.md
```

Multiple iterations:
```bash
oneshot claude-3 prompt.md --iterations 3
```

### oneshotcat

Combine meld and oneshot functionality - process a prompt script and send it to an AI model.

```bash
oneshotcat [model] input.meld.md [options]
```

Accepts all oneshot options plus:
- `--expanded-outfile <path>` - Save processed prompt script to file

#### Examples

Basic usage:
```bash
oneshotcat claude-3 myprompt.meld.md
```

Save both prompt and response:
```bash
oneshotcat claude-3 myprompt.meld.md --expanded-outfile expanded.md -o response.md
```

## Output Formats

### meld Output

Creates a new markdown file with commands replaced by their output:

```markdown
# My Prompt

Here's what the system looks like:

```
src
├── main.ts
├── lib
│   └── utils.ts
└── tests
    └── main.test.ts
```

And here's the relevant code:

```typescript
import { something } from './lib/utils';

export function main() {
  // ...
}
```
```

### oneshot/oneshotcat Output

Outputs responses in markdown format, perfect for reading or piping to another command:

```markdown
# Architect Perspective
Based on the codebase structure...

# Developer Perspective
Looking at the implementation...

# Security Perspective
From a security standpoint...
```

The markdown format makes it easy to:
1. Read the output directly
2. Save to a file (`-o output.md`)
3. Pipe into another command for meta-analysis
4. Process with standard Unix text tools

## Configuration

Configuration can be provided via:
1. Environment variables
2. `.meldrc` file (in home directory when installed globally)
3. Command line arguments

Priority: CLI args > .meldrc > env vars

### Environment Variables
```bash
ANTHROPIC_API_KEY=your_key
OPENAI_API_KEY=your_key
DEFAULT_MODEL=claude-3
```

### .meldrc
```json
{
  "defaultModel": "claude-3",
  "anthropicApiKey": "your_key",
  "openaiApiKey": "your_key"
}
```

### 1Password Integration

You can securely store your API keys in 1Password and reference them in your `.meldrc`:

```json
{
  "defaultModel": "claude-3",
  "anthropicApiKey": "op://vault-name/anthropic/api-key",
  "openaiApiKey": "op://vault-name/openai/api-key"
}
```

The tool will automatically resolve these references using the 1Password CLI (`op`) if it's installed.

### Configuration Helper

Use the `meld-config` command to manage your configuration:

```bash
# Show current configuration
meld-config --show

# Set API keys
meld-config --anthropic-key <your-key>
meld-config --openai-key <your-key>

# Set default model
meld-config --default-model claude-3
```

### Multiple Models with Variations

You can combine multiple models with variations to get a rich set of perspectives:

```bash
oneshot gpt-4 claude-3 prompt.md --variations roles.yaml
```

This will get each role's perspective from each model, with output like:

```markdown
# GPT-4: Architect Perspective
[response...]

# GPT-4: Developer Perspective
[response...]

# Claude 3: Architect Perspective
[response...]

# Claude 3: Developer Perspective
[response...]
```

## Command Chaining

The tools are designed to work well with Unix pipes and support chaining for meta-analysis:

```bash
# Get multiple AI perspectives then analyze them together
oneshot claude-3 myprompt.md --variations roles.yaml | oneshot claude-3 secondprompt.md
```

Where `secondprompt.md` might contain something like:
```markdown
Review these three responses from different perspectives. Identify:
- Common themes
- Points of dissonance
- A recommended path balancing pragmatism, keeping in mind this is for a single developer/server rather than enterprise software.

---
[Previous responses will be inserted here]
```

You can also use immediate prompts for quick chains:
```bash
oneshot claude-3 myprompt.md --variations roles.yaml | oneshot claude-3 "analyze these perspectives and recommend a path forward"
```

## Module Usage

All tools can also be used programmatically:

```typescript
import { PromptScript, Oneshot, Oneshotcat } from 'ai-prompt-tools';

// Process a prompt script
const meld = new PromptScript({
  inputFile: 'prompt.meld.md',
  outputFile: 'output.md'
});
const expanded = await meld.process();

// Send to AI
const oneshot = new Oneshot({
  model: 'claude-3',
  promptFile: 'prompt.md',
  variations: ['perspective 1', 'perspective 2']
});
const responses = await oneshot.process();

// Combined usage
const cat = new Oneshotcat({
  model: 'claude-3',
  promptFile: 'prompt.meld.md',
  variations: ['perspective 1', 'perspective 2']
});
const results = await cat.process();
```