integrate-playground

Developing playground features requires knowing exact API signatures of vrp-toolkit modules. Without reference documentation, this requires repeatedly reading source code (consuming thousands of tokens per integration) and leads to API mismatch errors.

This skill provides:

1. Interface Mapping Table - Playground needs → vrp-toolkit APIs
2. API Quick Reference - Exact signatures with usage examples
3. Contract Test Integration - Automated verification of interfaces
4. Common Error Patterns - Troubleshooting guide

Step 1: Check Interface Mapping

Before writing any integration code:

1. Open [interface_mapping.md](references/interface_mapping.md)
2. Find the workflow you're implementing (e.g., "Generate synthetic map")
3. Note the exact API signature
4. Check for common mistakes marked with ⚠️

Example:

```markdown

Need: Generate synthetic map

API: RealMap(n_r: int, n_c: int, dist_function: Callable, dist_params: Dict)

Common mistake: ❌ Don't use num_customers, use n_c

```

Step 2: Verify with Contract Test (Optional)

If uncertain about API behavior:

1. Check if contract test exists in contracts/ directory
2. Run the test: pytest contracts/test_.py -v
3. Read test code to see usage examples
4. Test validates: parameters accepted, attributes available, reproducibility

Example:

```bash

pytest contracts/test_realmap_api.py -v

# See test_realmap_initialization() for usage example

```

Step 3: Write Integration Code

Follow the mapping table exactly:

```python

# ✅ Correct: Use exact signature from mapping table

np.random.seed(seed) # For reproducibility

real_map = RealMap(

n_r=num_restaurants,

n_c=num_customers,

dist_function=np.random.uniform,

dist_params={'low': 0, 'high': 100}

)

# ❌ Wrong: Assumed API

real_map = RealMap(

num_customers=num_customers,

num_restaurants=num_restaurants,

area_size=100,

seed=seed

)

```

Data access pattern:

• Most generators create data in __init__, not via .generate() method
• Access via attributes: .demand_table, .order_table, .time_matrix
• See [interface_mapping.md](references/interface_mapping.md) for each API's pattern

Step 4: Add Error Handling

Common error patterns:

```python

try:

instance = PDPTWInstance(

order_table=order_table,

distance_matrix=real_map.distance_matrix,

time_matrix=order_gen.time_matrix,

robot_speed=1.0

)

except TypeError as e:

st.error(f"API mismatch: {e}")

st.info("Check interface_mapping.md for correct parameters")

```

Step 5: Add Contract Test (For New Integrations)

When adding new playground feature:

1. Create test in contracts/test_.py
2. Test should verify:

- API signature matches mapping table

- Reproducibility (same seed → same result)

- Feasibility (results meet constraints)

- Objective values are consistent

1. Add test reference to [interface_mapping.md](references/interface_mapping.md)

Template:

```python

# contracts/test_new_feature.py

def test_api_signature():

"""Verifies API matches interface_mapping.md"""

# Test exact parameters...

def test_reproducibility():

"""Same seed produces same result"""

np.random.seed(42)

result1 = generate_feature()

np.random.seed(42)

result2 = generate_feature()

assert result1 == result2

```

For Complete API Details

See [api_signatures.md](references/api_signatures.md) for:

• Full parameter lists with types
• Return types and attributes
• Usage examples
• Import statements

For Contract Testing

See [contract_tests.md](references/contract_tests.md) for:

• How to write contract tests
• Test organization patterns
• Running and maintaining tests
• Linking tests to mapping table

For Troubleshooting

See [troubleshooting.md](references/troubleshooting.md) for:

• Common error messages and fixes
• Module caching issues (need to restart Streamlit)
• Attribute vs method access patterns
• Missing parameter errors

❌ Don't assume API signatures

• Always check mapping table first
• Don't guess parameter names

❌ Don't repeatedly read source code

• Use this skill's mapping table (< 1000 tokens)
• Avoid re-reading vrp-toolkit source (several thousand tokens each time)

❌ Don't call non-existent methods

• Check if it's an attribute or method
• Most generators use attributes: .demand_table, not .generate()

❌ Don't skip contract tests for complex integrations

• Tests catch issues early
• Tests document expected behavior
• Tests prevent regressions

When vrp-toolkit API changes:

1. Update [interface_mapping.md](references/interface_mapping.md)
2. Update affected contract tests in contracts/
3. Run tests to verify: pytest contracts/ -v
4. Update playground code
5. Update [troubleshooting.md](references/troubleshooting.md) if new error patterns emerge

When adding new playground features:

1. Add API to [interface_mapping.md](references/interface_mapping.md)
2. Add detailed signature to [api_signatures.md](references/api_signatures.md)
3. Create contract test in contracts/
4. Reference test in mapping table

Without this skill:

• Read RealMap source: ~1500 tokens
• Read DemandGenerator source: ~1200 tokens
• Read OrderGenerator source: ~1800 tokens
• Read PDPTWInstance source: ~2000 tokens
• Total: ~6500 tokens per integration

With this skill:

• Read interface_mapping.md: ~800 tokens
• Total: ~800 tokens per integration

Savings: ~5700 tokens (87% reduction)