$ show mlco2/ecologits
EcoLogits is a Python library that estimates the environmental footprint (energy, GHG emissions, abiotic resource depletion, primary energy, water consumption) of generative AI model inference accessed through provider APIs. It integrates with official client libraries for OpenAI, Anthropic, Cohere, Mistral AI, HuggingFace Hub, Google GenAI, and LiteLLM by monkey-patching their core methods using `wrapt`. When a user makes an API call, the library intercepts the request, measures latency, looks up model characteristics and electricity mix data, and attaches an `ImpactsOutput` object to the response containing usage and embodied impact estimates with uncertainty ranges. Architecturally, the library is organized around a provider instrumentor pattern: each provider has a tracer class that wraps sync/async and streaming/non-streaming methods. Impact calculations are performed by a Directed Acyclic Graph (DAG) engine that resolves interdependent computations (energy, GWP, ADPe, PE, WCF) from regression coefficients and data files. The library also supports video generation impact estimation via a standalone function. An optional OpenTelemetry integration exports metrics to an OTLP endpoint. Key entry points are `EcoLogits.init()` to enable tracers for selected providers, and `video_impacts()` for video generation. External dependencies include provider SDKs (openai, anthropic, etc.), `wrapt` for wrapping, `pydantic` for data models, and optionally `opentelemetry-api` and `opentelemetry-sdk`. The library is published on PyPI and documented with MkDocs. While primarily a software library, EcoLogits has a strong data/research character: its methodology is based on Life Cycle Assessment principles, relies on curated JSON data files (models, electricity mixes, video models) that require regular updates, and is published in the Journal of Open Source Software. The codebase demonstrates high craftsmanship with clean abstractions, extensive testing, and a well-documented methodology.
The LLM identified 4 files worth highlighting for reuse:
A decorator-based Directed Acyclic Graph execution engine. Tasks are registered with dependencies, and the DAG resolves the execution order topologically. This pattern is reusable for any multi-step computation with interdependencies, not just environmental impacts. It demonstrates clean separation of concerns and could be extracted as a standalone utility.
A Pydantic model that represents a value with min, mean, and max fields, supporting arithmetic operations and comparisons. This is a generic pattern for handling uncertainty in measurements and could be reused in any domain requiring interval arithmetic.
A system of base classes WarningMessage and ErrorMessage with code-based lookup and URL linking to documentation. This provides a structured way to communicate data quality issues to users, and the pattern could be extracted for any library that needs to report warnings/errors with actionable links.
Contains the ImpactsOutput model and llm_impacts() helper function that orchestrates the impact computation for a single LLM call. While somewhat coupled to the impact models, the pattern of collecting timing, looking up model data, and returning a structured result is clean and could inform similar instrumentation libraries.