Skip to main content

52. Minimal Dependencies for AI Module

Status: Accepted Date: 2025-07-06

Context​

The mercury-ai module is a critical component that needs to be reliable and performant. In software development, adding third-party dependencies can accelerate development but also introduces risks: larger bundle sizes, slower startup times, potential security vulnerabilities, and a higher maintenance burden (keeping dependencies up to date). For a core service like the AI module, we need to be deliberate about managing these risks.

Decision​

The mercury-ai module must adhere to a strict Minimal Dependencies policy. We will be highly selective about the third-party libraries we add to this module.

Every new dependency must be justified and evaluated against the following criteria:

  1. Necessity: Is the functionality absolutely essential for the module's core purpose?
  2. Size & Performance: What is the impact of the dependency on the package size and runtime performance?
  3. Security & Maintenance: Is the library actively maintained, and does it have a good security track record?
  4. Alternatives: Can the same functionality be achieved with a small amount of native code or with a library we already use elsewhere in the project?

The default decision for any proposed new dependency is "no", unless a strong case can be made. The only expected core dependencies are the client library for communicating with Ollama and the client for communicating with the signal emitter service.

Consequences​

Positive:

  • Improved Performance: A smaller dependency footprint leads to a smaller, faster service with lower memory consumption and quicker startup times.
  • Enhanced Security: Fewer dependencies mean a smaller attack surface and less exposure to vulnerabilities in third-party code.
  • Higher Reliability & Stability: Fewer moving parts and less external code mean fewer potential points of failure.
  • Lower Maintenance Burden: Reduces the time and effort spent on updating dependencies and resolving conflicts between them.

Negative:

  • Slower Initial Development: We may need to write more code ourselves for functionality that could have been imported from a library. This can slow down the initial implementation of some features.
  • "Not Invented Here" Syndrome: This policy could encourage "re-inventing the wheel" if not applied with good judgment.

Mitigation:

  • Pragmatism over Dogma: This is a principle, not an unbreakable law. If a high-quality, well-maintained library provides significant value and aligns with our performance and security goals (e.g., a highly optimized math library), it can be approved. The goal is to be deliberate, not to forbid all dependencies.
  • Focus on Core Logic: The "write it ourselves" approach should be limited to simple, non-critical utilities. For complex, specialized domains (like advanced mathematics or data serialization), using a standard, best-in-class library is still the preferred approach.
  • Code Reviews: The justification for any new dependency will be a key point of discussion during code reviews, ensuring the policy is applied consistently.