{
  "name": "forge.health",
  "language": "python",
  "version": "0.1.0",
  "description": "Python health package; imports are explicit from this package.",
  "manifest": "forge-py/pyproject.toml",
  "manifestSha256": "7f96957378b21995bf2e583af2afd1b9e6fb3b0089ff3559d62c7e012a034696",
  "status": "source-reference",
  "registryPublicationVerified": false,
  "route": "/libraries/python/health",
  "features": {},
  "files": [
    {
      "path": "forge-py/src/forge/health/__init__.py",
      "sha256": "bff2d8e49f528ee5ca38343052495de7e022f22678b16607164e66ae31c918c2",
      "artifactSha256": "857b20bfc17d2e7bb3bb5348b0d80a0670d8267f5b4e8ebbe587a19a0a4fd62f",
      "url": "/reference/source/forge-py/src/forge/health/__init__.py.txt",
      "declarations": []
    },
    {
      "path": "forge-py/src/forge/health/events.py",
      "sha256": "2cee77133b9767621d5d02eed94202eae8776d301b580a0506beea2b4e5d821c",
      "artifactSha256": "774b8cebb521158ea90e78f1d0b3535fd921f419a33d0f8c9062d512c9269132",
      "url": "/reference/source/forge-py/src/forge/health/events.py.txt",
      "declarations": [
        {
          "name": "HealthEventKind",
          "line": 15,
          "signature": "class HealthEventKind(Enum)",
          "documentation": "Types of health events."
        },
        {
          "name": "HealthEvent",
          "line": 30,
          "signature": "class HealthEvent()",
          "documentation": "A significant health-related event.\n\nArgs:\n    kind: The type of health event.\n    message: Human-readable description.\n    details: Optional key-value details.\n    timestamp: When the event occurred."
        },
        {
          "name": "HealthEvent.to_dict",
          "line": 45,
          "signature": "def to_dict(self) -> dict[str, Any]",
          "documentation": "Serialize to a dictionary.\n\nReturns:\n    Dictionary representation."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/health/lifecycle.py",
      "sha256": "e6b64df78d0834c6e10652172088791e0b2285b17e7c4ad5d7b3fa0aaf14699e",
      "artifactSha256": "0db200f52b79003c375d56940e071ec5c8d56de75da023a5ab071c28ec328d43",
      "url": "/reference/source/forge-py/src/forge/health/lifecycle.py.txt",
      "declarations": [
        {
          "name": "LifecycleState",
          "line": 42,
          "signature": "class LifecycleState(Enum)",
          "documentation": "ANVIL lifecycle states.\n\nThese six states and their valid transitions are IMMUTABLE per\nANVIL Spec section 13.2. No states may be added, removed,\nor have their transition rules changed without a formal specification\namendment.\n\nExample:\n    >>> LifecycleState.RUNNING.is_operational()\n    True\n    >>> LifecycleState.READY.is_operational()\n    True\n    >>> LifecycleState.TERMINATED.is_terminal()\n    True"
        },
        {
          "name": "LifecycleState.valid_transitions",
          "line": 66,
          "signature": "def valid_transitions(self) -> tuple[LifecycleState, ...]",
          "documentation": "Return the set of valid target states from this state.\n\nThe transition table is defined by ANVIL Spec section 13.2\nand is immutable.\n\nReturns:\n    Tuple of valid target states.\n\nExample:\n    >>> targets = LifecycleState.RUNNING.valid_transitions()\n    >>> LifecycleState.PAUSED in targets\n    True"
        },
        {
          "name": "LifecycleState.is_terminal",
          "line": 83,
          "signature": "def is_terminal(self) -> bool",
          "documentation": "Return True if this is a terminal state (no outgoing transitions).\n\nCurrently, only Terminated is a terminal state.\n\nReturns:\n    True if terminal."
        },
        {
          "name": "LifecycleState.is_operational",
          "line": 93,
          "signature": "def is_operational(self) -> bool",
          "documentation": "Return True if the agent can perform work in this state.\n\nBoth Ready and Running are operational states. Ready means the\nagent can accept new work; Running means it is actively processing.\n\nANVIL Spec section 13.2.\n\nReturns:\n    True if operational."
        },
        {
          "name": "LifecycleTransition",
          "line": 141,
          "signature": "class LifecycleTransition()",
          "documentation": "A record of a single lifecycle state transition.\n\nEvery transition is timestamped and stored in the LifecycleManager's history.\n\nArgs:\n    from_state: The state before the transition.\n    to_state: The state after the transition.\n    timestamp: The UTC timestamp when the transition occurred."
        },
        {
          "name": "LifecycleManager",
          "line": 157,
          "signature": "class LifecycleManager()",
          "documentation": "Manages the ANVIL lifecycle state machine for a single agent.\n\nThe LifecycleManager enforces the immutable transition table from ANVIL Spec\nsection 13.2. It tracks the current state, validates all\ntransitions, and maintains a complete transition history.\n\nEvery agent starts in the Initializing state per ANVIL Spec section 13.2.\n\nExample:\n    >>> mgr = LifecycleManager()\n    >>> mgr.state\n    <LifecycleState.INITIALIZING: 'Initializing'>\n    >>> t = mgr.transition(LifecycleState.READY)\n    >>> t.from_state\n    <LifecycleState.INITIALIZING: 'Initializing'>\n    >>> mgr.state\n    <LifecycleState.READY: 'Ready'>"
        },
        {
          "name": "LifecycleManager.__init__",
          "line": 177,
          "signature": "def __init__(self) -> None",
          "documentation": ""
        },
        {
          "name": "LifecycleManager.state",
          "line": 182,
          "signature": "def state(self) -> LifecycleState",
          "documentation": "Return the current lifecycle state.\n\nReturns:\n    The current LifecycleState."
        },
        {
          "name": "LifecycleManager.transition",
          "line": 190,
          "signature": "def transition(self, target: LifecycleState) -> LifecycleTransition",
          "documentation": "Attempt to transition to the given target state.\n\nValidates the transition against the ANVIL Spec section 13.2\ntransition table. If valid, the state is updated and a LifecycleTransition\nis recorded. If invalid, an error is raised and the state is unchanged.\n\nANVIL Spec section 13.2 -- Lifecycle State Machine.\n\nArgs:\n    target: The desired target LifecycleState.\n\nReturns:\n    A LifecycleTransition record.\n\nRaises:\n    InvalidLifecycleTransitionError: If the transition is not in the\n        ANVIL transition table or is a self-transition.\n\nExample:\n    >>> mgr = LifecycleManager()\n    >>> t = mgr.transition(LifecycleState.READY)\n    >>> t.to_state\n    <LifecycleState.READY: 'Ready'>"
        },
        {
          "name": "LifecycleManager.can_transition_to",
          "line": 248,
          "signature": "def can_transition_to(self, target: LifecycleState) -> bool",
          "documentation": "Return True if the transition from the current state to target is valid.\n\nArgs:\n    target: The candidate target LifecycleState.\n\nReturns:\n    True if the transition is permitted."
        },
        {
          "name": "LifecycleManager.valid_transitions",
          "line": 259,
          "signature": "def valid_transitions(self) -> list[LifecycleState]",
          "documentation": "Return the set of valid target states from the current state.\n\nReturns:\n    List of valid target states."
        },
        {
          "name": "LifecycleManager.history",
          "line": 267,
          "signature": "def history(self) -> list[LifecycleTransition]",
          "documentation": "Return the complete transition history.\n\nThe history is ordered chronologically.\n\nReturns:\n    List of all LifecycleTransition records."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/health/monitoring.py",
      "sha256": "bd7db074d076ba7fde7530d8f0bb5d69637620f33c7a761c402717384e3ab502",
      "artifactSha256": "3614da58d48de230161d47f47e5557128c3e73039e7acf02db037ae58dad3b11",
      "url": "/reference/source/forge-py/src/forge/health/monitoring.py.txt",
      "declarations": [
        {
          "name": "HealthStatus",
          "line": 14,
          "signature": "class HealthStatus(Enum)",
          "documentation": "Overall health status of an agent.\n\nANVIL Spec section 14.1 -- Telemetry Contract."
        },
        {
          "name": "HealthThresholds",
          "line": 30,
          "signature": "class HealthThresholds()",
          "documentation": "Configurable thresholds for health monitoring.\n\nArgs:\n    max_error_rate: Maximum error rate (errors / total calls) before degraded.\n    max_cpu_percent: CPU usage threshold for degraded status.\n    max_memory_bytes: Memory usage threshold for degraded status.\n    critical_error_count: Error count threshold for critical status."
        },
        {
          "name": "HealthMonitor",
          "line": 46,
          "signature": "class HealthMonitor()",
          "documentation": "Monitors agent health based on configurable thresholds.\n\nThe monitor evaluates a HealthProfile against thresholds to determine\nthe overall health status.\n\nArgs:\n    thresholds: The health thresholds to apply.\n\nExample:\n    >>> monitor = HealthMonitor()\n    >>> profile = HealthProfile()\n    >>> monitor.evaluate(profile)\n    <HealthStatus.HEALTHY: 'healthy'>"
        },
        {
          "name": "HealthMonitor.__init__",
          "line": 62,
          "signature": "def __init__(self, thresholds: HealthThresholds | None=None) -> None",
          "documentation": ""
        },
        {
          "name": "HealthMonitor.evaluate",
          "line": 65,
          "signature": "def evaluate(self, profile: HealthProfile) -> HealthStatus",
          "documentation": "Evaluate the health status of a profile.\n\nArgs:\n    profile: The health profile to evaluate.\n\nReturns:\n    The overall health status."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/health/profile.py",
      "sha256": "5997917589466f7b42de166bd9856b8ee6fa2cf972278e17ebffa6eec843d98d",
      "artifactSha256": "6e906352cb78940e49aec6f61ec5fac7acb3544d26ff44340797d957da8630a4",
      "url": "/reference/source/forge-py/src/forge/health/profile.py.txt",
      "declarations": [
        {
          "name": "HealthProfile",
          "line": 21,
          "signature": "class HealthProfile()",
          "documentation": "Runtime health metrics for an ANVIL-compliant agent.\n\nThe health profile tracks operational statistics that enable health\nmonitoring, capacity planning, and audit trail generation. All counters\nare monotonically increasing -- they are never reset during an agent's\nlifetime.\n\nANVIL Spec section 14.1 -- Telemetry Contract.\n\nExample:\n    >>> profile = HealthProfile()\n    >>> profile.record_tool_invocation()\n    >>> profile.record_inference(256)\n    >>> profile.record_error()\n    >>> profile.tool_invocations\n    1\n    >>> profile.inference_tokens\n    256\n    >>> profile.error_count\n    1"
        },
        {
          "name": "HealthProfile.record_tool_invocation",
          "line": 63,
          "signature": "def record_tool_invocation(self) -> None",
          "documentation": "Record a tool invocation.\n\nIncrements the tool_invocations counter by one and updates\nthe last_updated timestamp."
        },
        {
          "name": "HealthProfile.record_inference",
          "line": 72,
          "signature": "def record_inference(self, tokens: int) -> None",
          "documentation": "Record an inference call with the given token count.\n\nIncrements the inference_calls counter by one, adds tokens to\nthe inference_tokens total, and updates the last_updated timestamp.\n\nArgs:\n    tokens: The number of tokens consumed by this inference call."
        },
        {
          "name": "HealthProfile.record_error",
          "line": 85,
          "signature": "def record_error(self) -> None",
          "documentation": "Record an error occurrence.\n\nIncrements the error_count counter by one and updates the\nlast_updated timestamp."
        },
        {
          "name": "HealthProfile.update_resources",
          "line": 94,
          "signature": "def update_resources(self, cpu: float, memory: int) -> None",
          "documentation": "Update the point-in-time resource usage metrics.\n\nCPU percentage is clamped to the range [0.0, 100.0].\n\nArgs:\n    cpu: Current CPU usage as a percentage (0.0 to 100.0).\n    memory: Current memory usage in bytes."
        },
        {
          "name": "HealthProfile.update_uptime",
          "line": 107,
          "signature": "def update_uptime(self, seconds: int) -> None",
          "documentation": "Update the uptime counter.\n\nArgs:\n    seconds: The total uptime in seconds since the agent became Running."
        },
        {
          "name": "HealthProfile.record_task_started",
          "line": 116,
          "signature": "def record_task_started(self) -> None",
          "documentation": "Record the start of a new task.\n\nIncrements the active_tasks gauge by one and updates the\nlast_updated timestamp.\n\nANVIL Spec section 14.1 -- Telemetry Contract.\n\nExample:\n    >>> profile = HealthProfile()\n    >>> profile.record_task_started()\n    >>> profile.active_tasks\n    1"
        },
        {
          "name": "HealthProfile.record_task_completed",
          "line": 133,
          "signature": "def record_task_completed(self) -> None",
          "documentation": "Record the completion of a task.\n\nDecrements the active_tasks gauge by one (saturating at zero) and\nincrements the completed_tasks counter by one. Updates the\nlast_updated timestamp.\n\nANVIL Spec section 14.1 -- Telemetry Contract.\n\nExample:\n    >>> profile = HealthProfile()\n    >>> profile.record_task_started()\n    >>> profile.record_task_completed()\n    >>> profile.active_tasks\n    0\n    >>> profile.completed_tasks\n    1"
        },
        {
          "name": "HealthProfile.record_generation_success",
          "line": 155,
          "signature": "def record_generation_success(self) -> None",
          "documentation": "Record a successful generation call.\n\nUpdates generation_success_rate and error_rate based on the\nrunning totals of successes and failures. Updates the\nlast_updated timestamp.\n\nANVIL Spec section 14.1 -- Telemetry Contract.\n\nExample:\n    >>> profile = HealthProfile()\n    >>> profile.record_generation_success()\n    >>> abs(profile.generation_success_rate - 1.0) < 1e-9\n    True"
        },
        {
          "name": "HealthProfile.record_generation_failure",
          "line": 174,
          "signature": "def record_generation_failure(self) -> None",
          "documentation": "Record a failed generation call.\n\nUpdates generation_success_rate and error_rate based on the\nrunning totals of successes and failures. Also increments\nerror_count. Updates the last_updated timestamp.\n\nANVIL Spec section 14.1 -- Telemetry Contract.\n\nExample:\n    >>> profile = HealthProfile()\n    >>> profile.record_generation_failure()\n    >>> abs(profile.error_rate - 1.0) < 1e-9\n    True"
        },
        {
          "name": "HealthProfile.to_dict",
          "line": 201,
          "signature": "def to_dict(self) -> dict[str, Any]",
          "documentation": "Serialize to a dictionary.\n\nReturns:\n    Dictionary representation."
        },
        {
          "name": "HealthProfile.from_dict",
          "line": 225,
          "signature": "def from_dict(data: dict[str, Any]) -> HealthProfile",
          "documentation": "Deserialize from a dictionary.\n\nArgs:\n    data: Dictionary representation.\n\nReturns:\n    The deserialized HealthProfile."
        },
        {
          "name": "HealthProfile.to_json",
          "line": 253,
          "signature": "def to_json(self) -> str",
          "documentation": "Serialize to JSON string."
        },
        {
          "name": "HealthProfile.from_json",
          "line": 258,
          "signature": "def from_json(data: str) -> HealthProfile",
          "documentation": "Deserialize from JSON string."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/health/reporting.py",
      "sha256": "b931bedf00fd2f367ff7cac3a72ef8c988d44030a4b9211c204ac160cfbc7154",
      "artifactSha256": "c79e545566248a868019da8edb8f9ee3134266615bb77430243c9e49471daef0",
      "url": "/reference/source/forge-py/src/forge/health/reporting.py.txt",
      "declarations": [
        {
          "name": "HealthReport",
          "line": 19,
          "signature": "class HealthReport()",
          "documentation": "A structured health report for an agent.\n\nArgs:\n    status: The overall health status.\n    lifecycle_state: The current lifecycle state.\n    profile: The health profile snapshot.\n    agent_did: Optional agent DID.\n    generated_at: When the report was generated."
        },
        {
          "name": "HealthReport.to_dict",
          "line": 36,
          "signature": "def to_dict(self) -> dict[str, Any]",
          "documentation": "Serialize to a dictionary.\n\nReturns:\n    Dictionary representation."
        },
        {
          "name": "HealthReport.to_json",
          "line": 52,
          "signature": "def to_json(self) -> str",
          "documentation": "Serialize to JSON string.\n\nReturns:\n    JSON string representation."
        }
      ]
    }
  ]
}