ComputerAssignments/CA8_neural_program_synthesis/docs/QUICKSTART.md

Quick Start Guide - CA8 Neural Program Synthesis

🚀 Getting Started in 5 Minutes

Step 1: Installation

cd CA8_neural_program_synthesis
pip install -r requirements.txt

Note: If you encounter dependency issues, you can install core packages only:

pip install torch numpy pandas matplotlib tqdm

Step 2: Run Your First Demo

python demos/advanced_synthesis_demo.py

This will demonstrate all 6 synthesis techniques with example outputs.

Step 3: Try the Complete System

python demos/complete_synthesis_project.py

This runs an integrated system that automatically selects the best technique for each task.

📝 Basic Usage Examples

Example 1: Simple Program Synthesis

from neural_program_synthesis import Seq2SeqProgramSynthesizer
import torch

# Initialize
synthesizer = Seq2SeqProgramSynthesizer(
    vocab_size=1000,
    embedding_dim=256,
    hidden_dim=512
)

# Create dummy input (in practice, tokenize your specification)
spec_ids = torch.randint(0, 1000, (1, 10))
spec_lengths = torch.tensor([10])

# Generate program
synthesizer.eval()
with torch.no_grad():
    program = synthesizer.generate(
        spec_ids,
        spec_lengths,
        max_length=50
    )

print("Generated program tokens:", program)

Example 2: Hierarchical Synthesis

from neural_program_synthesis import HierarchicalProgramSynthesizer

# Initialize
hierarchical = HierarchicalProgramSynthesizer(
    vocab_size=1000,
    embedding_dim=256,
    hidden_dim=512,
    max_depth=3
)

# Synthesize
program_tree = hierarchical.synthesize_hierarchical(
    spec_ids,
    spec_lengths
)

# Access generated code
print("Generated code:")
print(program_tree.code)

Example 3: Program Fixing

from neural_program_synthesis import (
    DifferentiableProgramFixer,
    PythonExecutor,
    SimpleTokenizer
)

# Initialize
fixer = DifferentiableProgramFixer(vocab_size=1000)
executor = PythonExecutor()
tokenizer = SimpleTokenizer(vocab_size=1000)

# Buggy program
buggy_code = """
def average(numbers):
    return sum(numbers) / len(numbers)  # Bug: doesn't handle empty list
"""

# Test cases
test_cases = [
    {"input": {"numbers": [1, 2, 3]}, "expected_output": 2.0},
    {"input": {"numbers": []}, "expected_output": 0},
]

# Fix iteratively
fixed_code, success, history = fixer.iterative_fix(
    buggy_code,
    test_cases,
    executor,
    tokenizer,
    max_iterations=5
)

print(f"Success: {success}")
print(f"Fixed in {len(history)} iterations")
print("Fixed code:")
print(fixed_code)

Example 4: LLM Integration (Optional)

from integrations.llm_program_synthesis import (
    LLMProgramSynthesizer,
    SynthesisRequest,
    LLMProvider
)

# Set API key (optional)
import os
os.environ["OPENAI_API_KEY"] = "your-key-here"

# Initialize
synthesizer = LLMProgramSynthesizer(
    provider=LLMProvider.OPENAI,
    model="gpt-4"
)

# Create request
request = SynthesisRequest(
    specification="Create a function to calculate factorial",
    language="python",
    constraints=[
        "Use recursion",
        "Handle n=0 case",
        "Add type hints"
    ],
    examples=[
        {"input": {"n": 5}, "output": 120},
        {"input": {"n": 0}, "output": 1}
    ]
)

# Synthesize
response = synthesizer.synthesize(request, validate=True)

if response.success:
    print("Generated code:")
    print(response.code)
else:
    print(f"Error: {response.error}")

🎯 Common Use Cases

Use Case 1: Generate Arithmetic Functions

from demos.complete_synthesis_project import (
    CompleteSynthesisSystem,
    ProgramTask
)

# Initialize system
system = CompleteSynthesisSystem(vocab_size=1000)

# Create task
task = ProgramTask(
    id="task_001",
    name="Sum Two Numbers",
    specification="Create a function that returns the sum of two numbers",
    test_cases=[
        {"input": {"a": 5, "b": 3}, "expected_output": 8},
        {"input": {"a": -2, "b": 7}, "expected_output": 5},
    ],
    difficulty="easy",
    category="arithmetic"
)

# Synthesize
result = system.synthesize(task, technique="auto")

print(f"Success: {result.success}")
print(f"Pass rate: {result.test_pass_rate:.1%}")
print("Generated code:")
print(result.code)

Use Case 2: Explore Multiple Solutions

from neural_program_synthesis import TreeOfThoughtsProgramSynthesizer

# Initialize
tot = TreeOfThoughtsProgramSynthesizer(
    vocab_size=1000,
    num_thoughts=3  # Generate 3 candidate solutions
)

# This will explore multiple synthesis paths
# and return the best solution

Use Case 3: Interactive Development

from neural_program_synthesis import REPLGuidedSynthesizer

# Initialize
repl = REPLGuidedSynthesizer(vocab_size=1000)

# Synthesize with execution feedback
# The system will execute partial programs
# and use the results to guide synthesis

📚 What to Explore Next

1. Documentation

• README.md: Complete project overview
• ADVANCED_TECHNIQUES.md: Detailed technique explanations
• IMPLEMENTATION_SUMMARY.md: What was implemented

2. Demos

• advanced_synthesis_demo.py: All 6 techniques
• complete_synthesis_project.py: Integrated system

3. Notebooks (Coming Soon)

• Hierarchical Program Synthesis
• Differentiable Program Fixing
• REPL-Guided Synthesis
• Tree-of-Thoughts
• RL-based Synthesis
• Complete System Tutorial

4. Source Code

• neural_program_synthesis.py: Core implementations
• integrations/llm_program_synthesis.py: LLM integration

🔧 Configuration

Model Configuration

Edit config.py to customize:

MODEL_CONFIGS = {
    "seq2seq": {
        "vocab_size": 1000,
        "embedding_dim": 256,
        "hidden_dim": 512,
        "num_layers": 2,
    },
    # ... more configs
}

Training Configuration

TRAINING_CONFIGS = {
    "batch_size": 32,
    "learning_rate": 0.001,
    "num_epochs": 100,
    "max_length": 100,
}

🐛 Troubleshooting

Issue: ImportError for torch

Solution: Install PyTorch

pip install torch torchvision torchaudio

Issue: LLM API errors

Solution: Set API keys or use local mode

export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GOOGLE_API_KEY="your-key"

Or use local fallback:

synthesizer = LLMProgramSynthesizer(provider=LLMProvider.LOCAL)

Issue: CUDA out of memory

Solution: Reduce model size or batch size

synthesizer = Seq2SeqProgramSynthesizer(
    vocab_size=500,  # Smaller vocab
    embedding_dim=128,  # Smaller embeddings
    hidden_dim=256  # Smaller hidden size
)

💡 Tips

1. Start Simple: Begin with the basic Seq2Seq model
2. Use Demos: Run demos to see all features
3. Read Docs: Check ADVANCED_TECHNIQUES.md for details
4. Experiment: Try different techniques on your tasks
5. Validate: Always validate generated code

🎓 Learning Path

Beginner

1. Run advanced_synthesis_demo.py
2. Read README.md
3. Try basic examples above
4. Explore config.py

Intermediate

1. Study ADVANCED_TECHNIQUES.md
2. Run complete_synthesis_project.py
3. Modify demo tasks
4. Experiment with hyperparameters

Advanced

1. Implement custom synthesis techniques
2. Train on your own datasets
3. Integrate with your applications
4. Contribute improvements

📞 Getting Help

• Documentation: Check docs/ folder
• Examples: See demos/ folder
• Issues: Open GitHub issue
• Questions: Contact maintainers

✅ Quick Checklist

• Installed dependencies
• Ran first demo
• Tried basic examples
• Read documentation
• Explored source code
• Experimented with techniques

🎉 You're Ready!

You now have a working neural program synthesis system. Start experimenting and building amazing applications!

---

Happy Coding! 🚀