Require Explicit Runtime Activation Instead of Import-Time Monkeypatching

[Tanishq1030]

Summary

Importing anchor.runtime currently performs automatic runtime activation, including global monkeypatching of supported HTTP and LLM client libraries.

Importing a Python module should not modify global application behavior.

Runtime activation should require an explicit API call from the developer.

---

Problem

Today:

import anchor.runtime

implicitly performs:

anchor.runtime.activate()

This globally patches supported libraries (e.g. requests, httpx, and supported LLM SDKs) during module import.

Import-time side effects can:

• unexpectedly alter application behavior,
• make debugging more difficult,
• interfere with testing,
• surprise developers,
• make integration harder with existing frameworks.

Importing a module should be a passive operation whenever possible.

---

Proposed Solution

Separate importing the runtime from activating it.

Example:

import anchor.runtime

anchor.runtime.activate()

or

from anchor.runtime import activate

activate()

Activation should occur only when explicitly requested by the application.

If activation has not occurred, runtime interception should remain disabled.

---

Benefits

• Removes unexpected import-time side effects.
• Makes runtime activation explicit.
• Improves compatibility with existing Python applications.
• Simplifies testing and debugging.
• Aligns with established Python library conventions.

---

Acceptance Criteria

• Remove automatic activation during module import.
• Require an explicit activate() call.
• Prevent monkeypatching until activation occurs.
• Update documentation and examples to use explicit activation.
• Preserve existing runtime behavior after activation.

---

Design Notes

Anchor Runtime should follow the principle of explicit activation.

Importing a module should expose functionality without modifying application state.

Activation represents a deliberate decision by the developer to enable runtime governance and should therefore occur through an explicit API rather than as a side effect of importing the package.

This approach improves predictability while preserving all existing runtime capabilities.