@openagentsy/footprint 0.0.0-stage → 0.2.0

package/dist/resolve.d.ts

@@ -0,0 +1,56 @@
+import { type ModelArch, type Range, type SiteProfile } from './types.js';
+/**
+ * Everything the estimator needs to know, injected.
+ *
+ * Nothing is loaded from a file: the model map, the grid factors and the
+ * provider sites all come from the caller, because the data behind them has
+ * licenses this package cannot ship.
+ */
+export interface Registry {
+    /** The model map, keyed by the normalised model id. */
+    ecologitsModels: Map<string, ModelArch>;
+    /** The user's own numbers, keyed by `provider/modelId` or by `modelId`. */
+    overrides: Map<string, ModelArch>;
+    /** The provider sites, keyed by provider. */
+    providerSites: Map<string, SiteProfile>;
+    /** Kilograms of CO2 per kWh, by region. */
+    grid: Map<string, Range>;
+    /** Litres per kWh of embedded water, by region. */
+    offsiteWue: Map<string, Range>;
+}
+/** The region key that means "the world, when nobody says". */
+export declare const WORLD_REGION = "WORLD";
+/** What a provider discloses about its own infrastructure. */
+export interface ProviderDefaults {
+    pue: Range;
+    wueOnSite: Range;
+    source: string;
+    disclosed: boolean;
+}
+/** What a provider discloses about its own infrastructure. */
+export declare function providerDefaults(provider: string): ProviderDefaults;
+/**
+ * The model id in the form the model map is keyed by.
+ *
+ * A model id may carry its provider (`ollama/qwen3:8b`) and it may be
+ * written in any case, so the key is the name alone, in lower case.
+ */
+export declare function normalizeModelId(modelId: string): string;
+/**
+ * What is known about a model.
+ *
+ * A user's own number wins over the model map, because the person writing
+ * it knows more than any table. A model nobody describes gets a very wide
+ * range, so the answer says "model size unknown" instead of pretending.
+ */
+export declare function resolveArch(reg: Registry, provider: string, modelId: string): ModelArch;
+/**
+ * The site of a provider in a region.
+ *
+ * The provider's own PUE and cooling water come from the table, or from the
+ * registry when the caller knows better. The grid's carbon and water come
+ * from the registry, which is injected, and a region nobody has a number
+ * for falls back to the world.
+ */
+export declare function resolveSite(reg: Registry, provider: string, region: string): SiteProfile;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAK,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACxC,2EAA2E;IAC3E,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,6CAA6C;IAC7C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxC,2CAA2C;IAC3C,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzB,mDAAmD;IACnD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAChC;AAED,+DAA+D;AAC/D,eAAO,MAAM,YAAY,UAAU,CAAC;AAEpC,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,KAAK,CAAC;IACX,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB;AAuDD,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAGnE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAUvF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAyBxF"}

package/dist/resolve.js

@@ -0,0 +1,114 @@
+import { r } from './types.js';
+/** The region key that means "the world, when nobody says". */
+export const WORLD_REGION = 'WORLD';
+/**
+ * The provider table of the EcoLogits methodology.
+ *
+ * The numbers are the ones EcoLogits uses for these providers. A provider
+ * that is not in the table gets the widest range in it, marked as not
+ * disclosed, because guessing a narrow one would be a lie.
+ */
+const PROVIDER_TABLE = {
+    anthropic: {
+        pue: r(1.09, 1.14),
+        wueOnSite: r(0.13, 0.999),
+        source: 'ecologits:anthropic',
+        disclosed: true,
+    },
+    google: {
+        pue: r(1.09),
+        wueOnSite: r(0.999),
+        source: 'ecologits:google',
+        disclosed: true,
+    },
+    mistral: {
+        pue: r(1.16),
+        wueOnSite: r(0.09),
+        source: 'ecologits:mistral',
+        disclosed: true,
+    },
+    openai: {
+        pue: r(1.2),
+        wueOnSite: r(0.569),
+        source: 'ecologits:openai',
+        disclosed: true,
+    },
+};
+/** The names EcoLogits itself uses, which are not the names in the table. */
+const PROVIDER_ALIASES = {
+    google_genai: 'google',
+    mistralai: 'mistral',
+};
+/**
+ * The widest PUE range in the table, with the widest WUE range.
+ *
+ * A provider that discloses nothing gets these, and they are marked as not
+ * disclosed so the UI can say so.
+ */
+const UNDISCLOSED = {
+    pue: r(1.09, 1.14),
+    wueOnSite: r(0.13, 0.999),
+    source: 'world-default',
+    disclosed: false,
+};
+/** What a provider discloses about its own infrastructure. */
+export function providerDefaults(provider) {
+    const key = PROVIDER_ALIASES[provider] ?? provider;
+    return PROVIDER_TABLE[key] ?? UNDISCLOSED;
+}
+/**
+ * The model id in the form the model map is keyed by.
+ *
+ * A model id may carry its provider (`ollama/qwen3:8b`) and it may be
+ * written in any case, so the key is the name alone, in lower case.
+ */
+export function normalizeModelId(modelId) {
+    const trimmed = modelId.trim().toLowerCase();
+    const slash = trimmed.indexOf('/');
+    return slash === -1 ? trimmed : trimmed.slice(slash + 1);
+}
+/**
+ * What is known about a model.
+ *
+ * A user's own number wins over the model map, because the person writing
+ * it knows more than any table. A model nobody describes gets a very wide
+ * range, so the answer says "model size unknown" instead of pretending.
+ */
+export function resolveArch(reg, provider, modelId) {
+    return (reg.overrides.get(`${provider}/${modelId}`) ??
+        reg.overrides.get(modelId) ??
+        reg.ecologitsModels.get(normalizeModelId(modelId)) ?? {
+        totalParamsB: r(10, 2000),
+        activeParamsB: r(1, 600),
+        source: 'unknown',
+    });
+}
+/**
+ * The site of a provider in a region.
+ *
+ * The provider's own PUE and cooling water come from the table, or from the
+ * registry when the caller knows better. The grid's carbon and water come
+ * from the registry, which is injected, and a region nobody has a number
+ * for falls back to the world.
+ */
+export function resolveSite(reg, provider, region) {
+    const injected = reg.providerSites.get(provider);
+    const site = injected ?? providerDefaults(provider);
+    const grid = reg.grid.get(region) ?? reg.grid.get(WORLD_REGION);
+    if (!grid) {
+        throw new Error(`no grid carbon factor for "${region}" and no "${WORLD_REGION}" in the registry`);
+    }
+    const offsite = reg.offsiteWue.get(region) ?? reg.offsiteWue.get(WORLD_REGION);
+    if (!offsite) {
+        throw new Error(`no off-site water factor for "${region}" and no "${WORLD_REGION}" in the registry`);
+    }
+    return {
+        pue: site.pue,
+        wueOnSite: site.wueOnSite,
+        wueOffSite: offsite,
+        gridKgCo2PerKWh: grid,
+        source: site.source,
+        disclosed: site.disclosed,
+    };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"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"}

package/dist/resolve.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resolve.test.d.ts.map

package/dist/resolve.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.test.d.ts","sourceRoot":"","sources":["../src/resolve.test.ts"],"names":[],"mappings":""}

package/dist/resolve.test.js

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeModelId, providerDefaults, resolveArch, resolveSite, } from './resolve.js';
+import { r } from './types.js';
+const ARCH = {
+    totalParamsB: r(70),
+    activeParamsB: r(70),
+    source: 'user',
+};
+function registry(overrides = {}) {
+    return {
+        ecologitsModels: new Map(),
+        overrides: new Map(),
+        providerSites: new Map(),
+        grid: new Map(),
+        offsiteWue: new Map(),
+        ...overrides,
+    };
+}
+describe('the provider table', () => {
+    it('keeps the numbers the methodology publishes', () => {
+        expect(providerDefaults('anthropic')).toMatchObject({
+            pue: [1.09, 1.14],
+            wueOnSite: [0.13, 0.999],
+            disclosed: true,
+        });
+        expect(providerDefaults('google')).toMatchObject({
+            pue: [1.09, 1.09],
+            wueOnSite: [0.999, 0.999],
+        });
+        expect(providerDefaults('mistral')).toMatchObject({
+            pue: [1.16, 1.16],
+            wueOnSite: [0.09, 0.09],
+        });
+        expect(providerDefaults('openai')).toMatchObject({
+            pue: [1.2, 1.2],
+            wueOnSite: [0.569, 0.569],
+        });
+    });
+    it('knows the names the methodology uses', () => {
+        expect(providerDefaults('google_genai')).toEqual(providerDefaults('google'));
+        expect(providerDefaults('mistralai')).toEqual(providerDefaults('mistral'));
+    });
+    it('gives an unknown provider the widest range, marked as undisclosed', () => {
+        const unknown = providerDefaults('ollama-cloud');
+        expect(unknown.pue).toEqual([1.09, 1.14]);
+        expect(unknown.wueOnSite).toEqual([0.13, 0.999]);
+        expect(unknown.disclosed).toBe(false);
+    });
+});
+describe('the model id', () => {
+    it('drops the provider and the case', () => {
+        expect(normalizeModelId('Ollama/Qwen3:8B')).toBe('qwen3:8b');
+        expect(normalizeModelId('  gpt-4o-mini ')).toBe('gpt-4o-mini');
+    });
+});
+describe('the architecture of a model', () => {
+    it('prefers the number the user wrote for that provider', () => {
+        const reg = registry({
+            overrides: new Map([
+                ['openai/gpt-4o-mini', ARCH],
+                ['gpt-4o-mini', { ...ARCH, totalParamsB: r(1) }],
+            ]),
+        });
+        expect(resolveArch(reg, 'openai', 'gpt-4o-mini')).toEqual(ARCH);
+    });
+    it('falls back to the number the user wrote for any provider', () => {
+        const reg = registry({ overrides: new Map([['gpt-4o-mini', ARCH]]) });
+        expect(resolveArch(reg, 'azure', 'gpt-4o-mini')).toEqual(ARCH);
+    });
+    it('then takes the model map, under the normalised name', () => {
+        const reg = registry({ ecologitsModels: new Map([['gpt-4o-mini', ARCH]]) });
+        expect(resolveArch(reg, 'openai', 'GPT-4o-Mini')).toEqual(ARCH);
+    });
+    it('and says the model size is unknown when nobody knows it', () => {
+        const unknown = resolveArch(registry(), 'openai', 'mystery-model');
+        expect(unknown.source).toBe('unknown');
+        expect(unknown.totalParamsB[0]).toBe(10);
+        expect(unknown.totalParamsB[1]).toBe(2000);
+    });
+});
+describe('the site of a provider', () => {
+    it('joins the provider numbers with the grid numbers', () => {
+        const reg = registry({
+            grid: new Map([['US', r(0.4)]]),
+            offsiteWue: new Map([['US', r(1.6)]]),
+        });
+        const site = resolveSite(reg, 'openai', 'US');
+        expect(site.pue).toEqual([1.2, 1.2]);
+        expect(site.wueOnSite).toEqual([0.569, 0.569]);
+        expect(site.gridKgCo2PerKWh).toEqual([0.4, 0.4]);
+        expect(site.wueOffSite).toEqual([1.6, 1.6]);
+    });
+    it('falls back to the world when the region is unknown', () => {
+        const reg = registry({
+            grid: new Map([['WORLD', r(0.5)]]),
+            offsiteWue: new Map([['WORLD', r(2)]]),
+        });
+        const site = resolveSite(reg, 'openai', 'FR');
+        expect(site.gridKgCo2PerKWh).toEqual([0.5, 0.5]);
+        expect(site.wueOffSite).toEqual([2, 2]);
+    });
+    it('says what is missing instead of guessing a grid', () => {
+        expect(() => resolveSite(registry(), 'openai', 'US')).toThrow(/grid carbon factor/);
+    });
+});
+//# sourceMappingURL=resolve.test.js.map

package/dist/resolve.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.test.js","sourceRoot":"","sources":["../src/resolve.test.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * A quantity nobody knows exactly, so it carries its bounds.
+ *
+ * Every number this package produces is an interval, because the inputs are
+ * intervals: a model size nobody discloses, a data centre's PUE, a grid's
+ * carbon factor. A point estimate would hide that, so the type makes the
+ * width impossible to lose.
+ */
+export type Range = readonly [lo: number, hi: number];
+/** An interval, with the ends in order. */
+export declare const r: (lo: number, hi?: number) => Range;
+/** The sum of two intervals. */
+export declare const add: (a: Range, b: Range) => Range;
+/** The product of two intervals: the four corners, then the two ends. */
+export declare const mul: (a: Range, b: Range) => Range;
+/** An interval scaled by a number. */
+export declare const scale: (a: Range, k: number) => Range;
+export interface ModelArch {
+    /** Billions of parameters in total. */
+    totalParamsB: Range;
+    /**
+     * Billions of parameters that take part in one token's forward pass.
+     * Equal to the total for a dense model; EcoLogits assumes 10-30 percent
+     * activation for a mixture of experts when nobody says.
+     */
+    activeParamsB: Range;
+    source: 'ecologits' | 'model-card' | 'user' | 'unknown';
+}
+export interface SiteProfile {
+    /** Power Usage Effectiveness: the overhead of the data centre. */
+    pue: Range;
+    /** Litres per kWh, for the cooling inside the data centre. */
+    wueOnSite: Range;
+    /** Litres per kWh, for the water embedded in the grid electricity. */
+    wueOffSite: Range;
+    /** Kilograms of CO2 per kWh. */
+    gridKgCo2PerKWh: Range;
+    /** Where the numbers came from, e.g. "ecologits:anthropic" or "owid:US". */
+    source: string;
+    /** False when the provider does not disclose its infrastructure. */
+    disclosed: boolean;
+}
+export interface Usage {
+    /** Generated tokens. Reasoning tokens count once, not twice. */
+    outputTokens: number;
+    /** Fresh input tokens. */
+    inputTokens: number;
+    /** Input tokens read from the cache. */
+    cacheReadTokens: number;
+    /** Input tokens written to the cache. */
+    cacheWriteTokens: number;
+    /** The measured request time, when it is known. */
+    latencyS?: number;
+}
+export interface Impact {
+    energyWh: Range;
+    waterL: Range;
+    co2Kg: Range;
+    warmingC: Range;
+    dominantUncertainty: 'model-size' | 'site' | 'grid' | 'tcre';
+    notes: string[];
+}
+/**
+ * The coefficients of the prefill term.
+ *
+ * The fit is not shipped: the numbers come from ML.ENERGY measurements that
+ * a person has to review first, so a caller that wants the term brings its
+ * own coefficients. The unit is Wh per token per billion active parameters,
+ * and a coefficient is an interval like every other number in this package:
+ * the fit in `data/prefill-fit.json` carries a range, because the models
+ * that were measured differ from each other.
+ */
+export interface PrefillCoeff {
+    /** The fresh input: Wh per input token per billion active parameters. */
+    kIn: Range;
+    /** The cache read: Wh per cache-read token per billion active parameters. */
+    kCache: Range;
+}
+/** How fast the provider generates, when the numbers are known. */
+export interface Throughput {
+    /** Time to the first token, in seconds. */
+    ttftS: Range;
+    /** Tokens per second. */
+    tps: Range;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;AAEtD,2CAA2C;AAC3C,eAAO,MAAM,CAAC,GAAI,IAAI,MAAM,EAAE,WAAO,KAAG,KAA6C,CAAC;AAEtF,gCAAgC;AAChC,eAAO,MAAM,GAAG,GAAI,GAAG,KAAK,EAAE,GAAG,KAAK,KAAG,KAAmC,CAAC;AAE7E,yEAAyE;AACzE,eAAO,MAAM,GAAG,GAAI,GAAG,KAAK,EAAE,GAAG,KAAK,KAAG,KAGxC,CAAC;AAEF,sCAAsC;AACtC,eAAO,MAAM,KAAK,GAAI,GAAG,KAAK,EAAE,GAAG,MAAM,KAAG,KAA8B,CAAC;AAE3E,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,YAAY,EAAE,KAAK,CAAC;IACpB;;;;OAIG;IACH,aAAa,EAAE,KAAK,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,CAAC;CACzD;AAED,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,GAAG,EAAE,KAAK,CAAC;IACX,8DAA8D;IAC9D,SAAS,EAAE,KAAK,CAAC;IACjB,sEAAsE;IACtE,UAAU,EAAE,KAAK,CAAC;IAClB,gCAAgC;IAChC,eAAe,EAAE,KAAK,CAAC;IACvB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,KAAK;IACpB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC;IAChB,mBAAmB,EAAE,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,GAAG,EAAE,KAAK,CAAC;IACX,6EAA6E;IAC7E,MAAM,EAAE,KAAK,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,KAAK,EAAE,KAAK,CAAC;IACb,yBAAyB;IACzB,GAAG,EAAE,KAAK,CAAC;CACZ"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/** An interval, with the ends in order. */
+export const r = (lo, hi = lo) => [Math.min(lo, hi), Math.max(lo, hi)];
+/** The sum of two intervals. */
+export const add = (a, b) => [a[0] + b[0], a[1] + b[1]];
+/** The product of two intervals: the four corners, then the two ends. */
+export const mul = (a, b) => {
+    const products = [a[0] * b[0], a[0] * b[1], a[1] * b[0], a[1] * b[1]];
+    return [Math.min(...products), Math.max(...products)];
+};
+/** An interval scaled by a number. */
+export const scale = (a, k) => r(a[0] * k, a[1] * k);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAUA,2CAA2C;AAC3C,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAU,EAAE,EAAE,GAAG,EAAE,EAAS,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAEtF,gCAAgC;AAChC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7E,yEAAyE;AACzE,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE;IAC/C,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;AACxD,CAAC,CAAC;AAEF,sCAAsC;AACtC,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAQ,EAAE,CAAS,EAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@openagentsy/footprint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "author": "Grand Slopulissimo <slopulissimo@voxslopuli.org>",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "fit:prefill": "node scripts/fit-prefill.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  },
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voxslopuli/openagentsy.git"
+  },
+  "homepage": "https://github.com/voxslopuli/openagentsy#readme",
+  "bugs": {
+    "url": "https://github.com/voxslopuli/openagentsy/issues"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "The OpenAgentsy footprint estimator: the energy, water and carbon of an inference, as ranges.",
+  "keywords": [
+    "agents",
+    "opencode",
+    "llm",
+    "ecologits",
+    "carbon"
+  ],
+  "files": [
+    "dist"
+  ]
+}