Design: Balance between general-purpose API and project-specific helpers

[turbomam]

Summary

Clarify architectural philosophy: stay general-purpose while supporting NMDC-specific use cases.

Current Tension

General-purpose (good):

weather_result = service.get_weather(lat, lon, date)  # Rich, flexible

NMDC-specific (too narrow):

annual_precpt = service.get_annual_precpt(lat, lon)  # Slot-specific
annual_temp = service.get_annual_temp(lat, lon)
# Would need 100+ methods for every submission-schema slot!

Olivia's Feedback

"If you want this to be used by different projects, try not to get too in the weeds of making a function per slot - that would be NMDC's job. You want to be able to develop a framework that any project can easily access the weather, soil, flooding, etc data that they need easier with your package than reaching out to the API."

Proposed Approach

Keep general services:

# Core API - general and flexible
weather_result = weather_service.get_weather(lat, lon, date)
annual_precip = weather_service.get_annual_precipitation(lat, lon)

Add extraction helpers:

# Convenience methods for common formats
simple_values = weather_result.to_submission_schema()
# Returns: {"annual_temp": 12.5, "annual_precpt": 225.0}

Don't create:

• Per-slot methods (get_annual_precpt(), get_annual_temp(), etc.)
• NMDC-specific business logic
• Slot validation or schema enforcement

Do create:

• General data retrieval methods
• Format conversion utilities
• Clear documentation showing how to extract values

Benefits

1. Reusable - Other projects can use the same API
2. Maintainable - No explosion of slot-specific methods
3. Flexible - Projects choose how to map data to their schemas
4. Clear separation - biosample-enricher provides data, nmdc-server handles schema logic

References

• Olivia Hess DM conversation 2025-11-21
• Related: Add submission-schema extraction helpers #193 (submission-schema helpers)