# {{projectName}}

{{description}}

## Prerequisites

- Node.js >= 24.3
- Docker and Docker Compose (for local development)

## Project Structure

```
src/
├── clients/                   # API clients (e.g., jina.ts)
├── shared/                    # Shared code across workflows
│   └── utils/                 # Utility functions (e.g., string.ts)
└── workflows/                 # Workflow definitions
    └── blog_evaluator/        # Example workflow
        ├── workflow.ts        # Main workflow
        ├── steps.ts           # Workflow steps
        ├── evaluators.ts      # Quality evaluators
        ├── types.ts           # Shared types and schemas
        ├── utils.ts           # Local utilities
        ├── prompts/           # LLM prompts
        └── scenarios/         # Test scenarios
```

### Clients Directory

The `src/clients/` directory contains API clients using `@outputai/http` for external services.

### Shared Directory

The `src/shared/` directory contains code shared across multiple workflows:

- **`shared/utils/`** - Helper functions and utilities

### Import Rules

**Workflows** can import from:
- Local steps, evaluators, and utilities
- Clients, shared steps, evaluators, and utilities

**Steps and Evaluators** can import from:
- Local utilities and clients
- Clients and shared utilities

**Steps and Evaluators cannot** import from:
- Other steps or evaluators (Temporal activity isolation)

## Getting Started

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Credentials

Initialize and add your API keys using the Output credentials manager:

```bash
npx output credentials init
npx output credentials edit
```

Add your keys in the editor:
- `anthropic.api_key` - for Claude LLM integration
- `openai.api_key` - for OpenAI LLM integration (optional)

### 3. Start Output Services

```bash
npm run output:dev
```

This starts:
- Temporal server and UI (http://localhost:8080)
- PostgreSQL and Redis databases
- Output.ai API server (http://localhost:3001)
- Worker process for executing workflows

### 4. Run a workflow

In a new terminal:

```bash
npx output workflow run blog_evaluator paulgraham_hwh
```

### 5. Stop Services

Press `Ctrl+C` in the terminal running `npm run output:dev` to stop all services gracefully.

### 6. View Logs

Monitor workflow execution and system status in the Temporal UI:

```bash
open http://localhost:8080
```

## Checking Workflows for Bad Imports

Temporal bundles your workflows before they run. If a workflow — or anything it
transitively imports — pulls in a `node:` built-in (e.g. `node:fs`), the bundle fails
**at worker startup**, not at `tsc` build time. The optional bundle check reproduces
that bundling so you catch it early:

```bash
npm run output:worker:build   # compile to dist/
npm run output:worker:check   # bundle-check workflows (runs output-worker --check)
```

It exits non-zero and names the offending module when a workflow can't be bundled.

To gate merges, wire it into your CI — for example, GitHub Actions:

```yaml
# .github/workflows/output-check.yml
name: Output checks
on: [pull_request]
jobs:
  workflows:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npm ci
      - run: npm run output:worker:build
      - run: npm run output:worker:check
```
