Skip to content

quickstart.md

Latest commit

 

History

History
443 lines (320 loc) · 8.93 KB

quickstart.md

File metadata and controls

443 lines (320 loc) · 8.93 KB

Quick Start Guide

Get up and running with Forge in 5 minutes.

Prerequisites

  • Python 3.11+ installed
  • Poetry installed (see Installation Guide)
  • KnowledgeForge patterns in patterns/

5-Minute Quick Start

Tip: Run pip install -e . once to install the forge command globally. Then you can use forge directly instead of forge. See Installation Guide for details.

Step 1: Verify Installation (30 seconds)

cd /path/to/forge

# Check Forge is working
forge --version
# Output: forge, version 1.0.0

# Run health check
forge doctor

Expected output:

✓ Python 3.11.13
✓ git installed
✓ docker installed
✓ KnowledgeForge patterns (28 files)
✨ Forge health check complete!

Step 2: Create Your First Project (1 minute)

# Create a new project
forge init "Task Board API" \
  --description "Kanban-style task management REST API"

Output:

✓ Initialized project: Task Board API
• ID: task-board-api-20251207
• Stage: planning

What happened:

  • Project created in SQLite database
  • Unique ID generated with timestamp
  • Initial checkpoint created
  • Project stage set to "planning"

Step 3: Search KnowledgeForge Patterns (1 minute)

# Search for relevant patterns
forge search "data pipeline"

# More specific search
forge search "machine learning orchestration" --max-results 5

# Try different search methods
forge search "API design" --method semantic

Output shows:

┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Filename                ┃ Title               ┃ Module ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ 01_Core_DataTransfer.md │ Data Transfer       │ Core   │
│ 02_Workflows_...        │ Workflow Patterns   │ ...    │
└─────────────────────────┴─────────────────────┴────────┘

Search methods:

  • keyword - Fast FTS5 full-text search
  • semantic - AI-powered similarity search
  • hybrid - Best of both (default)

Step 4: Check Project Status (30 seconds)

# View project details
forge status task-board-api-20251207

Output:

┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Property ┃ Value                           ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ ID       │ task-board-api-20251207 │
│ Name     │ Task Board API          │
│ Stage    │ planning                        │
│ Created  │ 2025-12-07 12:00:00            │
└──────────┴─────────────────────────────────┘

Step 5: View System Information (30 seconds)

# Get system stats
forge info

Output:

• Patterns indexed: 28
• Cache: 0/128 entries
• Cache hit rate: 0.0%
• Backend: codegen_api
• Search method: hybrid

Common Workflows

Activate Poetry Shell (Recommended)

Instead of typing poetry run each time:

# Activate Poetry shell
poetry shell

# Now run commands directly
forge doctor
forge search "patterns"
forge info

# Exit when done
exit

Search Patterns by Topic

# Find testing patterns
forge search "testing unit integration" --method keyword

# Find security patterns
forge search "authentication authorization security" --max-results 3

# Find orchestration patterns
forge search "workflow orchestration deployment" --method hybrid

Explore Pattern Content

After finding patterns, view them:

# Pattern files are in sibling directory
cat patterns/01_Core_DataTransfer.md
less patterns/02_Workflows_Orchestration.md

# Or use your favorite editor
code patterns/

Create Multiple Projects

# E-commerce platform
forge init "E-commerce Platform" \
  --description "Full-stack e-commerce with AI recommendations"

# Data pipeline
forge init "Analytics Pipeline" \
  --description "Real-time analytics data processing"

# Microservices
forge init "Payment Service" \
  --description "Secure payment processing microservice"

Using the Python API

For programmatic access:

from forge.core.orchestrator import Orchestrator
from forge.core.config import ForgeConfig

# Initialize
config = ForgeConfig.load()
orchestrator = Orchestrator(config)

# Create project
project = orchestrator.create_project(
    name="My API",
    description="RESTful API for mobile app"
)
print(f"Created: {project.id}")

# Search patterns
patterns = orchestrator.search_patterns(
    query="REST API design",
    max_results=5
)

for pattern in patterns:
    print(f"- {pattern['filename']}: {pattern['title']}")

# Clean up
orchestrator.close()

Configuration Quick Setup

Create Default Configuration

# Project-specific config
forge config

# Edit forge.yaml
nano forge.yaml

Basic Configuration

Edit forge.yaml:

generator:
  backend: codegen_api
  timeout: 300

knowledgeforge:
  patterns_dir: patterns
  search_method: hybrid
  cache_size: 128

log_level: INFO

Environment Variables

For API keys:

# Add to ~/.zshrc or ~/.bashrc
export CODEGEN_API_KEY="your-key-here"
export CODEGEN_ORG_ID="your-org-id"

# Reload shell
source ~/.zshrc

Testing Your Setup

Run Tests

# All tests
poetry run pytest

# Verbose output
poetry run pytest -v

# Specific test
poetry run pytest tests/test_pattern_store.py -v

Expected: 26 passed in ~17s

Verify Pattern Store

from forge.knowledgeforge.pattern_store import PatternStore

# Open pattern store
store = PatternStore()

# Check count
count = store.get_pattern_count()
print(f"Patterns indexed: {count}")  # Should be 28

# Test search
results = store.search("orchestration", max_results=3)
for r in results:
    print(f"- {r['filename']}")

store.close()

Next Steps

Now that you're up and running:

1. Learn More

2. Try Advanced Features

3. Explore the Codebase

  • Browse src/forge/ for implementation
  • Read tests/ for usage examples
  • Review architecture in docs/architecture/

4. Build Something

Follow the Tutorial to build a complete project.

Quick Reference

Essential Commands

# Health check
forge doctor

# Create project
forge init "Project Name" --description "Description"

# Search patterns
forge search "query" [--method keyword|semantic|hybrid] [--max-results N]

# Project status
forge status <project-id>

# System info
forge info

# Configuration
forge config [--global-config]

File Locations

  • Databases: .forge/patterns.db, .forge/state.db
  • Config: ./forge.yaml (project) or ~/.forge/config.yaml (global)
  • Patterns: patterns/*.md
  • Logs: .forge/forge.log

Getting Help

# Command help
forge --help
forge search --help
forge init --help

# Run doctor
forge doctor

# Check version
forge --version

Troubleshooting

Patterns Not Found

# Check patterns directory
ls patterns/*.md

# Should show 28 files
# If not:
mkdir -p patterns
# Copy your .md files there

Database Errors

# Reset databases
rm -rf .forge/
forge doctor  # Recreates databases

Import Errors

# Reinstall dependencies
poetry install --no-cache

Permission Issues

# Fix permissions
chmod -R 755 .forge/

Tips & Best Practices

💡 Use Poetry Shell

poetry shell  # Activate once
forge doctor  # Run commands without 'poetry run'

💡 Explore Patterns

The 28 KnowledgeForge patterns contain valuable best practices:

# List all patterns
ls patterns/

# Search for specific topics
forge search "your topic" --max-results 10

💡 Check System Status

Regularly run forge doctor to ensure everything is working:

forge doctor

💡 Use Hybrid Search

Hybrid search combines speed and accuracy:

forge search "query" --method hybrid  # Best results

Summary

You've now:

  • ✅ Verified Forge installation
  • ✅ Created your first project
  • ✅ Searched KnowledgeForge patterns
  • ✅ Checked project status
  • ✅ Viewed system information

Ready to dive deeper? Check out the User Guide!