Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 29 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,24 +231,35 @@ LLMMetricResolver llmMetricResolver = new MicrometerLLMMetricResolver(meterRegis

#### Now, assemble the `WombatCore`

The `WombatCore` is also handed `WombatServices`, the system components made available to modules. For now this is the `SecretResolver` modules use to read the credentials their assets reference by variable name (an API key, a password, etc.). `SecretResolver.standard()` reads them from the process environment, which is also what the `WombatCore` falls back to when no `WombatServices` is given.

[Default components](#default-components) are registered per family as factories, `null` meaning there is no default for that part of the pipeline. Assets whose type has neither a module component nor a default for a given part are not evaluated for that part, and an error is logged when the evaluator is created.

```java
/* tech.illuin.wombat.core.connector.boavizta.connector.BoaviztaClient boaviztaClient */
/* tech.illuin.wombat.core.connector.ecologits.connector.EcologitsClient ecologitsClient */

/* Default components are stateless, a single instance can serve every asset */
WombatActivityResolver k8sActivity = new KubernetesActivityResolver(k8sMetricResolver);
WombatActivityResolver llmActivity = new LLMActivityResolver(llmMetricResolver);
WombatEvaluationResolver boavizta = new BoaviztaEvaluationResolver(boaviztaClient);
WombatEvaluationResolver ecologits = new EcologitsEvaluationResolver(ecologitsClient);

try (WombatCore core = new WombatCore(
contextProvider,
new WombatServices(SecretResolver.standard()),
metricPersister,
List.of(
new KubernetesAPIModule(),
new KubernetesStaticModule(),
new LLMStaticModule()
),
defaults -> {
defaults.register(KUBERNETES_CONTAINER, new KubernetesActivityResolver(k8sMetricResolver), new BoaviztaEvaluationResolver(boaviztaClient), null);
defaults.register(LLM, new LLMActivityResolver(llmMetricResolver), new EcologitsEvaluationResolver(ecologitsClient), null);
defaults.register(KUBERNETES_CONTAINER, (services, asset) -> k8sActivity, (services, asset) -> boavizta, null);
defaults.register(LLM, (services, asset) -> llmActivity, (services, asset) -> ecologits, null);
}
)) {
/* The evaluator is stateless, you should reuse it throughout your app ; e.g. make it injectable if applicable */
/* The evaluator keeps the resolvers it built for each asset, you should reuse it throughout your app ; e.g. make it injectable if applicable */
AssetEvaluator evaluator = core.createEvaluator();

Instant now = Instant.now();
Expand All @@ -257,9 +268,11 @@ try (WombatCore core = new WombatCore(
}
```

Both the `AssetMonitor` and the `AssetEvaluator` read the context on every call: assets added to it are picked up without rebuilding anything, and the components of removed assets are discarded. When an asset's settings change, call `refresh(asset.identity())` on both so that its components are built again (see [component lifecycle](#component-lifecycle)).

### Custom Module

Custom modules enable tracking domain-specific assets , integrating custom activity modeling or even custom impact/cost resolving. To create a custom module, define an `Asset` with its profile, implement `WombatModule`, and provide the relevant resolvers (such as a `WombatActivityResolver`).
Custom modules enable tracking domain-specific assets , integrating custom activity modeling or even custom impact/cost resolving. To create a custom module, define an `Asset` with its profile, implement `WombatModule`, and provide factories for the relevant components (such as a `WombatActivityResolver`).

Here is an example of a custom module providing modeled activity data for LLM traffic:

Expand All @@ -277,9 +290,9 @@ public class MySimulationModule implements WombatModule
public Class<? extends Asset> assetClass() { return MySimulationAsset.class; }

@Override
public Optional<WombatActivityResolver> createActivityResolver(WombatContext ctx)
public Optional<ProcessorFactory<WombatActivityResolver>> activityResolver()
{
return Optional.of(new MySimulationActivityResolver());
return Optional.of((services, asset) -> new MySimulationActivityResolver());
}
}

Expand Down Expand Up @@ -351,6 +364,16 @@ public class MySimulationActivityResolver implements WombatActivityResolver

Once defined, you can register this module in your `WombatCore` as seen [above](#custom-core) or in a Wombat app as documented [here](https://github.com/illuin-tech/wombat#custom-extensions).

#### Component lifecycle

A module never builds its components upfront: each method of `WombatModule` returns a `ProcessorFactory`, which the `AssetMonitor` and `AssetEvaluator` invoke the first time they need a component for it.

* a component is built once per asset identity (`AssetIdentity`) and then kept
* the component is handed the asset as it currently is on every call, so its settings should be read from there rather than captured by the factory ; anything built by the factory remains as it was built until the asset is refreshed with `refresh(asset.identity())`, or leaves the context
* if the component implements `AutoCloseable`, it is closed when its asset is refreshed or leaves the context, and when the `AssetMonitor` or `AssetEvaluator` is closed
* a factory may return the same instance for every asset (as the default components above do), such an instance must then not implement `AutoCloseable` since it would be closed along with the first asset to go ; release its resources from `WombatModule.close()` instead
* a factory failing leaves nothing behind: its exception propagates to the call that needed the component, and building it is attempted again the next time it is needed

## How to build

Building the project requires a Java 21+ JDK, in order to compile it:
Expand Down
87 changes: 49 additions & 38 deletions core/src/main/java/tech/illuin/wombat/core/WombatCore.java
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,13 @@
import org.slf4j.LoggerFactory;
import tech.illuin.wombat.core.activity.WombatActivityResolver;
import tech.illuin.wombat.core.asset.type.ServiceFamily;
import tech.illuin.wombat.core.context.WombatContext;
import tech.illuin.wombat.core.context.WombatContextProvider;
import tech.illuin.wombat.core.evaluation.WombatEvaluationResolver;
import tech.illuin.wombat.core.evaluation.AssetEvaluator;
import tech.illuin.wombat.core.module.ProcessorFactory;
import tech.illuin.wombat.core.module.WombatModule;
import tech.illuin.wombat.core.module.WombatServices;
import tech.illuin.wombat.core.secret.SecretResolver;
import tech.illuin.wombat.core.source.AssetMonitor;
import tech.illuin.wombat.core.source.persistence.WombatMetricPersister;

Expand All @@ -21,18 +23,31 @@ public final class WombatCore implements AutoCloseable
{
private final Map<String, WombatModule> modules;
private final WombatContextProvider contextProvider;
private final WombatServices services;
private final WombatMetricPersister persister;
private final CoreDefaults defaults;

private static final Logger logger = LoggerFactory.getLogger(WombatCore.class);

/** Resolves secrets from the process environment, which is where a deployment supplies them. */
public WombatCore(
WombatContextProvider contextProvider,
WombatMetricPersister persister,
Collection<WombatModule> modules,
Consumer<CoreDefaults> defaultsAdjuster
) {
this(contextProvider, new WombatServices(SecretResolver.standard()), persister, modules, defaultsAdjuster);
}

public WombatCore(
WombatContextProvider contextProvider,
WombatServices services,
WombatMetricPersister persister,
Collection<WombatModule> modules,
Consumer<CoreDefaults> defaultsAdjuster
) {
this.contextProvider = contextProvider;
this.services = services;
this.persister = persister;
this.modules = new HashMap<>();
this.defaults = new CoreDefaults();
Expand All @@ -59,44 +74,40 @@ public AssetMonitor createMonitor()
public AssetMonitor createMonitor(ExecutorService executorService)
{
logger.info("Creating wombat source-monitor out of {} registered modules", this.modules.size());
AssetMonitor monitor = new AssetMonitor(this.contextProvider, this.persister, executorService);
WombatContext context = this.contextProvider.provide();

context.assets().stream()
.filter(asset -> this.modules.containsKey(asset.type().name()))
.forEach(asset -> {
WombatModule module = this.modules.get(asset.type().name());
WombatContext scoped = context.scope(asset.type());

module.createSource(scoped).ifPresentOrElse(
src -> monitor.register(asset.type(), src),
() -> logger.debug("Skipping monitor registration for asset-type {}", asset.type().name())
);
});
AssetMonitor monitor = new AssetMonitor(this.contextProvider, this.services, this.persister, executorService);

for (WombatModule module : this.modules.values())
{
module.source().ifPresentOrElse(
factory -> monitor.register(module.type(), factory),
() -> logger.debug("Skipping monitor registration for asset-type {}", module.type().name())
);
}
return monitor;
}

public AssetEvaluator createEvaluator()
{
logger.info("Creating wombat impact-calculator out of {} registered modules", this.modules.size());
AssetEvaluator calculator = new AssetEvaluator(this.contextProvider);
WombatContext context = this.contextProvider.provide();
AssetEvaluator calculator = new AssetEvaluator(this.contextProvider, this.services);

for (WombatModule module : this.modules.values())
{
ServiceFamily family = module.type().family();

WombatActivityResolver activityResolver = module.createActivityResolver(context).or(() -> this.defaults.getActivityResolver(family)).orElseThrow();
calculator.registerActivityResolver(module.type(), activityResolver);
logger.debug("Registered wombat activity-resolver {} for asset-type {}", activityResolver.getClass().getSimpleName(), module.type().name());

WombatEvaluationResolver impactResolver = module.createImpactResolver(context).or(() -> this.defaults.getImpactResolver(family)).orElseThrow();
calculator.registerImpactResolver(module.type(), impactResolver);
logger.debug("Registered wombat impact-resolver {} for asset-type {}", impactResolver.getClass().getSimpleName(), module.type().name());

WombatEvaluationResolver costResolver = module.createCostResolver(context).or(() -> this.defaults.getCostResolver(family)).orElseThrow();
calculator.registerCostResolver(module.type(), costResolver);
logger.debug("Registered wombat cost-resolver {} for asset-type {}", costResolver.getClass().getSimpleName(), module.type().name());
String typeName = module.type().name();

module.activityResolver().or(() -> this.defaults.getActivityResolver(family)).ifPresentOrElse(
factory -> calculator.registerActivityResolver(module.type(), factory),
() -> logger.error("No activity-resolver available for asset-type {}, its assets will not be evaluated", typeName)
);
module.impactResolver().or(() -> this.defaults.getImpactResolver(family)).ifPresentOrElse(
factory -> calculator.registerImpactResolver(module.type(), factory),
() -> logger.error("No impact-resolver available for asset-type {}, impacts of its assets will not be evaluated", typeName)
);
module.costResolver().or(() -> this.defaults.getCostResolver(family)).ifPresentOrElse(
factory -> calculator.registerCostResolver(module.type(), factory),
() -> logger.error("No cost-resolver available for asset-type {}, costs of its assets will not be evaluated", typeName)
);
}

return calculator;
Expand All @@ -111,9 +122,9 @@ public void close()

public static final class CoreDefaults
{
private final Map<ServiceFamily, WombatActivityResolver> defaultActivityResolvers;
private final Map<ServiceFamily, WombatEvaluationResolver> defaultImpactResolvers;
private final Map<ServiceFamily, WombatEvaluationResolver> defaultCostResolvers;
private final Map<ServiceFamily, ProcessorFactory<WombatActivityResolver>> defaultActivityResolvers;
private final Map<ServiceFamily, ProcessorFactory<WombatEvaluationResolver>> defaultImpactResolvers;
private final Map<ServiceFamily, ProcessorFactory<WombatEvaluationResolver>> defaultCostResolvers;

private CoreDefaults()
{
Expand All @@ -124,27 +135,27 @@ private CoreDefaults()

public CoreDefaults register(
ServiceFamily family,
WombatActivityResolver activityResolver,
WombatEvaluationResolver impactResolver,
WombatEvaluationResolver costResolver
ProcessorFactory<WombatActivityResolver> activityResolver,
ProcessorFactory<WombatEvaluationResolver> impactResolver,
ProcessorFactory<WombatEvaluationResolver> costResolver
) {
this.defaultActivityResolvers.put(family, activityResolver);
this.defaultImpactResolvers.put(family, impactResolver);
this.defaultCostResolvers.put(family, costResolver);
return this;
}

public Optional<WombatActivityResolver> getActivityResolver(ServiceFamily family)
public Optional<ProcessorFactory<WombatActivityResolver>> getActivityResolver(ServiceFamily family)
{
return Optional.ofNullable(this.defaultActivityResolvers.get(family));
}

public Optional<WombatEvaluationResolver> getImpactResolver(ServiceFamily family)
public Optional<ProcessorFactory<WombatEvaluationResolver>> getImpactResolver(ServiceFamily family)
{
return Optional.ofNullable(this.defaultImpactResolvers.get(family));
}

public Optional<WombatEvaluationResolver> getCostResolver(ServiceFamily family)
public Optional<ProcessorFactory<WombatEvaluationResolver>> getCostResolver(ServiceFamily family)
{
return Optional.ofNullable(this.defaultCostResolvers.get(family));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,21 @@

import tech.illuin.wombat.core.asset.Asset;
import tech.illuin.wombat.core.asset.Environment;
import tech.illuin.wombat.core.secret.EnvironmentSecretResolver;
import tech.illuin.wombat.core.secret.SecretResolver;

import java.util.List;

public final class ResolvedContext implements WombatContext
{
private final List<Environment> environments;
private final SecretResolver secrets;

public ResolvedContext(List<Environment> environments, SecretResolver secrets)
{
this.environments = environments;
this.secrets = secrets;
}

/** Resolves secrets from the process environment, which is where a deployment supplies them. */
public ResolvedContext(List<Environment> environments)
{
this(environments, new EnvironmentSecretResolver());
this.environments = environments;
}

public ResolvedContext(Environment... environments)
{
this(List.of(environments), new EnvironmentSecretResolver());
this(List.of(environments));
}

@Override
Expand All @@ -42,10 +32,4 @@ public List<Asset> assets()
.flatMap(e -> e.assets().stream())
.toList();
}

@Override
public SecretResolver secrets()
{
return this.secrets;
}
}
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
package tech.illuin.wombat.core.context;

import tech.illuin.wombat.core.asset.Asset;
import tech.illuin.wombat.core.asset.type.AssetType;
import tech.illuin.wombat.core.asset.Environment;
import tech.illuin.wombat.core.secret.SecretResolver;

import java.util.List;

Expand All @@ -12,28 +10,4 @@ public interface WombatContext
List<Environment> environments();

List<Asset> assets();

/**
* Resolves the credentials the context's assets reference by variable name.
* <p>
* Part of the context rather than a per-module dependency: an asset and the secrets it needs are resolved
* together, so a module builds its clients from the context alone.
*/
SecretResolver secrets();

default WombatContext scope(AssetType type)
{
return new ResolvedContext(
this.environments().stream()
.map(e -> {
List<Asset> filtered = e.assets().stream()
.filter(p -> p.type().equals(type))
.toList();
return new Environment(e.id(), filtered);
})
.filter(e -> !e.assets().isEmpty())
.toList(),
this.secrets()
);
}
}
Loading
Loading