From 8a8d747dc9548acf3fadec20dc225480b9bed812 Mon Sep 17 00:00:00 2001 From: Pierre Lecerf Date: Thu, 19 Nov 2026 23:52:13 +0100 Subject: [PATCH] feat(core): asset metadata for json schemas and kebab-case through naming strategy * feat: SecretKey value type for secret references in assets * feat: descriptions and defaults on assets, profiles and scenarios * refactor: implicit property names, kebab-case YAML derived from the naming strategy; only aliases for assets persisted before 0.15 and legacy scenario names are kept * fix: applicability days-of-week ignored in YAML configurations * fix: Country.WORLD serialization (XXX), mapped to WOR for Boavizta and Ecologits * test: naming guard, documented configurations read without ignored keys --- .../wombat/core/activity/commons/Country.java | 44 +++- .../core/activity/commons/TimeRange.java | 7 +- .../wombat/core/asset/AssetIdentity.java | 8 +- .../wombat/core/asset/profile/Lifetime.java | 2 + .../wombat/core/asset/type/AssetType.java | 8 +- .../impact/BoaviztaEvaluationResolver.java | 10 +- .../impact/EcologitsEvaluationResolver.java | 9 +- .../illuin/wombat/core/secret/SecretKey.java | 35 +++ .../illuin/wombat/core/source/Period.java | 2 + .../core/activity/commons/CountryTest.java | 36 +++ .../BoaviztaEvaluationResolverTest.java | 20 ++ .../EcologitsEvaluationResolverTest.java | 21 ++ .../wombat/core/secret/SecretKeyTest.java | 39 +++ doc/module/llm-vertexai.md | 2 +- doc/type-glossary.md | 10 + module/pom.xml | 14 + .../kubernetes_api/KubernetesAPIAsset.java | 17 +- .../KubernetesAPIServerProfile.java | 13 +- .../KubernetesStaticAsset.java | 6 +- .../KubernetesStaticProfile.java | 18 +- .../scenario/BatchActivityScenario.java | 26 +- .../scenario/ConstantScenario.java | 11 +- .../scenario/UserActivityScenario.java | 26 +- .../scenario/tools/ApplicabilityFilter.java | 8 +- .../llm_anthropic/LLMAnthropicAsset.java | 18 +- .../llm_anthropic/LLMAnthropicProfile.java | 14 +- .../connector/AnthropicClientConfig.java | 2 +- .../llm_prometheus/LLMPrometheusAsset.java | 22 +- .../llm_prometheus/LLMPrometheusProfile.java | 15 +- .../connector/PrometheusClientConfig.java | 2 +- .../module/llm_static/LLMStaticAsset.java | 6 +- .../module/llm_static/LLMStaticProfile.java | 17 +- .../scenario/BatchActivityScenario.java | 27 +- .../llm_static/scenario/ConstantScenario.java | 15 +- .../scenario/UserActivityScenario.java | 27 +- .../scenario/tools/ApplicabilityFilter.java | 8 +- .../module/llm_vertexai/LLMVertexAIAsset.java | 21 +- .../llm_vertexai/LLMVertexAIProfile.java | 8 +- .../connector/GoogleClientConfig.java | 2 +- .../wombat/module/AssetConfigurationTest.java | 247 ++++++++++++++++++ .../illuin/wombat/module/AssetJsonTest.java | 2 +- .../KubernetesStaticProfileTest.java | 12 +- .../llm_anthropic/LLMAnthropicModuleTest.java | 3 +- .../LLMAnthropicActivityResolverTest.java | 3 +- .../connector/AnthropicClientConfigTest.java | 3 +- .../LLMPrometheusAssetTest.java | 3 +- .../LLMPrometheusModuleTest.java | 3 +- .../connector/PrometheusClientConfigTest.java | 3 +- .../llm_static/LLMStaticProfileTest.java | 8 +- .../scenario/ScenarioSerializationTest.java | 16 +- .../llm_vertexai/LLMVertexAIAssetTest.java | 3 +- .../llm_vertexai/LLMVertexAIModuleTest.java | 3 +- .../llm_vertexai/LLMVertexAIProfileTest.java | 6 +- .../connector/GoogleClientConfigTest.java | 3 +- .../connector/GoogleRegionTest.java | 2 +- 55 files changed, 711 insertions(+), 205 deletions(-) create mode 100644 core/src/main/java/tech/illuin/wombat/core/secret/SecretKey.java create mode 100644 core/src/test/java/tech/illuin/wombat/core/secret/SecretKeyTest.java create mode 100644 module/src/test/java/tech/illuin/wombat/module/AssetConfigurationTest.java diff --git a/core/src/main/java/tech/illuin/wombat/core/activity/commons/Country.java b/core/src/main/java/tech/illuin/wombat/core/activity/commons/Country.java index cb3e31b..dc1579c 100644 --- a/core/src/main/java/tech/illuin/wombat/core/activity/commons/Country.java +++ b/core/src/main/java/tech/illuin/wombat/core/activity/commons/Country.java @@ -1,19 +1,27 @@ package tech.illuin.wombat.core.activity.commons; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonCreator; import com.fasterxml.jackson.annotation.JsonValue; +import java.util.Comparator; import java.util.HashMap; +import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Optional; +@JsonClassDescription("ISO 3166-1 alpha-3 country code, XXX for the world") public final class Country { private final Locale locale; + private final String alpha2; + private final String alpha3; + private final String name; private static final Map indexAlpha2; private static final Map indexAlpha3; + private static final List values; static { indexAlpha2 = new HashMap<>(); @@ -25,9 +33,13 @@ public final class Country indexAlpha3.put(country.alpha3(), country); } - var world = new Country(Locale.ROOT); - indexAlpha2.put("XX", world); - indexAlpha3.put("XXX", world); + var world = new Country(Locale.ROOT, "XX", "XXX", "World"); + indexAlpha2.put(world.alpha2(), world); + indexAlpha3.put(world.alpha3(), world); + + values = indexAlpha3.values().stream() + .sorted(Comparator.comparing(Country::alpha3)) + .toList(); } public static final Country WORLD = ofAlpha2("XX"); @@ -77,15 +89,31 @@ public static Country ofAlpha3(String alpha3) return indexAlpha3.get(alpha3.toUpperCase()); } + /** + * @return every known country, ordered by alpha-3 code + */ + public static List values() + { + return values; + } + public static Optional ofCode(String code) { return Optional.ofNullable(ofAlpha2(code)) .or(() -> Optional.ofNullable(ofAlpha3(code))); } - private Country(Locale locale) + private Country(Locale locale, String alpha2, String alpha3, String name) { this.locale = locale; + this.alpha2 = alpha2; + this.alpha3 = alpha3; + this.name = name; + } + + private Country(Locale locale) + { + this(locale, locale.getCountry(), locale.getISO3Country(), null); } private Country(String alpha2Code) @@ -95,22 +123,22 @@ private Country(String alpha2Code) public String alpha2() { - return this.locale.getCountry(); + return this.alpha2; } @JsonValue public String alpha3() { - return this.locale.getISO3Country(); + return this.alpha3; } public String displayName() { - return this.locale.getDisplayCountry(Locale.ENGLISH); + return this.displayName(Locale.ENGLISH); } public String displayName(Locale locale) { - return this.locale.getDisplayCountry(locale); + return this.name != null ? this.name : this.locale.getDisplayCountry(locale); } } diff --git a/core/src/main/java/tech/illuin/wombat/core/activity/commons/TimeRange.java b/core/src/main/java/tech/illuin/wombat/core/activity/commons/TimeRange.java index 3e014c9..bb1c008 100644 --- a/core/src/main/java/tech/illuin/wombat/core/activity/commons/TimeRange.java +++ b/core/src/main/java/tech/illuin/wombat/core/activity/commons/TimeRange.java @@ -1,7 +1,6 @@ package tech.illuin.wombat.core.activity.commons; import com.fasterxml.jackson.annotation.JsonIgnore; -import com.fasterxml.jackson.annotation.JsonProperty; import tech.illuin.wombat.core.activity.commons.validation.ValidTimeRange; import java.time.Duration; @@ -15,9 +14,9 @@ @ValidTimeRange public record TimeRange( - @JsonProperty("start") Instant start, - @JsonProperty("end") Instant end, - @JsonProperty("resolution") Duration resolution + Instant start, + Instant end, + Duration resolution ) { public TimeRange { diff --git a/core/src/main/java/tech/illuin/wombat/core/asset/AssetIdentity.java b/core/src/main/java/tech/illuin/wombat/core/asset/AssetIdentity.java index 7458952..51740af 100644 --- a/core/src/main/java/tech/illuin/wombat/core/asset/AssetIdentity.java +++ b/core/src/main/java/tech/illuin/wombat/core/asset/AssetIdentity.java @@ -3,6 +3,7 @@ import com.fasterxml.jackson.annotation.JsonAlias; import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.NotBlank; import tech.illuin.wombat.core.asset.type.AssetType; @@ -14,9 +15,10 @@ */ @JsonIgnoreProperties(ignoreUnknown = true) public record AssetIdentity( - @NotBlank @JsonProperty("id") String id, - @NotBlank @JsonProperty("environmentId") @JsonAlias("environment-id") String environmentId, - @NotBlank @JsonProperty("type") String assetType + @NotBlank @JsonPropertyDescription("Unique identifier of the asset") String id, + // The kebab-case @JsonAlias read assets persisted before 0.15, when properties were named that way + @NotBlank @JsonPropertyDescription("Identifier of the asset's environment") @JsonAlias("environment-id") String environmentId, + @NotBlank @JsonPropertyDescription("Name of the asset-type") @JsonProperty("type") String assetType ) { public AssetIdentity { diff --git a/core/src/main/java/tech/illuin/wombat/core/asset/profile/Lifetime.java b/core/src/main/java/tech/illuin/wombat/core/asset/profile/Lifetime.java index 581f396..3504a8f 100644 --- a/core/src/main/java/tech/illuin/wombat/core/asset/profile/Lifetime.java +++ b/core/src/main/java/tech/illuin/wombat/core/asset/profile/Lifetime.java @@ -1,5 +1,6 @@ package tech.illuin.wombat.core.asset.profile; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonCreator; import com.fasterxml.jackson.annotation.JsonValue; @@ -7,6 +8,7 @@ import java.util.regex.Matcher; import java.util.regex.Pattern; +@JsonClassDescription("Duration as an amount and a unit suffix: h (hours), d (days), m (months), y (years), e.g. 5y; a bare amount is in hours") public record Lifetime( long value, Unit unit diff --git a/core/src/main/java/tech/illuin/wombat/core/asset/type/AssetType.java b/core/src/main/java/tech/illuin/wombat/core/asset/type/AssetType.java index 4797451..f3d20f6 100644 --- a/core/src/main/java/tech/illuin/wombat/core/asset/type/AssetType.java +++ b/core/src/main/java/tech/illuin/wombat/core/asset/type/AssetType.java @@ -9,10 +9,10 @@ @JsonIgnoreProperties(ignoreUnknown = true) public record AssetType( - @NotBlank @JsonProperty("namespace") String namespace, - @NotBlank @JsonProperty("localName") String localName, - @NotNull @JsonProperty("regime") ActivityRegime regime, - @NotNull @JsonProperty("family") ServiceFamily family + @NotBlank String namespace, + @NotBlank String localName, + @NotNull ActivityRegime regime, + @NotNull ServiceFamily family ) { public AssetType { diff --git a/core/src/main/java/tech/illuin/wombat/core/connector/boavizta/impact/BoaviztaEvaluationResolver.java b/core/src/main/java/tech/illuin/wombat/core/connector/boavizta/impact/BoaviztaEvaluationResolver.java index 7251a55..7b12e4f 100644 --- a/core/src/main/java/tech/illuin/wombat/core/connector/boavizta/impact/BoaviztaEvaluationResolver.java +++ b/core/src/main/java/tech/illuin/wombat/core/connector/boavizta/impact/BoaviztaEvaluationResolver.java @@ -3,6 +3,7 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; import tech.illuin.wombat.core.activity.commons.ActivityData; +import tech.illuin.wombat.core.activity.commons.Country; import tech.illuin.wombat.core.activity.commons.TimeRange; import tech.illuin.wombat.core.asset.Asset; import tech.illuin.wombat.core.asset.profile.ServerProvider; @@ -31,6 +32,8 @@ public class BoaviztaEvaluationResolver implements WombatEvaluationResolver private static final double NANOCORES_PER_CORE = 1_000_000_000.0; private static final double FULL_LOAD = 100.0; + /** Boavizta's world average, ISO 3166 having no code for the world. */ + private static final String WORLD_LOCATION = "WOR"; private static final String rebalanceWarning = "This usage has been rebalanced by the Wombat service, it does not come from the Boavizta API"; private static final String timeProrationWarning = "This impact has been prorated to the requested time range by the Wombat service"; @@ -178,7 +181,7 @@ private BoaviztaImpactResponse requestImpactFromPercentage(ServerProfile profile new BoaviztaInstanceImpactRequest( getProvider(profile.provider()), profile.instanceType(), - new BoaviztaInstanceImpactRequest.Usage(profile.location().alpha3(), List.of(new BoaviztaInstanceImpactRequest.Usage.LoadSegment(100, loadPercentage))) + new BoaviztaInstanceImpactRequest.Usage(getLocation(profile.location()), List.of(new BoaviztaInstanceImpactRequest.Usage.LoadSegment(100, loadPercentage))) ), (int) profile.lifespan().asHours() ); @@ -301,5 +304,10 @@ private static BoaviztaServerProvider getProvider(ServerProvider provider) .orElseThrow(() -> new IllegalArgumentException("Unsupported Server provider: " + provider)); } + private static String getLocation(Country location) + { + return location == Country.WORLD ? WORLD_LOCATION : location.alpha3(); + } + private record Share(String serviceId, double share) {} } diff --git a/core/src/main/java/tech/illuin/wombat/core/connector/ecologits/impact/EcologitsEvaluationResolver.java b/core/src/main/java/tech/illuin/wombat/core/connector/ecologits/impact/EcologitsEvaluationResolver.java index 129501c..84de1e1 100644 --- a/core/src/main/java/tech/illuin/wombat/core/connector/ecologits/impact/EcologitsEvaluationResolver.java +++ b/core/src/main/java/tech/illuin/wombat/core/connector/ecologits/impact/EcologitsEvaluationResolver.java @@ -27,6 +27,8 @@ public class EcologitsEvaluationResolver implements WombatEvaluationResolver { private final EcologitsClient client; + /** Ecologits' world electricity mix, ISO 3166 having no code for the world. */ + private static final String WORLD_ZONE = "WOR"; private static final Logger logger = LoggerFactory.getLogger(EcologitsEvaluationResolver.class); public EcologitsEvaluationResolver(EcologitsClient client) @@ -127,11 +129,16 @@ private EcologitsEstimationResponse estimate(LLMProvider provider, String model, ecologitsProvider, model, outputTokenCount, - location.alpha3() + electricityMixZone(location) ); return this.client.estimate(request); } + private static String electricityMixZone(Country location) + { + return location == Country.WORLD ? WORLD_ZONE : location.alpha3(); + } + private static boolean validate(EcologitsEstimationResponse response) { if (response == null || response.impacts() == null) diff --git a/core/src/main/java/tech/illuin/wombat/core/secret/SecretKey.java b/core/src/main/java/tech/illuin/wombat/core/secret/SecretKey.java new file mode 100644 index 0000000..11cdc2f --- /dev/null +++ b/core/src/main/java/tech/illuin/wombat/core/secret/SecretKey.java @@ -0,0 +1,35 @@ +package tech.illuin.wombat.core.secret; + +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonValue; + +import java.util.Objects; + +/** + * The name under which a secret is bound in a {@link SecretResolver}, never its value: it is safe to store, log and + * review. Assets declare their credentials with this type rather than a plain string, so tools reading their shape + * (e.g. a JSON schema) can tell a secret reference apart from any other text. + */ +@JsonClassDescription("Name of a secret, resolved by the configured secret resolver") +public record SecretKey(@JsonValue String value) +{ + public SecretKey + { + Objects.requireNonNull(value, "value cannot be null"); + if (value.isBlank()) + throw new IllegalArgumentException("value cannot be null or blank"); + } + + /** + * @return the key named {@code value}, {@code null} when it is null or blank: such a value names no secret, which + * lets a templated configuration leave an optional key empty + */ + @JsonCreator(mode = JsonCreator.Mode.DELEGATING) + public static SecretKey of(String value) + { + if (value == null || value.isBlank()) + return null; + return new SecretKey(value); + } +} diff --git a/core/src/main/java/tech/illuin/wombat/core/source/Period.java b/core/src/main/java/tech/illuin/wombat/core/source/Period.java index 42f3417..bb9857a 100644 --- a/core/src/main/java/tech/illuin/wombat/core/source/Period.java +++ b/core/src/main/java/tech/illuin/wombat/core/source/Period.java @@ -1,5 +1,6 @@ package tech.illuin.wombat.core.source; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonCreator; import com.fasterxml.jackson.annotation.JsonValue; @@ -13,6 +14,7 @@ * @param value * @param unit */ +@JsonClassDescription("Duration as an amount and a unit suffix: s (seconds), m (minutes), h (hours), e.g. 5m") public record Period( long value, Unit unit diff --git a/core/src/test/java/tech/illuin/wombat/core/activity/commons/CountryTest.java b/core/src/test/java/tech/illuin/wombat/core/activity/commons/CountryTest.java index b979e57..debc1fc 100644 --- a/core/src/test/java/tech/illuin/wombat/core/activity/commons/CountryTest.java +++ b/core/src/test/java/tech/illuin/wombat/core/activity/commons/CountryTest.java @@ -1,10 +1,13 @@ package tech.illuin.wombat.core.activity.commons; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.json.JsonMapper; import org.junit.jupiter.api.Test; import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.CsvSource; import org.junit.jupiter.params.provider.ValueSource; +import java.util.List; import java.util.Locale; import static org.junit.jupiter.api.Assertions.*; @@ -121,4 +124,37 @@ void testAllISOCountriesIndexed() assertSame(country, fromAlpha3); } } + + @Test + void testValuesListsEveryCountryOnceByAlpha3() + { + List values = Country.values(); + + assertEquals(Locale.getISOCountries().length + 1, values.size()); + assertTrue(values.contains(Country.FRANCE)); + assertTrue(values.contains(Country.WORLD)); + assertEquals(values.stream().map(Country::alpha3).sorted().toList(), values.stream().map(Country::alpha3).toList()); + assertThrows(UnsupportedOperationException.class, () -> values.add(Country.FRANCE)); + } + + @Test + void testWorldHasItsOwnCodesAndName() + { + assertEquals("XX", Country.WORLD.alpha2()); + assertEquals("XXX", Country.WORLD.alpha3()); + assertEquals("World", Country.WORLD.displayName()); + assertEquals("World", Country.WORLD.displayName(Locale.FRENCH)); + assertSame(Country.WORLD, Country.ofAlpha3("XXX")); + assertSame(Country.WORLD, Country.ofCode("XX").orElseThrow()); + } + + @Test + void testJsonRoundTripIncludingWorld() throws Exception + { + ObjectMapper mapper = JsonMapper.builder().build(); + + assertEquals("\"XXX\"", mapper.writeValueAsString(Country.WORLD)); + for (Country country : Country.values()) + assertSame(country, mapper.readValue(mapper.writeValueAsString(country), Country.class)); + } } diff --git a/core/src/test/java/tech/illuin/wombat/core/connector/boavizta/impact/BoaviztaEvaluationResolverTest.java b/core/src/test/java/tech/illuin/wombat/core/connector/boavizta/impact/BoaviztaEvaluationResolverTest.java index e3fc478..542b3fe 100644 --- a/core/src/test/java/tech/illuin/wombat/core/connector/boavizta/impact/BoaviztaEvaluationResolverTest.java +++ b/core/src/test/java/tech/illuin/wombat/core/connector/boavizta/impact/BoaviztaEvaluationResolverTest.java @@ -118,6 +118,26 @@ void resolve_relativeUsage_scalesSingleNodeEmissionsByNodeCount() throws Excepti assertEquals(3, k8sImpact.nodeCount()); } + /** ISO 3166 has no code for the world, Boavizta names it WOR. */ + @Test + void resolve_worldLocation_requestsTheWorldAverage() throws Exception + { + BoaviztaClient client = mock(BoaviztaClient.class); + BoaviztaEvaluationResolver evalResolver = new BoaviztaEvaluationResolver(client); + + when(client.getInstanceConfig(eq(BoaviztaServerProvider.aws), eq("c5a.4xlarge"))) + .thenReturn(new BoaviztaInstanceConfigResponse(new BoaviztaInstanceConfigResponse.IntConfigItem(16), null, null, null, null, null)); + when(client.getInstanceImpact(eq(true), anyInt(), anySet(), any(BoaviztaInstanceImpactRequest.class))) + .thenReturn(new BoaviztaImpactResponse(Map.of(), 0)); + + TestAsset asset = new TestAsset(K8S_TYPE, new TestServerProfile(ServerProvider.aws, "c5a.4xlarge", Country.WORLD, Lifetime.ofHours(1000), 1)); + TimeRange range = new TimeRange(Instant.parse("2026-11-01T00:00:00Z"), Instant.parse("2026-11-01T01:00:00Z"), Duration.ofHours(1)); + evalResolver.resolve(asset, new KubernetesActivityData(ActivityRegime.MODELED, Set.of("srv-1"), range, CPUUsage.relative(0.50), Map.of("srv-1", 1.0), Map.of())); + + verify(client, atLeastOnce()).getInstanceImpact(eq(true), anyInt(), anySet(), argThat(request -> "WOR".equals(request.usage().usageLocation()))); + verify(client, never()).getInstanceImpact(eq(true), anyInt(), anySet(), argThat(request -> !"WOR".equals(request.usage().usageLocation()))); + } + private record TestServerProfile( ServerProvider provider, String instanceType, diff --git a/core/src/test/java/tech/illuin/wombat/core/connector/ecologits/impact/EcologitsEvaluationResolverTest.java b/core/src/test/java/tech/illuin/wombat/core/connector/ecologits/impact/EcologitsEvaluationResolverTest.java index e9d110a..f58c023 100644 --- a/core/src/test/java/tech/illuin/wombat/core/connector/ecologits/impact/EcologitsEvaluationResolverTest.java +++ b/core/src/test/java/tech/illuin/wombat/core/connector/ecologits/impact/EcologitsEvaluationResolverTest.java @@ -14,12 +14,15 @@ import tech.illuin.wombat.core.asset.type.AssetType; import tech.illuin.wombat.core.asset.type.ServiceFamily; import tech.illuin.wombat.core.connector.ecologits.connector.EcologitsClient; +import tech.illuin.wombat.core.connector.ecologits.connector.model.EcologitsEstimationRequest; import tech.illuin.wombat.core.connector.ecologits.connector.model.EcologitsEstimationResponse; import tech.illuin.wombat.core.evaluation.AssetEvaluation; import tech.illuin.wombat.core.evaluation.impact.commons.AssetImpact; import tech.illuin.wombat.core.evaluation.impact.llm.LLMImpact; import java.time.Instant; +import java.util.ArrayList; +import java.util.List; import java.util.Map; import java.util.Set; @@ -98,6 +101,24 @@ void resolve_multiServiceActivity_calculatesSharesAndAggregatesFootprint() throw assertEquals(expectedGwp, impact.footprint().gwp().totalValue(), 1e-4); } + /** ISO 3166 has no code for the world, Ecologits names its electricity mix WOR. */ + @Test + void resolve_worldLocation_requestsTheWorldElectricityMix() throws Exception + { + List requests = new ArrayList<>(); + EcologitsEvaluationResolver capturing = new EcologitsEvaluationResolver(req -> { + requests.add(req); + return dummyResponse(req.outputTokenCount()); + }); + + TestAsset asset = new TestAsset(LLM_TYPE, new TestLLMProfile(LLMProvider.google_genai, "gemini-2.5-pro", Country.WORLD)); + LLMServiceActivity service = new LLMServiceActivity(LLMProvider.google_genai, "gemini-2.5-pro", Country.WORLD, 1000L, 10.0); + TimeRange range = new TimeRange(Instant.ofEpochMilli(0), Instant.ofEpochMilli(1000)); + capturing.resolve(asset, new LLMActivityData(ActivityRegime.MEASURED, Set.of("gemini-2.5-pro"), range, Map.of("gemini-2.5-pro", service))); + + assertEquals(List.of("WOR"), requests.stream().map(EcologitsEstimationRequest::electricityMixZone).toList()); + } + private static EcologitsEstimationResponse dummyResponse(double value) { EcologitsEstimationResponse.Metric gwp = new EcologitsEstimationResponse.Metric("gwp", "GWP", EcologitsEstimationResponse.Metric.EcologitsRange.of(value), "kgCO2eq"); diff --git a/core/src/test/java/tech/illuin/wombat/core/secret/SecretKeyTest.java b/core/src/test/java/tech/illuin/wombat/core/secret/SecretKeyTest.java new file mode 100644 index 0000000..66c7905 --- /dev/null +++ b/core/src/test/java/tech/illuin/wombat/core/secret/SecretKeyTest.java @@ -0,0 +1,39 @@ +package tech.illuin.wombat.core.secret; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.json.JsonMapper; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; + +class SecretKeyTest +{ + private final ObjectMapper mapper = JsonMapper.builder().build(); + + @Test + void isWrittenAndReadAsAPlainString() throws Exception + { + SecretKey key = SecretKey.of("API_KEY"); + + assertEquals("\"API_KEY\"", this.mapper.writeValueAsString(key)); + assertEquals(key, this.mapper.readValue("\"API_KEY\"", SecretKey.class)); + } + + @Test + void aBlankValueNamesNoKey() throws Exception + { + assertNull(SecretKey.of(null)); + assertNull(SecretKey.of(" ")); + assertNull(this.mapper.readValue("\"\"", SecretKey.class)); + assertNull(this.mapper.readValue("null", SecretKey.class)); + } + + @Test + void cannotBeBuiltBlank() + { + assertThrows(NullPointerException.class, () -> new SecretKey(null)); + assertThrows(IllegalArgumentException.class, () -> new SecretKey(" ")); + } +} diff --git a/doc/module/llm-vertexai.md b/doc/module/llm-vertexai.md index f19f06f..930cd5f 100644 --- a/doc/module/llm-vertexai.md +++ b/doc/module/llm-vertexai.md @@ -46,7 +46,7 @@ id: "vertex-gemini-flash" # required - Unique identifier for the asset. environment-id: "production" # required - Identifier of the environment (e.g. `production`, `staging`). google-url: "https://monitoring.googleapis.com" # `String`, Required - Base URL of the Cloud Monitoring API. resource-name: "projects/my-gcp-project" # `String`, Required - projects/, folders/, or organizations/. -credentials-key: "secrets.google.service-account" # `String`, Optional(default: null) - Secret resolver key for a service-account JSON key. Falls back to Application Default Credentials when omitted. +credentials-key: "secrets.google.service-account" # `SecretKey`, Optional(default: null) - Secret resolver key for a service-account JSON key. Falls back to Application Default Credentials when omitted. proxy-url: "http://proxy.corp.internal:8080" # optional (default: null) - HTTP corporate proxy URL; must include a host and a port. profile: # `LLMVertexAIProfile`, Required - LLM profile and Cloud Monitoring query configuration. models: # optional (default: all models) - Restricts the usage report to these model identifiers. diff --git a/doc/type-glossary.md b/doc/type-glossary.md index 884bb88..b7d4b37 100644 --- a/doc/type-glossary.md +++ b/doc/type-glossary.md @@ -2,6 +2,8 @@ This document serves as a reference for generic domain types, structures, enums, and data formats used across `wombat-core` and core module configurations. +Property names follow the format: configuration files (YAML) are written in kebab-case (e.g. `instance-type`), and JSON payloads (e.g. the API) in camelCase (e.g. `instanceType`). + ## 1. Core Identity Types ### `ServiceFamily` @@ -32,6 +34,13 @@ It is currently composed of the following properties: - the asset `environmentId` - the asset `type`, see [`AssetType`](#assettype) +### `SecretKey` + +The name under which a credential is bound in the configured secret resolver (e.g. an environment variable), never the credential itself: it is safe to store, log and review. + +- **Format**: a non-blank string (e.g. `secrets.anthropic.admin-key`); an empty value means no secret, for optional keys. +- **Usage**: Used by assets requiring credentials, such as the `admin-key` of an Anthropic asset or the `password-key` of a Prometheus asset. + ## 2. Temporal & Time Types ### `TimeRange` @@ -88,6 +97,7 @@ Operational hardware lifespan of server equipment, serialized as a duration stri Geographical country location code, adhering to ISO 3166-1 alpha-3 (or alpha-2). - **Format**: 3-letter (or 2-letter) country code (e.g. `FRA`, `USA`, `DEU`, `SWE`, `GBR`, `IRL`). +- **World**: `XXX` stands for the world as a whole. - **Usage**: Used in server and cloud asset profiles to resolve localized carbon intensity factors (grid emissions). ### `ServerProvider` diff --git a/module/pom.xml b/module/pom.xml index 468cf77..aaf90e6 100644 --- a/module/pom.xml +++ b/module/pom.xml @@ -52,6 +52,20 @@ test + + com.fasterxml.jackson.datatype + jackson-datatype-jdk8 + ${jackson.version} + test + + + + com.fasterxml.jackson.dataformat + jackson-dataformat-yaml + ${jackson.version} + test + + io.fabric8 kubernetes-client diff --git a/module/src/main/java/tech/illuin/wombat/module/kubernetes_api/KubernetesAPIAsset.java b/module/src/main/java/tech/illuin/wombat/module/kubernetes_api/KubernetesAPIAsset.java index 70e0cd0..c93b8d4 100644 --- a/module/src/main/java/tech/illuin/wombat/module/kubernetes_api/KubernetesAPIAsset.java +++ b/module/src/main/java/tech/illuin/wombat/module/kubernetes_api/KubernetesAPIAsset.java @@ -1,7 +1,8 @@ package tech.illuin.wombat.module.kubernetes_api; import com.fasterxml.jackson.annotation.JsonAlias; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import com.fasterxml.jackson.annotation.JsonUnwrapped; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; @@ -14,14 +15,16 @@ import java.time.Duration; import java.util.Optional; +@JsonClassDescription("Kubernetes cluster whose container CPU usage is polled from its API") public record KubernetesAPIAsset( @JsonUnwrapped AssetIdentity identity, - @NotBlank @JsonProperty("configPath") @JsonAlias("config-path") String configPath, - @JsonProperty("namespace") String namespace, - @JsonProperty("context") Optional context, - @JsonProperty("readTimeout") @JsonAlias("read-timeout") Optional readTimeout, - @JsonProperty("period") Period period, - @NotNull @JsonProperty("profile") KubernetesAPIServerProfile profile + // The kebab-case @JsonAlias read assets persisted before 0.15, when properties were named that way + @NotBlank @JsonPropertyDescription("Path to the kubeconfig file") @JsonAlias("config-path") String configPath, + @JsonPropertyDescription("Namespace to poll, all namespaces when omitted") String namespace, + @JsonPropertyDescription("Kubeconfig context to target, the active one when omitted") Optional context, + @JsonPropertyDescription("Read timeout of the Kubernetes API requests (ISO-8601), the client's default when omitted") @JsonAlias("read-timeout") Optional readTimeout, + @JsonPropertyDescription("Polling interval, the monitor's default when omitted") Period period, + @NotNull @JsonPropertyDescription("Server hardware profile") KubernetesAPIServerProfile profile ) implements Asset, Monitorable { @Override diff --git a/module/src/main/java/tech/illuin/wombat/module/kubernetes_api/KubernetesAPIServerProfile.java b/module/src/main/java/tech/illuin/wombat/module/kubernetes_api/KubernetesAPIServerProfile.java index 1fea0bb..3f1f5ab 100644 --- a/module/src/main/java/tech/illuin/wombat/module/kubernetes_api/KubernetesAPIServerProfile.java +++ b/module/src/main/java/tech/illuin/wombat/module/kubernetes_api/KubernetesAPIServerProfile.java @@ -1,7 +1,8 @@ package tech.illuin.wombat.module.kubernetes_api; import com.fasterxml.jackson.annotation.JsonAlias; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; import tech.illuin.wombat.core.activity.commons.Country; @@ -9,9 +10,11 @@ import tech.illuin.wombat.core.asset.profile.ServerProfile; import tech.illuin.wombat.core.asset.profile.ServerProvider; +@JsonClassDescription("Hardware of the cluster's nodes") public record KubernetesAPIServerProfile( - @NotNull @JsonProperty("provider") ServerProvider provider, - @NotBlank @JsonProperty("instanceType") @JsonAlias("instance-type") String instanceType, - @NotNull @JsonProperty("location") Country location, - @NotNull @JsonProperty("lifespan") Lifetime lifespan + @NotNull @JsonPropertyDescription("Infrastructure provider") ServerProvider provider, + // The kebab-case @JsonAlias read assets persisted before 0.15, when properties were named that way + @NotBlank @JsonPropertyDescription("Instance type of the nodes, e.g. m5.xlarge or n2-standard-4") @JsonAlias("instance-type") String instanceType, + @NotNull @JsonPropertyDescription("Country hosting the nodes") Country location, + @NotNull @JsonPropertyDescription("Expected operational lifespan of the hardware") Lifetime lifespan ) implements ServerProfile {} diff --git a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticAsset.java b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticAsset.java index db84a12..48dfb4b 100644 --- a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticAsset.java +++ b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticAsset.java @@ -1,15 +1,17 @@ package tech.illuin.wombat.module.kubernetes_static; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import com.fasterxml.jackson.annotation.JsonUnwrapped; import jakarta.validation.constraints.NotNull; import tech.illuin.wombat.core.asset.Asset; import tech.illuin.wombat.core.asset.AssetIdentity; import tech.illuin.wombat.core.asset.type.AssetType; +@JsonClassDescription("Kubernetes cluster whose load is modeled from static scenarios") public record KubernetesStaticAsset( @JsonUnwrapped AssetIdentity identity, - @NotNull @JsonProperty("profile") KubernetesStaticProfile profile + @NotNull @JsonPropertyDescription("Server hardware profile and load scenarios") KubernetesStaticProfile profile ) implements Asset { @Override diff --git a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticProfile.java b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticProfile.java index 3fb987d..c198198 100644 --- a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticProfile.java +++ b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticProfile.java @@ -1,7 +1,8 @@ package tech.illuin.wombat.module.kubernetes_static; -import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.Valid; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotEmpty; @@ -17,14 +18,15 @@ import java.time.ZoneOffset; import java.util.List; +@JsonClassDescription("Hardware of the cluster's nodes and their modeled load") public record KubernetesStaticProfile( - @NotNull @JsonProperty("provider") ServerProvider provider, - @NotBlank @JsonProperty("instanceType") @JsonAlias("instance-type") String instanceType, - @NotNull @JsonProperty("location") Country location, - @NotNull @JsonProperty("lifespan") Lifetime lifespan, - @Positive @JsonProperty("nodeCount") @JsonAlias("node-count") int nodeCount, - @JsonProperty("zoneId") @JsonAlias("zone-id") ZoneId zoneId, - @NotNull @NotEmpty @JsonProperty("scenarios") List<@Valid Scenario> scenarios + @NotNull @JsonPropertyDescription("Infrastructure provider") ServerProvider provider, + @NotBlank @JsonPropertyDescription("Instance type of the nodes, e.g. c5.2xlarge or n2-standard-8") String instanceType, + @NotNull @JsonPropertyDescription("Country hosting the nodes") Country location, + @NotNull @JsonPropertyDescription("Expected operational lifespan of the hardware") Lifetime lifespan, + @Positive @JsonProperty(defaultValue = "1") @JsonPropertyDescription("Number of identical nodes") int nodeCount, + @JsonProperty(defaultValue = "UTC") @JsonPropertyDescription("Time zone the scenarios' times are evaluated in, e.g. Europe/Paris") ZoneId zoneId, + @NotNull @NotEmpty @JsonPropertyDescription("Superposed load scenarios") List<@Valid Scenario> scenarios ) implements ServerProfile { public KubernetesStaticProfile diff --git a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/BatchActivityScenario.java b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/BatchActivityScenario.java index a3bde90..75bffd7 100644 --- a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/BatchActivityScenario.java +++ b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/BatchActivityScenario.java @@ -1,7 +1,8 @@ package tech.illuin.wombat.module.kubernetes_static.scenario; -import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.NotNull; import jakarta.validation.constraints.PositiveOrZero; import tech.illuin.wombat.module.kubernetes_static.scenario.tools.ApplicabilityFilter; @@ -17,23 +18,16 @@ * Models scheduled batch workload activity with trigger time, duration, and optional smoothing, * with baseline and peak load expressed as fractions of 100% server capacity * (e.g. {@code 0.0} baseline, {@code 0.90} peak batch load). - * - * @param baselineLoad fraction of server capacity outside batch window (>= 0.0) - * @param peakLoad fraction of server capacity during batch execution (>= 0.0) - * @param triggerTime daily start time of batch job - * @param duration active execution duration - * @param jitter deterministic variance factor (e.g. 0.05 for +-5%) - * @param smoothing transition smoothing mode (none, linear ramp, smooth step) - * @param applicability optional applicability filter */ +@JsonClassDescription("Load of a scheduled daily batch job") public record BatchActivityScenario( - @PositiveOrZero @JsonProperty("baselineLoad") @JsonAlias("baseline-load") double baselineLoad, - @PositiveOrZero @JsonProperty("peakLoad") @JsonAlias("peak-load") double peakLoad, - @NotNull @JsonProperty("triggerTime") @JsonAlias("trigger-time") LocalTime triggerTime, - @NotNull @JsonProperty("duration") Duration duration, - @JsonProperty("jitter") double jitter, - @JsonProperty("smoothing") SmoothingMode smoothing, - @JsonProperty("applicability") ApplicabilityFilter applicability + @PositiveOrZero @JsonPropertyDescription("Fraction of the server capacity outside the batch window") double baselineLoad, + @PositiveOrZero @JsonPropertyDescription("Fraction of the server capacity during the batch window") double peakLoad, + @NotNull @JsonPropertyDescription("Daily start time of the batch job") LocalTime triggerTime, + @NotNull @JsonPropertyDescription("Duration of the batch job (ISO-8601)") Duration duration, + @JsonProperty(defaultValue = "0") @JsonPropertyDescription("Deterministic variance factor, e.g. 0.05 for +-5%") double jitter, + @JsonProperty(defaultValue = "none") @JsonPropertyDescription("Smoothing of the transitions at both ends of the batch window") SmoothingMode smoothing, + @JsonPropertyDescription("Days and months the scenario applies to, always when omitted") ApplicabilityFilter applicability ) implements Scenario { public static final SmoothingMode DEFAULT_SMOOTHING = SmoothingMode.NONE; diff --git a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/ConstantScenario.java b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/ConstantScenario.java index 3cba75e..f693c87 100644 --- a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/ConstantScenario.java +++ b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/ConstantScenario.java @@ -1,6 +1,7 @@ package tech.illuin.wombat.module.kubernetes_static.scenario; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.PositiveOrZero; import tech.illuin.wombat.module.kubernetes_static.scenario.tools.ApplicabilityFilter; @@ -9,13 +10,11 @@ /** * Models a constant baseline load factor expressed as a fraction of 100% server capacity * (e.g. {@code 0.10} for 10% load, {@code 1.0} for 100% capacity). - * - * @param load fraction of server capacity (>= 0.0) - * @param applicability optional applicability filter */ +@JsonClassDescription("Constant load") public record ConstantScenario( - @PositiveOrZero @JsonProperty("load") double load, - @JsonProperty("applicability") ApplicabilityFilter applicability + @PositiveOrZero @JsonPropertyDescription("Fraction of the server capacity, e.g. 0.20 for 20%") double load, + @JsonPropertyDescription("Days and months the scenario applies to, always when omitted") ApplicabilityFilter applicability ) implements Scenario { public ConstantScenario diff --git a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/UserActivityScenario.java b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/UserActivityScenario.java index ee34dac..0fdb202 100644 --- a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/UserActivityScenario.java +++ b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/UserActivityScenario.java @@ -1,7 +1,8 @@ package tech.illuin.wombat.module.kubernetes_static.scenario; -import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.NotNull; import jakarta.validation.constraints.PositiveOrZero; import tech.illuin.wombat.module.kubernetes_static.scenario.tools.ApplicabilityFilter; @@ -15,23 +16,16 @@ * Models user activity between opening and closing times with configurable curve shape, * with baseline and peak load expressed as fractions of 100% server capacity * (e.g. {@code 0.10} baseline, {@code 0.75} peak diurnal load). - * - * @param baselineLoad fraction of server capacity during off-hours (>= 0.0) - * @param peakLoad fraction of server capacity at peak hours (>= 0.0) - * @param openingTime start time of user activity window - * @param closingTime end time of user activity window - * @param curve mathematical curve profile (sinusoidal, trapezoidal, bell) - * @param jitter deterministic variance factor (e.g. 0.05 for +-5%) - * @param applicability optional applicability filter */ +@JsonClassDescription("Load following user activity over a daily window") public record UserActivityScenario( - @PositiveOrZero @JsonProperty("baselineLoad") @JsonAlias("baseline-load") double baselineLoad, - @PositiveOrZero @JsonProperty("peakLoad") @JsonAlias("peak-load") double peakLoad, - @NotNull @JsonProperty("openingTime") @JsonAlias("opening-time") LocalTime openingTime, - @NotNull @JsonProperty("closingTime") @JsonAlias("closing-time") LocalTime closingTime, - @JsonProperty("curve") CurveShape curve, - @JsonProperty("jitter") double jitter, - @JsonProperty("applicability") ApplicabilityFilter applicability + @PositiveOrZero @JsonPropertyDescription("Fraction of the server capacity during off-hours") double baselineLoad, + @PositiveOrZero @JsonPropertyDescription("Fraction of the server capacity at peak hours") double peakLoad, + @NotNull @JsonPropertyDescription("Start of the daily activity window") LocalTime openingTime, + @NotNull @JsonPropertyDescription("End of the daily activity window") LocalTime closingTime, + @JsonProperty(defaultValue = "bell") @JsonPropertyDescription("Shape of the activity over the window") CurveShape curve, + @JsonProperty(defaultValue = "0") @JsonPropertyDescription("Deterministic variance factor, e.g. 0.05 for +-5%") double jitter, + @JsonPropertyDescription("Days and months the scenario applies to, always when omitted") ApplicabilityFilter applicability ) implements Scenario { public static final CurveShape DEFAULT_CURVE = CurveShape.BELL; diff --git a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/tools/ApplicabilityFilter.java b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/tools/ApplicabilityFilter.java index 7ac189a..4d4c044 100644 --- a/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/tools/ApplicabilityFilter.java +++ b/module/src/main/java/tech/illuin/wombat/module/kubernetes_static/scenario/tools/ApplicabilityFilter.java @@ -1,15 +1,17 @@ package tech.illuin.wombat.module.kubernetes_static.scenario.tools; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import java.time.DayOfWeek; import java.time.Month; import java.time.ZonedDateTime; import java.util.Set; +@JsonClassDescription("Days and months a scenario applies to") public record ApplicabilityFilter( - @JsonProperty("daysOfWeek") Set daysOfWeek, - @JsonProperty("months") Set months + @JsonPropertyDescription("Days of the week the scenario applies to, every day when empty") Set daysOfWeek, + @JsonPropertyDescription("Months the scenario applies to, every month when empty") Set months ) { public static final ApplicabilityFilter ALWAYS = new ApplicabilityFilter(Set.of(), Set.of()); diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicAsset.java b/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicAsset.java index 114ed80..895f415 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicAsset.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicAsset.java @@ -1,23 +1,25 @@ package tech.illuin.wombat.module.llm_anthropic; -import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import com.fasterxml.jackson.annotation.JsonUnwrapped; -import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; import tech.illuin.wombat.core.asset.Asset; import tech.illuin.wombat.core.asset.AssetIdentity; import tech.illuin.wombat.core.asset.type.AssetType; import tech.illuin.wombat.core.secret.SecretAware; +import tech.illuin.wombat.core.secret.SecretKey; import java.util.Set; +@JsonClassDescription("Anthropic organization whose usage is read from the Admin API usage report") public record LLMAnthropicAsset( @JsonUnwrapped AssetIdentity identity, - @JsonProperty("apiUrl") @JsonAlias("api-url") String apiUrl, - @JsonProperty("proxyUrl") @JsonAlias("proxy-url") String proxyUrl, - @NotBlank @JsonProperty("adminKey") @JsonAlias("admin-key") String adminKey, - @NotNull @JsonProperty("profile") LLMAnthropicProfile profile + @JsonProperty(defaultValue = LLMAnthropicAsset.DEFAULT_API_URL) @JsonPropertyDescription("Base URL of the Anthropic API") String apiUrl, + @JsonPropertyDescription("HTTP proxy URL, with a host and a port") String proxyUrl, + @NotNull @JsonPropertyDescription("Secret holding an Anthropic Admin API key (sk-ant-admin...); a standard API key is rejected") SecretKey adminKey, + @NotNull @JsonPropertyDescription("Usage scope and request estimation") LLMAnthropicProfile profile ) implements Asset, SecretAware { public static final String DEFAULT_API_URL = "https://api.anthropic.com"; @@ -31,10 +33,10 @@ public AssetType type() @Override public Set requiredSecretKeys() { - if (this.adminKey == null || this.adminKey.isBlank()) + if (this.adminKey == null) throw new IllegalStateException("Asset " + this.identity.id() + " declares no adminKey"); - return Set.of(this.adminKey); + return Set.of(this.adminKey.value()); } public String resolvedApiUrl() diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicProfile.java b/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicProfile.java index 83b5c61..bb687fc 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicProfile.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicProfile.java @@ -1,19 +1,21 @@ package tech.illuin.wombat.module.llm_anthropic; -import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.Positive; import tech.illuin.wombat.core.activity.commons.Country; import tech.illuin.wombat.core.asset.profile.LLMProfile; import java.util.List; +@JsonClassDescription("Scope of the usage report and request estimation") public record LLMAnthropicProfile( - @JsonProperty("location") Country location, - @Positive @JsonProperty("outputTokensPerRequest") @JsonAlias("output-tokens-per-request") Integer outputTokensPerRequest, - @JsonProperty("models") List models, - @JsonProperty("workspaceIds") @JsonAlias("workspace-ids") List workspaceIds, - @JsonProperty("apiKeyIds") @JsonAlias("api-key-ids") List apiKeyIds + @JsonProperty(defaultValue = "USA") @JsonPropertyDescription("Country where inference is assumed to occur") Country location, + @Positive @JsonProperty(defaultValue = "500") @JsonPropertyDescription("Average output tokens per request, used to derive the request count") Integer outputTokensPerRequest, + @JsonPropertyDescription("Model identifiers the report is restricted to, all models when empty") List models, + @JsonPropertyDescription("Workspace identifiers the report is restricted to, includes all workspaces when empty") List workspaceIds, + @JsonPropertyDescription("API key identifiers the report is restricted to, includes all API keys when empty") List apiKeyIds ) implements LLMProfile { public LLMAnthropicProfile diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/connector/AnthropicClientConfig.java b/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/connector/AnthropicClientConfig.java index b63b4a7..3e75720 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/connector/AnthropicClientConfig.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_anthropic/connector/AnthropicClientConfig.java @@ -25,7 +25,7 @@ public static AnthropicAdminClient create(LLMAnthropicAsset properties, SecretRe { Feign.Builder builder = Feign.builder() .decoder(new JacksonDecoder()) - .requestInterceptor(new AnthropicHeadersInterceptor(secrets.require(properties.adminKey()))); + .requestInterceptor(new AnthropicHeadersInterceptor(secrets.require(properties.adminKey().value()))); if (client != null) builder.client(client); diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusAsset.java b/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusAsset.java index ea9349b..acd4ec4 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusAsset.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusAsset.java @@ -1,7 +1,8 @@ package tech.illuin.wombat.module.llm_prometheus; import com.fasterxml.jackson.annotation.JsonAlias; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import com.fasterxml.jackson.annotation.JsonUnwrapped; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; @@ -9,19 +10,22 @@ import tech.illuin.wombat.core.asset.AssetIdentity; import tech.illuin.wombat.core.asset.type.AssetType; import tech.illuin.wombat.core.secret.SecretAware; +import tech.illuin.wombat.core.secret.SecretKey; import tech.illuin.wombat.core.source.Monitorable; import tech.illuin.wombat.core.source.Period; import java.util.Set; +@JsonClassDescription("LLM serving stack whose output token volume is polled from Prometheus") public record LLMPrometheusAsset( @JsonUnwrapped AssetIdentity identity, - @NotBlank @JsonProperty("prometheusUrl") @JsonAlias("prometheus-url") String prometheusUrl, - @JsonProperty("proxyUrl") @JsonAlias("proxy-url") String proxyUrl, - @JsonProperty("username") String username, - @JsonProperty("passwordKey") @JsonAlias("password-key") String passwordKey, - @JsonProperty("period") Period period, - @NotNull @JsonProperty("profile") LLMPrometheusProfile profile + // The kebab-case @JsonAlias read assets persisted before 0.15, when properties were named that way + @NotBlank @JsonPropertyDescription("Base URL of the Prometheus server") @JsonAlias("prometheus-url") String prometheusUrl, + @JsonPropertyDescription("HTTP proxy URL, with a host and a port") @JsonAlias("proxy-url") String proxyUrl, + @JsonPropertyDescription("Basic authentication username") String username, + @JsonPropertyDescription("Secret holding the basic authentication password, required with a username") @JsonAlias("password-key") SecretKey passwordKey, + @JsonPropertyDescription("Polling interval, the monitor's default when omitted") Period period, + @NotNull @JsonPropertyDescription("LLM profile and PromQL query") LLMPrometheusProfile profile ) implements Asset, SecretAware, Monitorable { @Override @@ -35,10 +39,10 @@ public Set requiredSecretKeys() { if (!this.usesBasicAuth()) return Set.of(); - if (this.passwordKey == null || this.passwordKey.isBlank()) + if (this.passwordKey == null) throw new IllegalStateException("Asset " + this.identity.id() + " declares a Prometheus username but no password-key"); - return Set.of(this.passwordKey); + return Set.of(this.passwordKey.value()); } public boolean usesBasicAuth() diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusProfile.java b/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusProfile.java index de96b00..26193aa 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusProfile.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusProfile.java @@ -1,7 +1,8 @@ package tech.illuin.wombat.module.llm_prometheus; import com.fasterxml.jackson.annotation.JsonAlias; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.Valid; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; @@ -9,14 +10,16 @@ import tech.illuin.wombat.core.asset.profile.LLMProfile; import tech.illuin.wombat.core.asset.profile.LLMProvider; +@JsonClassDescription("Served model and the PromQL query measuring its output tokens") public record LLMPrometheusProfile( - @NotNull @JsonProperty("provider") LLMProvider provider, - @NotBlank @JsonProperty("model") String model, - @NotNull @JsonProperty("location") Country location, - @NotNull @Valid @JsonProperty("dynamicProfile") @JsonAlias("dynamic-profile") DynamicProfile dynamicProfile + @NotNull @JsonPropertyDescription("Model provider") LLMProvider provider, + @NotBlank @JsonPropertyDescription("Model identifier") String model, + @NotNull @JsonPropertyDescription("Country where inference occurs") Country location, + // The kebab-case @JsonAlias read assets persisted before 0.15, when properties were named that way + @NotNull @Valid @JsonPropertyDescription("PromQL query configuration") @JsonAlias("dynamic-profile") DynamicProfile dynamicProfile ) implements LLMProfile { public record DynamicProfile( - @NotBlank @JsonProperty("query") String query + @NotBlank @JsonPropertyDescription("PromQL query returning the output token volume over the sampling window") String query ) {} } diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/connector/PrometheusClientConfig.java b/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/connector/PrometheusClientConfig.java index 6066c8b..5548816 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/connector/PrometheusClientConfig.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_prometheus/connector/PrometheusClientConfig.java @@ -29,7 +29,7 @@ public static PrometheusClient create(LLMPrometheusAsset properties, SecretResol // require() rather than find(): a basic-auth asset whose variable is unset must fail, not silently // authenticate with a blank password. if (properties.usesBasicAuth()) - builder.requestInterceptor(new BasicAuthInterceptor(properties.username(), secrets.require(properties.passwordKey()))); + builder.requestInterceptor(new BasicAuthInterceptor(properties.username(), secrets.require(properties.passwordKey().value()))); return builder.target(PrometheusClient.class, properties.prometheusUrl()); } diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_static/LLMStaticAsset.java b/module/src/main/java/tech/illuin/wombat/module/llm_static/LLMStaticAsset.java index a2cc25b..99463f8 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_static/LLMStaticAsset.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_static/LLMStaticAsset.java @@ -1,15 +1,17 @@ package tech.illuin.wombat.module.llm_static; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import com.fasterxml.jackson.annotation.JsonUnwrapped; import jakarta.validation.constraints.NotNull; import tech.illuin.wombat.core.asset.Asset; import tech.illuin.wombat.core.asset.AssetIdentity; import tech.illuin.wombat.core.asset.type.AssetType; +@JsonClassDescription("LLM usage modeled from static scenarios") public record LLMStaticAsset( @JsonUnwrapped AssetIdentity identity, - @NotNull @JsonProperty("profile") LLMStaticProfile profile + @NotNull @JsonPropertyDescription("Models and their traffic scenarios") LLMStaticProfile profile ) implements Asset { @Override diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_static/LLMStaticProfile.java b/module/src/main/java/tech/illuin/wombat/module/llm_static/LLMStaticProfile.java index d47aff5..9454e08 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_static/LLMStaticProfile.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_static/LLMStaticProfile.java @@ -1,8 +1,9 @@ package tech.illuin.wombat.module.llm_static; -import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.Valid; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotEmpty; @@ -17,9 +18,10 @@ import java.util.List; @JsonIgnoreProperties(ignoreUnknown = true) +@JsonClassDescription("Models and their modeled traffic") public record LLMStaticProfile( - @JsonProperty("zoneId") @JsonAlias("zone-id") ZoneId zoneId, - @NotNull @NotEmpty @JsonProperty("models") List<@Valid ModelConfig> models + @JsonProperty(defaultValue = "UTC") @JsonPropertyDescription("Time zone the scenarios' times are evaluated in, e.g. Europe/Paris") ZoneId zoneId, + @NotNull @NotEmpty @JsonPropertyDescription("Models and their scenarios") List<@Valid ModelConfig> models ) implements LLMProfile { public LLMStaticProfile @@ -39,11 +41,12 @@ public LLMStaticProfile(LLMProvider provider, String model, Country location, Li } @JsonIgnoreProperties(ignoreUnknown = true) + @JsonClassDescription("Model and its superposed traffic scenarios") public record ModelConfig( - @NotNull @JsonProperty("provider") LLMProvider provider, - @NotBlank @JsonProperty("model") String model, - @NotNull @JsonProperty("location") Country location, - @NotNull @NotEmpty @JsonProperty("scenarios") List<@Valid Scenario> scenarios + @NotNull @JsonPropertyDescription("Foundation model provider") LLMProvider provider, + @NotBlank @JsonPropertyDescription("Model identifier, as listed by Ecologits") String model, + @NotNull @JsonPropertyDescription("Country where inference is assumed to occur") Country location, + @NotNull @NotEmpty @JsonPropertyDescription("Superposed traffic scenarios") List<@Valid Scenario> scenarios ) { public ModelConfig { diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/BatchActivityScenario.java b/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/BatchActivityScenario.java index a8c0aa5..83571ca 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/BatchActivityScenario.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/BatchActivityScenario.java @@ -1,8 +1,10 @@ package tech.illuin.wombat.module.llm_static.scenario; import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.NotNull; import jakarta.validation.constraints.PositiveOrZero; import tech.illuin.wombat.module.llm_static.scenario.tools.ApplicabilityFilter; @@ -17,24 +19,19 @@ /** * Models scheduled batch workload activity with trigger time, duration, and optional smoothing, * with annual request volume distributed across active batch executions. - * - * @param outputTokenPerRequest mean output token count per request (>= 0) - * @param requestPerYear total annual request volume (>= 0.0) - * @param triggerTime daily start time of batch job - * @param duration active execution duration - * @param jitter deterministic variance factor (e.g. 0.05 for +-5%) - * @param smoothing transition smoothing mode (none, linear ramp, smooth step) - * @param applicability optional applicability filter */ @JsonIgnoreProperties(ignoreUnknown = true) +@JsonClassDescription("Request volume of a scheduled daily batch job") public record BatchActivityScenario( - @PositiveOrZero @JsonProperty("outputTokenPerRequest") @JsonAlias({"output-token-per-request", "output-token-count"}) int outputTokenPerRequest, - @JsonProperty("requestPerYear") @JsonAlias({"request-per-year", "requestsPerYear", "peak-request-per-year", "peakRequestPerYear", "peakRequestsPerYear"}) @PositiveOrZero int requestPerYear, - @NotNull @JsonProperty("triggerTime") @JsonAlias("trigger-time") LocalTime triggerTime, - @NotNull @JsonProperty("duration") Duration duration, - @JsonProperty("jitter") double jitter, - @JsonProperty("smoothing") SmoothingMode smoothing, - @JsonProperty("applicability") ApplicabilityFilter applicability + // Legacy names, still found in configuration files + @PositiveOrZero @JsonPropertyDescription("Mean output tokens per request") @JsonAlias("output-token-count") int outputTokenPerRequest, + @PositiveOrZero @JsonPropertyDescription("Annual request count, distributed over the batch runs") + @JsonAlias({"requestsPerYear", "peak-request-per-year", "peakRequestPerYear", "peakRequestsPerYear"}) int requestPerYear, + @NotNull @JsonPropertyDescription("Daily start time of the batch job") LocalTime triggerTime, + @NotNull @JsonPropertyDescription("Duration of the batch job (ISO-8601)") Duration duration, + @JsonProperty(defaultValue = "0") @JsonPropertyDescription("Deterministic variance factor, e.g. 0.05 for +-5%") double jitter, + @JsonProperty(defaultValue = "none") @JsonPropertyDescription("Smoothing of the transitions at both ends of the batch window") SmoothingMode smoothing, + @JsonPropertyDescription("Days and months the scenario applies to, always when omitted") ApplicabilityFilter applicability ) implements Scenario { public static final SmoothingMode DEFAULT_SMOOTHING = SmoothingMode.NONE; diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/ConstantScenario.java b/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/ConstantScenario.java index cd50fb6..5955ad9 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/ConstantScenario.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/ConstantScenario.java @@ -1,7 +1,8 @@ package tech.illuin.wombat.module.llm_static.scenario; import com.fasterxml.jackson.annotation.JsonAlias; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.PositiveOrZero; import tech.illuin.wombat.module.llm_static.scenario.tools.ApplicabilityFilter; @@ -9,15 +10,13 @@ /** * Models a constant baseline annual request count and output token count per request. - * - * @param outputTokenPerRequest mean output token count per request (>= 0) - * @param requestPerYear annual request count (>= 0.0) - * @param applicability optional applicability filter */ +@JsonClassDescription("Constant request volume") public record ConstantScenario( - @PositiveOrZero @JsonProperty("outputTokenPerRequest") @JsonAlias({"output-token-per-request", "output-token-count"}) int outputTokenPerRequest, - @JsonProperty("requestPerYear") @JsonAlias({"request-per-year", "requestsPerYear"}) @PositiveOrZero int requestPerYear, - @JsonProperty("applicability") ApplicabilityFilter applicability + // Legacy names, still found in configuration files + @PositiveOrZero @JsonPropertyDescription("Mean output tokens per request") @JsonAlias("output-token-count") int outputTokenPerRequest, + @PositiveOrZero @JsonPropertyDescription("Annual request count") @JsonAlias("requestsPerYear") int requestPerYear, + @JsonPropertyDescription("Days and months the scenario applies to, always when omitted") ApplicabilityFilter applicability ) implements Scenario { public ConstantScenario diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/UserActivityScenario.java b/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/UserActivityScenario.java index 079f6ae..74e39cf 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/UserActivityScenario.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/UserActivityScenario.java @@ -1,8 +1,10 @@ package tech.illuin.wombat.module.llm_static.scenario; import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.NotNull; import jakarta.validation.constraints.PositiveOrZero; import tech.illuin.wombat.module.llm_static.scenario.tools.ApplicabilityFilter; @@ -15,24 +17,19 @@ /** * Models user activity between opening and closing times with configurable curve shape, * with annual request volume distributed across active periods and modulated by mathematical curves. - * - * @param outputTokenPerRequest mean output token count per request (>= 0) - * @param requestPerYear total annual request volume (>= 0.0) - * @param openingTime start time of user activity window - * @param closingTime end time of user activity window - * @param curve mathematical curve profile (sinusoidal, trapezoidal, bell) - * @param jitter deterministic variance factor (e.g. 0.05 for +-5%) - * @param applicability optional applicability filter */ @JsonIgnoreProperties(ignoreUnknown = true) +@JsonClassDescription("Request volume following user activity over a daily window") public record UserActivityScenario( - @PositiveOrZero @JsonProperty("outputTokenPerRequest") @JsonAlias({"output-token-per-request", "output-token-count"}) int outputTokenPerRequest, - @JsonProperty("requestPerYear") @JsonAlias({"request-per-year", "requestsPerYear", "peak-request-per-year", "peakRequestPerYear", "peakRequestsPerYear"}) @PositiveOrZero int requestPerYear, - @NotNull @JsonProperty("openingTime") @JsonAlias("opening-time") LocalTime openingTime, - @NotNull @JsonProperty("closingTime") @JsonAlias("closing-time") LocalTime closingTime, - @JsonProperty("curve") CurveShape curve, - @JsonProperty("jitter") double jitter, - @JsonProperty("applicability") ApplicabilityFilter applicability + // Legacy names, still found in configuration files + @PositiveOrZero @JsonPropertyDescription("Mean output tokens per request") @JsonAlias("output-token-count") int outputTokenPerRequest, + @PositiveOrZero @JsonPropertyDescription("Annual request count, distributed over the activity windows") + @JsonAlias({"requestsPerYear", "peak-request-per-year", "peakRequestPerYear", "peakRequestsPerYear"}) int requestPerYear, + @NotNull @JsonPropertyDescription("Start of the daily activity window") LocalTime openingTime, + @NotNull @JsonPropertyDescription("End of the daily activity window") LocalTime closingTime, + @JsonProperty(defaultValue = "bell") @JsonPropertyDescription("Shape of the activity over the window") CurveShape curve, + @JsonProperty(defaultValue = "0") @JsonPropertyDescription("Deterministic variance factor, e.g. 0.05 for +-5%") double jitter, + @JsonPropertyDescription("Days and months the scenario applies to, always when omitted") ApplicabilityFilter applicability ) implements Scenario { public static final CurveShape DEFAULT_CURVE = CurveShape.BELL; diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/tools/ApplicabilityFilter.java b/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/tools/ApplicabilityFilter.java index e7abc51..923cbdc 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/tools/ApplicabilityFilter.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_static/scenario/tools/ApplicabilityFilter.java @@ -1,16 +1,18 @@ package tech.illuin.wombat.module.llm_static.scenario.tools; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import java.time.DayOfWeek; import java.time.LocalDate; import java.time.Month; import java.time.ZonedDateTime; import java.util.Set; +@JsonClassDescription("Days and months a scenario applies to") public record ApplicabilityFilter( - @JsonProperty("daysOfWeek") Set daysOfWeek, - @JsonProperty("months") Set months + @JsonPropertyDescription("Days of the week the scenario applies to, every day when empty") Set daysOfWeek, + @JsonPropertyDescription("Months the scenario applies to, every month when empty") Set months ) { public static final ApplicabilityFilter ALWAYS = new ApplicabilityFilter(Set.of(), Set.of()); diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIAsset.java b/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIAsset.java index 6a7d7eb..964d89f 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIAsset.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIAsset.java @@ -1,6 +1,7 @@ package tech.illuin.wombat.module.llm_vertexai; -import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import com.fasterxml.jackson.annotation.JsonUnwrapped; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; @@ -9,20 +10,22 @@ import tech.illuin.wombat.core.asset.AssetIdentity; import tech.illuin.wombat.core.asset.type.AssetType; import tech.illuin.wombat.core.secret.SecretAware; +import tech.illuin.wombat.core.secret.SecretKey; import java.util.Set; +@JsonClassDescription("Google Cloud scope whose Vertex AI output tokens are read from Cloud Monitoring") public record LLMVertexAIAsset( @JsonUnwrapped AssetIdentity identity, - @NotBlank @JsonProperty("google-url") String googleUrl, + @NotBlank @JsonPropertyDescription("Base URL of the Cloud Monitoring API") String googleUrl, @NotBlank @Pattern(regexp = "(projects|folders|organizations)/[A-Za-z0-9_-]+") - @JsonProperty("resource-name") String resourceName, - @JsonProperty("credentials-key") String credentialsKey, - @JsonProperty("proxy-url") String proxyUrl, - @NotNull @JsonProperty("profile") LLMVertexAIProfile profile + @JsonPropertyDescription("Scope of the query: projects/, folders/ or organizations/") String resourceName, + @JsonPropertyDescription("Secret holding a service-account JSON key, Application Default Credentials when omitted") SecretKey credentialsKey, + @JsonPropertyDescription("HTTP proxy URL, with a host and a port") String proxyUrl, + @NotNull @JsonPropertyDescription("LLM profile and Cloud Monitoring query") LLMVertexAIProfile profile ) implements Asset, SecretAware { - public LLMVertexAIAsset(AssetIdentity identity, String googleUrl, String resourceName, String credentialsKey, LLMVertexAIProfile profile) + public LLMVertexAIAsset(AssetIdentity identity, String googleUrl, String resourceName, SecretKey credentialsKey, LLMVertexAIProfile profile) { this(identity, googleUrl, resourceName, credentialsKey, null, profile); } @@ -36,11 +39,11 @@ public AssetType type() @Override public Set requiredSecretKeys() { - return this.usesServiceAccountKey() ? Set.of(this.credentialsKey) : Set.of(); + return this.usesServiceAccountKey() ? Set.of(this.credentialsKey.value()) : Set.of(); } public boolean usesServiceAccountKey() { - return this.credentialsKey != null && !this.credentialsKey.isBlank(); + return this.credentialsKey != null; } } diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIProfile.java b/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIProfile.java index 6ddbdcf..4dd3174 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIProfile.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIProfile.java @@ -1,16 +1,18 @@ package tech.illuin.wombat.module.llm_vertexai; -import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonProperty; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.Positive; import tech.illuin.wombat.core.asset.profile.LLMProfile; import java.util.List; +@JsonClassDescription("Models the query is restricted to and request estimation") public record LLMVertexAIProfile( - @Positive @JsonProperty("outputTokensPerRequest") @JsonAlias("output-tokens-per-request") Integer outputTokensPerRequest, - @JsonProperty("models") List<@NotBlank String> models + @Positive @JsonProperty(defaultValue = "500") @JsonPropertyDescription("Average output tokens per request, used to derive the request count") Integer outputTokensPerRequest, + @JsonPropertyDescription("Model identifiers the query is restricted to, includes all models when empty") List<@NotBlank String> models ) implements LLMProfile { public LLMVertexAIProfile diff --git a/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleClientConfig.java b/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleClientConfig.java index e28fbb1..eb8d696 100644 --- a/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleClientConfig.java +++ b/module/src/main/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleClientConfig.java @@ -20,7 +20,7 @@ public static GoogleClient create(LLMVertexAIAsset properties, SecretResolver se public static GoogleClient create(LLMVertexAIAsset properties, SecretResolver secrets, Client client) { String serviceAccountJson = properties.usesServiceAccountKey() - ? secrets.require(properties.credentialsKey()) + ? secrets.require(properties.credentialsKey().value()) : null; Proxy proxy = null; diff --git a/module/src/test/java/tech/illuin/wombat/module/AssetConfigurationTest.java b/module/src/test/java/tech/illuin/wombat/module/AssetConfigurationTest.java new file mode 100644 index 0000000..1e0578b --- /dev/null +++ b/module/src/test/java/tech/illuin/wombat/module/AssetConfigurationTest.java @@ -0,0 +1,247 @@ +package tech.illuin.wombat.module; + +import com.fasterxml.jackson.annotation.JsonSubTypes; +import com.fasterxml.jackson.databind.BeanDescription; +import com.fasterxml.jackson.databind.JavaType; +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.PropertyNamingStrategies; +import com.fasterxml.jackson.databind.introspect.BeanPropertyDefinition; +import com.fasterxml.jackson.databind.json.JsonMapper; +import com.fasterxml.jackson.databind.jsontype.NamedType; +import com.fasterxml.jackson.databind.node.ObjectNode; +import com.fasterxml.jackson.dataformat.yaml.YAMLMapper; +import org.junit.jupiter.api.Test; +import tech.illuin.wombat.core.activity.commons.Country; +import tech.illuin.wombat.core.asset.Asset; +import tech.illuin.wombat.core.asset.profile.Lifetime; +import tech.illuin.wombat.core.module.WombatModule; +import tech.illuin.wombat.core.secret.SecretKey; +import tech.illuin.wombat.core.source.Period; +import tech.illuin.wombat.module.kubernetes_api.KubernetesAPIAsset; +import tech.illuin.wombat.module.llm_prometheus.LLMPrometheusAsset; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.time.Duration; +import java.util.ArrayList; +import java.util.HashSet; +import java.util.List; +import java.util.Map; +import java.util.ServiceLoader; +import java.util.Set; +import java.util.function.Function; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Collectors; +import java.util.stream.Stream; +import java.util.stream.StreamSupport; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Configuration files are kebab-case YAML and the API speaks camelCase JSON, both derived from the same implicit + * property names by the YAML mapper's naming strategy: these tests guard that nothing in the core modules defeats it. + */ +class AssetConfigurationTest +{ + private static final List MODULES = StreamSupport.stream(ServiceLoader.load(WombatModule.class).spliterator(), false).toList(); + private static final ObjectMapper YAML = register(YAMLMapper.builder().findAndAddModules().propertyNamingStrategy(PropertyNamingStrategies.KEBAB_CASE).build()); + private static final ObjectMapper JSON = register(JsonMapper.builder().findAndAddModules().build()); + private static final Path DOCS = Path.of("..", "doc", "module"); + private static final Pattern YAML_BLOCK = Pattern.compile("```yaml\\n(.*?)```", Pattern.DOTALL); + /** Types serialized as a single value, which have no properties of their own. */ + private static final Set> VALUE_TYPES = Set.of(Country.class, Lifetime.class, Period.class, SecretKey.class); + + /** + * An explicit multi-word name (e.g. {@code @JsonProperty("someName")}) is used as is by both mappers, so the YAML + * would expect {@code someName} rather than {@code some-name}. + */ + @Test + void naming_isKebabCaseInYamlForEveryProperty() + { + List mismatches = new ArrayList<>(); + Set> visited = new HashSet<>(); + for (WombatModule module : MODULES) + collectMismatches(JSON.constructType(module.assetClass()), visited, mismatches); + + assertTrue(visited.size() > MODULES.size(), "no nested type was walked"); + assertEquals(List.of(), mismatches); + } + + /** + * Every documented asset is read without losing any of its keys: unknown keys are otherwise silently ignored, at the + * root of an asset because its identity is unwrapped, and anywhere in the app which disables failing on them. + */ + @Test + void docs_areReadWithoutIgnoringAnyKey() throws IOException + { + Map> documented = documentedAssets(); + assertEquals(MODULES.size(), documented.size(), "every module documents its configuration"); + + for (List sources : documented.values()) + { + for (JsonNode source : sources) + { + Asset asset = YAML.treeToValue(source, Asset.class); + assertKeysRead(source, YAML.valueToTree(asset), asset.identity().id()); + } + } + } + + @Test + void docs_roundTripInYamlAndJson() throws IOException + { + for (List sources : documentedAssets().values()) + { + for (JsonNode source : sources) + { + Asset asset = YAML.treeToValue(source, Asset.class); + + assertEquals(asset, YAML.readValue(YAML.writeValueAsString(asset), Asset.class)); + assertEquals(asset, JSON.readValue(JSON.writeValueAsString(asset), Asset.class)); + } + } + } + + @Test + void persisted_readsKebabCaseAssetsFromBefore015() throws IOException + { + KubernetesAPIAsset kubernetes = assertInstanceOf(KubernetesAPIAsset.class, JSON.readValue(""" + { + "type": "tech.illuin.wombat-module.kubernetes-api", + "id": "k8s", + "environment-id": "env", + "config-path": "/etc/kubeconfig", + "read-timeout": "PT10S", + "profile": {"provider": "aws", "instance-type": "m5.large", "location": "FRA", "lifespan": "5y"} + } + """, Asset.class)); + + assertEquals("env", kubernetes.identity().environmentId()); + assertEquals("/etc/kubeconfig", kubernetes.configPath()); + assertEquals(Duration.ofSeconds(10), kubernetes.readTimeout().orElseThrow()); + assertEquals("m5.large", kubernetes.profile().instanceType()); + + LLMPrometheusAsset prometheus = assertInstanceOf(LLMPrometheusAsset.class, JSON.readValue(""" + { + "type": "tech.illuin.wombat-module.llm-prometheus", + "id": "prom", + "environment-id": "env", + "prometheus-url": "http://prometheus", + "proxy-url": "http://proxy:8080", + "username": "wombat", + "password-key": "PROM_PASSWORD", + "profile": {"provider": "mistralai", "model": "m", "location": "FRA", "dynamic-profile": {"query": "q"}} + } + """, Asset.class)); + + assertEquals("http://prometheus", prometheus.prometheusUrl()); + assertEquals("http://proxy:8080", prometheus.proxyUrl()); + assertEquals(SecretKey.of("PROM_PASSWORD"), prometheus.passwordKey()); + assertEquals("q", prometheus.profile().dynamicProfile().query()); + } + + private static void collectMismatches(JavaType type, Set> visited, List mismatches) + { + if (type.isContainerType() || type.isReferenceType()) + { + collectMismatches(type.getContentType(), visited, mismatches); + return; + } + + Class raw = type.getRawClass(); + if (raw.isPrimitive() || raw.isEnum() || raw.getName().startsWith("java.") || VALUE_TYPES.contains(raw) || !visited.add(raw)) + return; + + JsonSubTypes subTypes = raw.getAnnotation(JsonSubTypes.class); + if (subTypes != null) + { + for (JsonSubTypes.Type subType : subTypes.value()) + collectMismatches(JSON.constructType(subType.value()), visited, mismatches); + } + + Map yamlNames = properties(YAML, type).stream() + .collect(Collectors.toMap(BeanPropertyDefinition::getInternalName, BeanPropertyDefinition::getName)); + for (BeanPropertyDefinition property : properties(JSON, type)) + { + String expected = PropertyNamingStrategies.KebabCaseStrategy.INSTANCE.translate(property.getName()); + String actual = yamlNames.get(property.getInternalName()); + if (!expected.equals(actual)) + mismatches.add(raw.getSimpleName() + "." + property.getInternalName() + " is '" + actual + "' in YAML, expected '" + expected + "'"); + + collectMismatches(property.getPrimaryType(), visited, mismatches); + } + } + + private static List properties(ObjectMapper mapper, JavaType type) + { + BeanDescription description = mapper.getSerializationConfig().introspect(mapper.constructType(type.getRawClass())); + return description.findProperties(); + } + + /** + * @return the documented assets by asset-type, from the YAML blocks of {@code doc/module/*.md} starting with an + * {@code id}, the asset-type being named after the file + */ + private static Map> documentedAssets() throws IOException + { + Map typeByDoc = MODULES.stream() + .map(module -> module.type().name()) + .collect(Collectors.toMap(name -> name.substring(name.lastIndexOf('.') + 1) + ".md", Function.identity())); + + try (Stream docs = Files.list(DOCS)) + { + return docs + .filter(doc -> typeByDoc.containsKey(doc.getFileName().toString())) + .collect(Collectors.toMap(doc -> typeByDoc.get(doc.getFileName().toString()), doc -> readAssets(doc, typeByDoc.get(doc.getFileName().toString())))); + } + } + + private static List readAssets(Path doc, String type) + { + try { + List assets = new ArrayList<>(); + Matcher matcher = YAML_BLOCK.matcher(Files.readString(doc)); + while (matcher.find()) + { + if (!matcher.group(1).startsWith("id:")) + continue; + ObjectNode asset = (ObjectNode) YAML.readTree(matcher.group(1)); + asset.put("type", type); + assets.add(asset); + } + assertFalse(assets.isEmpty(), "no asset documented in " + doc); + return assets; + } + catch (IOException e) { + throw new IllegalStateException("Failed to read " + doc, e); + } + } + + private static void assertKeysRead(JsonNode source, JsonNode read, String path) + { + if (source.isObject()) + { + source.properties().forEach(entry -> { + assertTrue(read.has(entry.getKey()), "'" + entry.getKey() + "' is ignored at " + path); + assertKeysRead(entry.getValue(), read.get(entry.getKey()), path + "." + entry.getKey()); + }); + } + else if (source.isArray()) + { + for (int i = 0 ; i < source.size() ; i++) + assertKeysRead(source.get(i), read.get(i), path + "[" + i + "]"); + } + } + + private static M register(M mapper) + { + MODULES.forEach(module -> mapper.registerSubtypes(new NamedType(module.assetClass(), module.type().name()))); + return mapper; + } +} diff --git a/module/src/test/java/tech/illuin/wombat/module/AssetJsonTest.java b/module/src/test/java/tech/illuin/wombat/module/AssetJsonTest.java index 1ee676b..5f57da8 100644 --- a/module/src/test/java/tech/illuin/wombat/module/AssetJsonTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/AssetJsonTest.java @@ -49,7 +49,7 @@ void read_fillsTheIdentityTypeFromTheTypeProperty() throws Exception "provider": "mistralai", "model": "mistral-large-latest", "location": "FRA", - "scenarios": [{"type": "constant", "output-token-per-request": 500, "request-per-year": 1000}] + "scenarios": [{"type": "constant", "outputTokenPerRequest": 500, "requestPerYear": 1000}] }] } } diff --git a/module/src/test/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticProfileTest.java b/module/src/test/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticProfileTest.java index 1353f40..87f20c9 100644 --- a/module/src/test/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticProfileTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/kubernetes_static/KubernetesStaticProfileTest.java @@ -2,6 +2,8 @@ import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.PropertyNamingStrategies; +import com.fasterxml.jackson.dataformat.yaml.YAMLMapper; import org.junit.jupiter.api.Test; import tech.illuin.wombat.core.activity.commons.Country; import tech.illuin.wombat.core.asset.profile.Lifetime; @@ -25,6 +27,8 @@ class KubernetesStaticProfileTest { private final ObjectMapper objectMapper = new ObjectMapper().findAndRegisterModules(); + /** Reads configuration files as the app does: kebab-case, from the naming strategy alone. */ + private final ObjectMapper yamlMapper = YAMLMapper.builder().findAndAddModules().propertyNamingStrategy(PropertyNamingStrategies.KEBAB_CASE).build(); @Test void deserializesFromJsonWithCamelCaseProperties() throws JsonProcessingException @@ -61,7 +65,7 @@ void deserializesFromJsonWithCamelCaseProperties() throws JsonProcessingExceptio } @Test - void deserializesFromJsonWithKebabCaseAliases() throws JsonProcessingException + void deserializesFromKebabCaseYaml() throws JsonProcessingException { String json = """ { @@ -79,7 +83,7 @@ void deserializesFromJsonWithKebabCaseAliases() throws JsonProcessingException } """; - KubernetesStaticProfile profile = this.objectMapper.readValue(json, KubernetesStaticProfile.class); + KubernetesStaticProfile profile = this.yamlMapper.readValue(json, KubernetesStaticProfile.class); assertNotNull(profile); assertEquals(ServerProvider.gcp, profile.provider()); @@ -90,7 +94,7 @@ void deserializesFromJsonWithKebabCaseAliases() throws JsonProcessingException } @Test - void deserializesNodeCountInCamelCaseAndKebabCase() throws JsonProcessingException + void deserializesNodeCountFromJsonAndKebabCaseYaml() throws JsonProcessingException { String camelCaseJson = """ { @@ -128,7 +132,7 @@ void deserializesNodeCountInCamelCaseAndKebabCase() throws JsonProcessingExcepti } """; - KubernetesStaticProfile kebabProfile = this.objectMapper.readValue(kebabCaseJson, KubernetesStaticProfile.class); + KubernetesStaticProfile kebabProfile = this.yamlMapper.readValue(kebabCaseJson, KubernetesStaticProfile.class); assertNotNull(kebabProfile); assertEquals(4, kebabProfile.nodeCount()); } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicModuleTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicModuleTest.java index 8bedef4..b8ea64d 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicModuleTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/LLMAnthropicModuleTest.java @@ -7,6 +7,7 @@ import tech.illuin.wombat.core.module.WombatServices; import tech.illuin.wombat.core.secret.EnvironmentSecretResolver; import tech.illuin.wombat.core.secret.MissingSecretException; +import tech.illuin.wombat.core.secret.SecretKey; import tech.illuin.wombat.module.llm_anthropic.activity.LLMAnthropicActivityResolver; import java.util.Map; @@ -66,7 +67,7 @@ private static WombatServices services(Map environment) private static LLMAnthropicAsset asset() { return new LLMAnthropicAsset( - AssetIdentity.of("a", "env", LLMAnthropicModule.TYPE), null, null, "ANTHROPIC_ADMIN_KEY", + AssetIdentity.of("a", "env", LLMAnthropicModule.TYPE), null, null, SecretKey.of("ANTHROPIC_ADMIN_KEY"), new LLMAnthropicProfile(FRANCE, 500, null, null, null) ); } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/activity/LLMAnthropicActivityResolverTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/activity/LLMAnthropicActivityResolverTest.java index dc6ad65..311615a 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/activity/LLMAnthropicActivityResolverTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/activity/LLMAnthropicActivityResolverTest.java @@ -9,6 +9,7 @@ import tech.illuin.wombat.core.activity.llm.LLMServiceActivity; import tech.illuin.wombat.core.asset.AssetIdentity; import tech.illuin.wombat.core.asset.profile.LLMProvider; +import tech.illuin.wombat.core.secret.SecretKey; import tech.illuin.wombat.module.llm_anthropic.LLMAnthropicAsset; import tech.illuin.wombat.module.llm_anthropic.LLMAnthropicProfile; import tech.illuin.wombat.module.llm_anthropic.connector.AnthropicAdminClient; @@ -40,7 +41,7 @@ class LLMAnthropicActivityResolverTest private final AnthropicAdminClient client = mock(AnthropicAdminClient.class); private final LLMAnthropicAsset asset = new LLMAnthropicAsset( - AssetIdentity.of("claude", "prod", LLMAnthropicModule.TYPE), null, null, "ANTHROPIC_ADMIN_KEY", + AssetIdentity.of("claude", "prod", LLMAnthropicModule.TYPE), null, null, SecretKey.of("ANTHROPIC_ADMIN_KEY"), new LLMAnthropicProfile(FRANCE, 500, List.of("claude-opus-5-5"), null, null) ); private final LLMAnthropicActivityResolver resolver = new LLMAnthropicActivityResolver(this.client); diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/connector/AnthropicClientConfigTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/connector/AnthropicClientConfigTest.java index 6f5b4d3..2d87f18 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/connector/AnthropicClientConfigTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_anthropic/connector/AnthropicClientConfigTest.java @@ -6,6 +6,7 @@ import tech.illuin.wombat.module.llm_anthropic.LLMAnthropicModule; import tech.illuin.wombat.core.asset.AssetIdentity; import tech.illuin.wombat.core.secret.EnvironmentSecretResolver; +import tech.illuin.wombat.core.secret.SecretKey; import tech.illuin.wombat.module.llm_anthropic.LLMAnthropicAsset; import tech.illuin.wombat.module.llm_anthropic.LLMAnthropicProfile; import tech.illuin.wombat.module.llm_anthropic.connector.model.AnthropicUsageReport; @@ -55,7 +56,7 @@ void sendsAdminHeadersAndExpandsArrayParameters() }; LLMAnthropicAsset asset = new LLMAnthropicAsset( - AssetIdentity.of("claude", "prod", LLMAnthropicModule.TYPE), null, null, "ANTHROPIC_ADMIN_KEY", + AssetIdentity.of("claude", "prod", LLMAnthropicModule.TYPE), null, null, SecretKey.of("ANTHROPIC_ADMIN_KEY"), new LLMAnthropicProfile(FRANCE, 500, null, null, null) ); EnvironmentSecretResolver secrets = new EnvironmentSecretResolver(Map.of("ANTHROPIC_ADMIN_KEY", "sk-ant-admin-test")::get); diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusAssetTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusAssetTest.java index 5b1a450..ad475a3 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusAssetTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusAssetTest.java @@ -4,6 +4,7 @@ import tech.illuin.wombat.core.asset.AssetIdentity; import tech.illuin.wombat.core.asset.profile.LLMProvider; import tech.illuin.wombat.core.source.Period; +import tech.illuin.wombat.core.secret.SecretKey; import java.util.Set; @@ -47,7 +48,7 @@ void aUsernameWithoutAPasswordVariableIsRejected() private static LLMPrometheusAsset asset(String username, String passwordEnv) { return new LLMPrometheusAsset( - AssetIdentity.of("p", "env", LLMPrometheusModule.TYPE), "http://prometheus", null, username, passwordEnv, Period.ZERO, + AssetIdentity.of("p", "env", LLMPrometheusModule.TYPE), "http://prometheus", null, username, SecretKey.of(passwordEnv), Period.ZERO, new LLMPrometheusProfile(LLMProvider.mistralai, "m", FRANCE, new LLMPrometheusProfile.DynamicProfile("q")) ); } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusModuleTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusModuleTest.java index e23cc8f..d936f31 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusModuleTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/LLMPrometheusModuleTest.java @@ -9,6 +9,7 @@ import tech.illuin.wombat.core.secret.MissingSecretException; import tech.illuin.wombat.core.source.Period; import tech.illuin.wombat.core.source.WombatSource; +import tech.illuin.wombat.core.secret.SecretKey; import tech.illuin.wombat.module.llm_prometheus.source.LLMPrometheusSource; import java.util.Map; @@ -60,7 +61,7 @@ private static LLMPrometheusAsset asset(String username, String passwordEnv) { return new LLMPrometheusAsset( AssetIdentity.of("p", "env", LLMPrometheusModule.TYPE), - "http://prometheus", null, username, passwordEnv, Period.ZERO, + "http://prometheus", null, username, SecretKey.of(passwordEnv), Period.ZERO, new LLMPrometheusProfile(LLMProvider.mistralai, "m", FRANCE, new LLMPrometheusProfile.DynamicProfile("q")) ); } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/connector/PrometheusClientConfigTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/connector/PrometheusClientConfigTest.java index 6115152..6b44a47 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/connector/PrometheusClientConfigTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_prometheus/connector/PrometheusClientConfigTest.java @@ -8,6 +8,7 @@ import tech.illuin.wombat.core.secret.MissingSecretException; import tech.illuin.wombat.core.secret.SecretResolver; import tech.illuin.wombat.core.source.Period; +import tech.illuin.wombat.core.secret.SecretKey; import tech.illuin.wombat.module.llm_prometheus.LLMPrometheusAsset; import tech.illuin.wombat.module.llm_prometheus.LLMPrometheusProfile; @@ -54,7 +55,7 @@ private static LLMPrometheusAsset asset(String id, String username, String passw { return new LLMPrometheusAsset( AssetIdentity.of(id, "env", LLMPrometheusModule.TYPE), - "http://prometheus", null, username, passwordEnv, Period.ZERO, + "http://prometheus", null, username, SecretKey.of(passwordEnv), Period.ZERO, new LLMPrometheusProfile(LLMProvider.mistralai, "m", FRANCE, new LLMPrometheusProfile.DynamicProfile("q")) ); } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_static/LLMStaticProfileTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_static/LLMStaticProfileTest.java index 50949cc..50786f1 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_static/LLMStaticProfileTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_static/LLMStaticProfileTest.java @@ -2,6 +2,8 @@ import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.PropertyNamingStrategies; +import com.fasterxml.jackson.dataformat.yaml.YAMLMapper; import org.junit.jupiter.api.Test; import tech.illuin.wombat.core.activity.commons.Country; import tech.illuin.wombat.core.asset.profile.LLMProvider; @@ -21,6 +23,8 @@ class LLMStaticProfileTest { private final ObjectMapper objectMapper = new ObjectMapper().findAndRegisterModules(); + /** Reads configuration files as the app does: kebab-case, from the naming strategy alone. */ + private final ObjectMapper yamlMapper = YAMLMapper.builder().findAndAddModules().propertyNamingStrategy(PropertyNamingStrategies.KEBAB_CASE).build(); @Test void deserializesFromJsonWithCamelCaseProperties() throws JsonProcessingException @@ -64,7 +68,7 @@ void deserializesFromJsonWithCamelCaseProperties() throws JsonProcessingExceptio } @Test - void deserializesFromJsonWithKebabCaseAliases() throws JsonProcessingException + void deserializesFromKebabCaseYaml() throws JsonProcessingException { String json = """ { @@ -86,7 +90,7 @@ void deserializesFromJsonWithKebabCaseAliases() throws JsonProcessingException } """; - LLMStaticProfile profile = this.objectMapper.readValue(json, LLMStaticProfile.class); + LLMStaticProfile profile = this.yamlMapper.readValue(json, LLMStaticProfile.class); assertNotNull(profile); assertEquals(ZoneId.of("UTC"), profile.zoneId()); diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_static/scenario/ScenarioSerializationTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_static/scenario/ScenarioSerializationTest.java index 2a6b4bc..f3fe9fc 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_static/scenario/ScenarioSerializationTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_static/scenario/ScenarioSerializationTest.java @@ -2,6 +2,8 @@ import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.PropertyNamingStrategies; +import com.fasterxml.jackson.dataformat.yaml.YAMLMapper; import org.junit.jupiter.api.Test; import tech.illuin.wombat.module.llm_static.scenario.tools.ApplicabilityFilter; @@ -16,6 +18,8 @@ public class ScenarioSerializationTest { private final ObjectMapper objectMapper = new ObjectMapper().findAndRegisterModules(); + /** Reads configuration files as the app does: kebab-case, from the naming strategy alone. */ + private final ObjectMapper yamlMapper = YAMLMapper.builder().findAndAddModules().propertyNamingStrategy(PropertyNamingStrategies.KEBAB_CASE).build(); @Test void deserializesConstantScenario() throws JsonProcessingException @@ -44,7 +48,7 @@ void deserializesConstantScenario() throws JsonProcessingException } @Test - void deserializesConstantScenarioWithKebabCaseAliases() throws JsonProcessingException + void deserializesConstantScenarioFromKebabCaseYaml() throws JsonProcessingException { String json = """ { @@ -54,7 +58,7 @@ void deserializesConstantScenarioWithKebabCaseAliases() throws JsonProcessingExc } """; - Scenario scenario = this.objectMapper.readValue(json, Scenario.class); + Scenario scenario = this.yamlMapper.readValue(json, Scenario.class); assertInstanceOf(ConstantScenario.class, scenario); ConstantScenario constant = (ConstantScenario) scenario; @@ -92,7 +96,7 @@ void deserializesUserActivityScenario() throws JsonProcessingException } @Test - void deserializesUserActivityScenarioWithLegacyAndKebabCaseAliases() throws JsonProcessingException + void deserializesUserActivityScenarioFromKebabCaseYamlWithLegacyNames() throws JsonProcessingException { String json = """ { @@ -105,7 +109,7 @@ void deserializesUserActivityScenarioWithLegacyAndKebabCaseAliases() throws Json } """; - Scenario scenario = this.objectMapper.readValue(json, Scenario.class); + Scenario scenario = this.yamlMapper.readValue(json, Scenario.class); assertInstanceOf(UserActivityScenario.class, scenario); UserActivityScenario userActivity = (UserActivityScenario) scenario; @@ -145,7 +149,7 @@ void deserializesBatchActivityScenario() throws JsonProcessingException } @Test - void deserializesBatchActivityScenarioWithLegacyAndKebabCaseAliases() throws JsonProcessingException + void deserializesBatchActivityScenarioFromKebabCaseYamlWithLegacyNames() throws JsonProcessingException { String json = """ { @@ -158,7 +162,7 @@ void deserializesBatchActivityScenarioWithLegacyAndKebabCaseAliases() throws Jso } """; - Scenario scenario = this.objectMapper.readValue(json, Scenario.class); + Scenario scenario = this.yamlMapper.readValue(json, Scenario.class); assertInstanceOf(BatchActivityScenario.class, scenario); BatchActivityScenario batchActivity = (BatchActivityScenario) scenario; diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIAssetTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIAssetTest.java index 69890c2..e3de50f 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIAssetTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIAssetTest.java @@ -2,6 +2,7 @@ import org.junit.jupiter.api.Test; import tech.illuin.wombat.core.asset.AssetIdentity; +import tech.illuin.wombat.core.secret.SecretKey; import java.util.Set; import java.util.List; @@ -47,7 +48,7 @@ void declaresTheLLMVertexAIAssetType() private static LLMVertexAIAsset asset(String credentialsKey) { - return new LLMVertexAIAsset(AssetIdentity.of("g", "env", LLMVertexAIModule.TYPE), "https://monitoring.googleapis.com", "projects/my-project", credentialsKey, + return new LLMVertexAIAsset(AssetIdentity.of("g", "env", LLMVertexAIModule.TYPE), "https://monitoring.googleapis.com", "projects/my-project", SecretKey.of(credentialsKey), new LLMVertexAIProfile(500, List.of("gemini-2.5-flash"))); } } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIModuleTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIModuleTest.java index c626889..44907e7 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIModuleTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIModuleTest.java @@ -7,6 +7,7 @@ import tech.illuin.wombat.core.module.WombatServices; import tech.illuin.wombat.core.secret.EnvironmentSecretResolver; import tech.illuin.wombat.core.secret.MissingSecretException; +import tech.illuin.wombat.core.secret.SecretKey; import tech.illuin.wombat.module.llm_vertexai.activity.LLMVertexAIActivityResolver; import java.util.List; @@ -66,7 +67,7 @@ private static WombatServices services(Map environment) private static LLMVertexAIAsset asset(String credentialsKey) { - return new LLMVertexAIAsset(AssetIdentity.of("g", "env", LLMVertexAIModule.TYPE), "https://monitoring.googleapis.com", "projects/my-project", credentialsKey, + return new LLMVertexAIAsset(AssetIdentity.of("g", "env", LLMVertexAIModule.TYPE), "https://monitoring.googleapis.com", "projects/my-project", SecretKey.of(credentialsKey), new LLMVertexAIProfile(500, List.of("gemini-2.5-flash"))); } } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIProfileTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIProfileTest.java index f6e6807..1665380 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIProfileTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/LLMVertexAIProfileTest.java @@ -18,7 +18,7 @@ class LLMVertexAIProfileTest void omittedModelsMeansAllModels() throws Exception { LLMVertexAIProfile profile = this.mapper.readValue(""" - {"output-tokens-per-request":500} + {"outputTokensPerRequest":500} """, LLMVertexAIProfile.class); assertEquals(List.of(), profile.models()); @@ -39,8 +39,8 @@ void modelListIsCopiedAndImmutable() void oldRawFilterConfigurationIsRejected() { assertThrows(UnrecognizedPropertyException.class, () -> this.mapper.readValue(""" - {"output-tokens-per-request":500, - "dynamic-profile":{"filter":"anything"}} + {"outputTokensPerRequest":500, + "dynamicProfile":{"filter":"anything"}} """, LLMVertexAIProfile.class)); } } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleClientConfigTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleClientConfigTest.java index 719ba10..a867c55 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleClientConfigTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleClientConfigTest.java @@ -8,6 +8,7 @@ import tech.illuin.wombat.core.secret.EnvironmentSecretResolver; import tech.illuin.wombat.core.secret.MissingSecretException; import tech.illuin.wombat.core.secret.SecretResolver; +import tech.illuin.wombat.core.secret.SecretKey; import tech.illuin.wombat.module.llm_vertexai.LLMVertexAIAsset; import tech.illuin.wombat.module.llm_vertexai.LLMVertexAIProfile; @@ -115,7 +116,7 @@ private static SecretResolver secrets(Map environment) private static LLMVertexAIAsset asset(String id, String credentialsKey) { - return new LLMVertexAIAsset(AssetIdentity.of(id, "env", LLMVertexAIModule.TYPE), "https://monitoring.googleapis.com", "projects/my-project", credentialsKey, + return new LLMVertexAIAsset(AssetIdentity.of(id, "env", LLMVertexAIModule.TYPE), "https://monitoring.googleapis.com", "projects/my-project", SecretKey.of(credentialsKey), new LLMVertexAIProfile(500, List.of("gemini-2.5-flash"))); } diff --git a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleRegionTest.java b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleRegionTest.java index 0de0dee..1776910 100644 --- a/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleRegionTest.java +++ b/module/src/test/java/tech/illuin/wombat/module/llm_vertexai/connector/GoogleRegionTest.java @@ -52,7 +52,7 @@ class GoogleRegionTest "me-central2, SA", "me-central1, QA", "me-west1, IL", - "global, ''" + "global, XX" }) void testTranslate(String regionIdentifier, String expectedAlpha2) {