Files

alexpolo1 653e364b1e chore: reorganize docs - move md files to correct locations

- Move root-level status/feature/summary MDs into docs/ subdirs
- Convert .txt documentation files to .md format
- Tests-related MD moved to tests/
- Root now only contains README.md, CLAUDE.md, GEMINI.md

2026-02-28 18:37:46 +00:00

13 KiB

Raw Blame History

✅ OPENAI CARPENTER AGENT - SETUP COMPLETE

🎯 WHAT WAS CREATED:

🤖 CLI-Based OpenAI Agent (carpenter-agent-openai.js)
- Interactive multi-turn conversations with AI carpenters
- Automatic quote generation using GPT-4
- Natural language processing and understanding
- JSON output for integration with other systems
- 3 realistic carpenter personas with distinct voices
🌐 Browser-Based OpenAI Agent (tests/carpenter-agent-openai.spec.js)
- Playwright-based end-to-end testing
- OpenAI decides which UI elements to interact with
- Intelligent form filling and navigation
- Dynamic adaptation to different UI structures
- Automatic quote generation validation
📚 Complete Documentation (docs/OPENAI_CARPENTER_AGENT_GUIDE.md)
- Detailed usage instructions for both agents
- API integration guide
- Customization examples
- Cost estimation and troubleshooting
🚀 Quick Start Scripts
- carpenter-agent-openai-quickstart.sh (interactive menu)
- Easy setup for first-time users

═══════════════════════════════════════════════════════════════════════

🔧 REQUIREMENTS

Required: ✅ Node.js 18+ (already installed) ✅ OpenAI API Key (GPT-4 model) ✅ Playwright (for browser tests)

Optional:

VS Code (for editing)
Playwright browser binaries

🚀 QUICK START

Step 1: Get OpenAI API Key ─────────────────────────

Visit: https://platform.openai.com/account/api-keys
Create new secret key
Copy it

Step 2: Set Environment Variable ─────────────────────────────────

In terminal:

export OPENAI_API_KEY="sk-..."

Or save to .env:

echo "OPENAI_API_KEY=sk-..." >> .env

Step 3: Run the Agent ────────────────────

Interactive chat

node carpenter-agent-openai.js --interactive

Generate 5 quotes

node carpenter-agent-openai.js --generate-quotes=5 --save

Browser tests

cd tests && npx playwright test carpenter-agent-openai.spec.js --headed

Or use quick start script:

./carpenter-agent-openai-quickstart.sh

📋 AVAILABLE COMMANDS

CLI Agent: ──────────

Interactive mode (default carpenter: Lars)

node carpenter-agent-openai.js --interactive

Interactive with specific carpenter

node carpenter-agent-openai.js --interactive --carpenter=jannick node carpenter-agent-openai.js --interactive --carpenter=alexander

Generate quotes (batch mode)

node carpenter-agent-openai.js --generate-quotes=5 --save node carpenter-agent-openai.js --generate-quotes=10

Show help

node carpenter-agent-openai.js

Browser Tests: ──────────────

Run all tests

cd tests && npx playwright test carpenter-agent-openai.spec.js

Headed browser (see what happens)

npx playwright test carpenter-agent-openai.spec.js --headed

UI debug mode

npx playwright test carpenter-agent-openai.spec.js --ui

Show report

npx playwright show-report

🏗️ HOW IT WORKS

CLI Agent Flow:

User chooses carpenter and interacts naturally
AI receives user message + system prompt
OpenAI GPT-4 generates response based on carpenter persona
AI asks clarifying questions about project
When enough info gathered, AI generates quote
Quote is extracted and saved as JSON

Browser Agent Flow:

Playwright loads the website
Captures current page state (buttons, inputs, headings)
Sends page state to OpenAI
AI decides next action (click, fill, type)
Playwright executes the action
Process repeats until quote is generated
Test data saved with screenshots

👷 CARPENTER PERSONAS

Lars Nielsen (15 years) Specialty: Roofing & Terraces Approach: Methodical, detail-focused, high quality Projects: Roof repairs, terraces, thatch roofing
Jannick Andersen (12 years) Specialty: Interior Renovations Approach: Creative, solution-oriented, listens to needs Projects: Flooring, wardrobes, kitchen work
Alexander Ørneby Andersen (8 years) Specialty: Modern Construction & Renovation Approach: Tech-savvy, sustainable, communicative Projects: Door installation, window casings, full renovations

💻 EXAMPLE SESSION

Interactive Chat Example: ────────────────────────

$ node carpenter-agent-openai.js --interactive --carpenter=lars

════════════════════════════════════════════════════════════════════════ 🔨 CARPENTER AGENT: Lars Nielsen 📍 Specialty: Tag og terrasser Experience: 15 år ════════════════════════════════════════════════════════════════════════

🔨 Lars Nielsen: Hej! Jeg er Lars Nielsen. Jeg har 15 år erfaring inden for tag og terrasser. Hvordan kan jeg hjælpe dig i dag? Hvad for et projekt er du ved at planlægge?

👤 Du: Jeg har en tagflade der lækker

🔨 Lars Nielsen: Ah, det kan være problematisk. Kan du fortælle mig:

Hvor stort område cirka?
Hvor gammelt er taget?
Hvor er lækagen lokaliseret?

👤 Du: Det er omkring 40m², omkring 20 år gammelt, og der lækker ved en samling

⏳ Carpenter is thinking...

🔨 Lars Nielsen: ---QUOTE_SUMMARY--- PROJEKT: Tagreparation - Lække ved samling BESKRIVELSE: Udbedring af lække område på 40m² tagflade, omkring 20 år gammelt OMRÅDE: 40 m² ESTIMERET VARIGHED: 3-5 dage ESTIMERET PRIS: DKK 35.000 - 45.000 MATERIALER: Tagsten, mørtelmasse, bly, lister, underlay NOTER: Vil kræve hegning og sikkerhedsudstyr. Vejr-afhængigt arbejde. ---END_QUOTE---

✅ Quote generated! Saving...

💰 PRICING & COSTS

OpenAI API Usage: ─────────────────

Model: GPT-4

Input: ~$0.03 per 1,000 tokens
Output: ~$0.06 per 1,000 tokens

Estimated Costs:

1 chat session: ~$0.10-0.20
5 quote generations: ~$0.10-0.20
10 browser tests: ~$0.20-0.50
100 runs/month: ~$10-20

Tips to Save Money:

Use gpt-3.5-turbo instead (10x cheaper, still good quality)
Batch generate quotes off-hours
Set reasonable token limits
Cache common prompts

📊 OUTPUT FILES

Generated Test Data: ────────────────────

test-results/carpenter-openai-data/ ├── ai-quotes-2025-12-23.json (Generated quotes) ├── quote-Lars-Nielsen-12345.json (Individual quote) └── ...

Playwright Tests: ─────────────────

test-results/ ├── carpenter-openai-lars-0-quote.png (Screenshot) ├── carpenter-openai-lars-0.json (Test data) └── playwright-report/ (Full report)

🔍 VALIDATION

The agent validates: ✓ Quote format and structure ✓ Reasonable price ranges (based on area) ✓ Realistic timelines (days/weeks) ✓ Material selection (appropriate for project type) ✓ Professional language and tone ✓ Complete project information

🐛 TROUBLESHOOTING

Issue: "OPENAI_API_KEY is not set" Solution: export OPENAI_API_KEY="sk-..." node carpenter-agent-openai.js --generate-quotes=1

Issue: "Model gpt-4 not available" Solution: Use gpt-3.5-turbo instead (edit the script) or request GPT-4 access at openai.com

Issue: "Playwright timeout" Solution: cd tests npx playwright test --timeout 60000 npx playwright install

Issue: "API rate limit exceeded" Solution: Add delays between requests or use gpt-3.5-turbo (higher rate limits)

📚 INTEGRATION EXAMPLES

Using in Your Tests: ───────────────────

JavaScript: const quotes = JSON.parse( fs.readFileSync('test-results/carpenter-openai-data/ai-quotes.json') );

Python: import json with open('test-results/carpenter-openai-data/ai-quotes.json') as f: quotes = json.load(f)

Load Testing: // Use generated quotes for concurrent requests for (const quote of quotes) { // Submit quote to API }

📖 DOCUMENTATION

Full guides available:

docs/OPENAI_CARPENTER_AGENT_GUIDE.md (Comprehensive guide)
docs/CARPENTER_AGENT_GUIDE.md (Basic guide)
CARPENTER_AGENT_README.txt (Overview)

✅ FILES CREATED

Root: ✓ carpenter-agent-openai.js (440 lines) ✓ carpenter-agent-openai-quickstart.sh

Tests: ✓ tests/carpenter-agent-openai.spec.js (190 lines)

Documentation: ✓ docs/OPENAI_CARPENTER_AGENT_GUIDE.md

🚀 NEXT STEPS

✅ Get OpenAI API key from https://platform.openai.com
✅ Export: export OPENAI_API_KEY="sk-..."
✅ Try interactive: node carpenter-agent-openai.js --interactive
✅ Generate quotes: node carpenter-agent-openai.js --generate-quotes=5 --save
✅ Run tests: cd tests && npx playwright test carpenter-agent-openai.spec.js --headed
✅ Check results in: test-results/carpenter-openai-data/

💡 TIPS & TRICKS

Use --generate-quotes in a cron job to create fresh test data
Combine with other tests for comprehensive validation
Analyze generated quotes for realistic pricing patterns
Use different carpenter personas for diverse test scenarios
Export quotes to Excel/PDF for real customer testing

Questions? Check:

docs/OPENAI_CARPENTER_AGENT_GUIDE.md
carpenter-agent-openai.js (well-commented source)
OpenAI API documentation: https://platform.openai.com/docs

Ready to test! 🚀

13 KiB Raw Blame History