Integrate Playground with VRP-Toolkit

Token-efficient workflow for connecting Streamlit playground UI to vrp-toolkit backend APIs.

Core Problem

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.

Solution

This skill provides:

• Interface Mapping Table - Playground needs → vrp-toolkit APIs

• API Quick Reference - Exact signatures with usage examples

• Contract Test Integration - Automated verification of interfaces

• Common Error Patterns - Troubleshooting guide

Workflow

Step 1: Check Interface Mapping

Before writing any integration code:

• Open interface_mapping.md

• Find the workflow you're implementing (e.g., "Generate synthetic map")

• Note the exact API signature

• Check for common mistakes marked with ⚠️

Example:

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:

• Check if contract test exists in contracts/ directory

• Run the test: pytest contracts/test_<feature>.py -v

• Read test code to see usage examples

• Test validates: parameters accepted, attributes available, reproducibility

Example:

pytest contracts/test_realmap_api.py -v

See test_realmap_initialization() for usage example

Step 3: Write Integration Code

Follow the mapping table exactly:

✅ 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 for each API's pattern

Step 4: Add Error Handling

Common error patterns:

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:

Create test in contracts/test_<feature>.py

Test should verify:

• API signature matches mapping table

• Reproducibility (same seed → same result)

• Feasibility (results meet constraints)

• Objective values are consistent

Add test reference to interface_mapping.md

Template:

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

Quick Reference Files

For Complete API Details

See api_signatures.md for:

• Full parameter lists with types

• Return types and attributes

• Usage examples

• Import statements

For Contract Testing

See 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 for:

• Common error messages and fixes

• Module caching issues (need to restart Streamlit)

• Attribute vs method access patterns

• Missing parameter errors

Anti-Patterns to Avoid

❌ 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

Maintenance

When vrp-toolkit API changes:

• Update interface_mapping.md

• Update affected contract tests in contracts/

• Run tests to verify: pytest contracts/ -v

• Update playground code

• Update troubleshooting.md if new error patterns emerge

When adding new playground features:

• Add API to interface_mapping.md

• Add detailed signature to api_signatures.md

• Create contract test in contracts/

• Reference test in mapping table

Token Efficiency

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)