From f9b5acd758028e683b62ac2ee0e4225d273e1724 Mon Sep 17 00:00:00 2001
From: Ed_ <edwardgz@gmail.com>
Date: Sat, 2 May 2026 13:08:47 -0400
Subject: [PATCH] refactor(api): Audit and cleanup api_hook_client.py and
 api_hooks.py

---
 src/api_hook_client.py | 9 +++++++++
 src/api_hooks.py       | 6 ++++++
 2 files changed, 15 insertions(+)

diff --git a/src/api_hook_client.py b/src/api_hook_client.py
index 1480df4..3f504a5 100644
--- a/src/api_hook_client.py
+++ b/src/api_hook_client.py
@@ -83,6 +83,7 @@ class ApiHookClient:
   return res
 
  def post_project(self, project_data: dict) -> dict[str, Any]:
+  """Updates the current project configuration."""
   return self._make_request('POST', '/api/project', data=project_data) or {}
 
  def get_project(self) -> dict[str, Any]:
@@ -98,10 +99,12 @@ class ApiHookClient:
   return self._make_request('POST', '/api/session', data={"session": {"entries": session_entries}}) or {}
 
  def get_events(self) -> list[dict[str, Any]]:
+  """Retrieves any pending events from the API event queue."""
   res = self._make_request('GET', '/api/events')
   return res.get("events", []) if res else []
 
  def clear_events(self) -> list[dict[str, Any]]:
+  """Retrieves and clears the event queue."""
   return self.get_events()
 
 
@@ -241,20 +244,26 @@ class ApiHookClient:
   return self._make_request('GET', '/api/patch/status') or {}
 
  def spawn_mma_worker(self, data: dict) -> dict:
+  """Spawns a new MMA worker with the provided configuration."""
   return self._make_request('POST', '/api/mma/workers/spawn', data=data) or {}
 
  def kill_mma_worker(self, worker_id: str) -> dict:
+  """Kills an active MMA worker by its ID."""
   return self._make_request('POST', '/api/mma/workers/kill', data={"worker_id": worker_id}) or {}
 
  def pause_mma_pipeline(self) -> dict:
+  """Pauses the MMA execution pipeline."""
   return self._make_request('POST', '/api/mma/pipeline/pause') or {}
 
  def resume_mma_pipeline(self) -> dict:
+  """Resumes the MMA execution pipeline."""
   return self._make_request('POST', '/api/mma/pipeline/resume') or {}
 
  def inject_context(self, data: dict) -> dict:
+  """Injects custom file context into the application."""
   return self._make_request('POST', '/api/context/inject', data=data) or {}
 
  def mutate_mma_dag(self, data: dict) -> dict:
+  """Mutates the MMA DAG (Directed Acyclic Graph) structure."""
   return self._make_request('POST', '/api/mma/dag/mutate', data=data) or {}
 
diff --git a/src/api_hooks.py b/src/api_hooks.py
index 239a110..ad52460 100644
--- a/src/api_hooks.py
+++ b/src/api_hooks.py
@@ -42,6 +42,7 @@ See Also:
 """
 
 def _get_app_attr(app: Any, name: str, default: Any = None) -> Any:
+ """Retrieves an attribute from the App or its Controller."""
  if hasattr(app, name):
   val = getattr(app, name)
   return val
@@ -51,11 +52,13 @@ def _get_app_attr(app: Any, name: str, default: Any = None) -> Any:
  return default
 
 def _has_app_attr(app: Any, name: str) -> bool:
+ """Checks if an attribute exists on the App or its Controller."""
  if hasattr(app, name): return True
  if hasattr(app, 'controller') and hasattr(app.controller, name): return True
  return False
 
 def _set_app_attr(app: Any, name: str, value: Any) -> None:
+ """Sets an attribute on the App or its Controller."""
  if hasattr(app, name):
   setattr(app, name, value)
  elif hasattr(app, 'controller'):
@@ -66,10 +69,12 @@ def _set_app_attr(app: Any, name: str, value: Any) -> None:
 class HookServerInstance(ThreadingHTTPServer):
  """Custom HTTPServer that carries a reference to the main App instance."""
  def __init__(self, server_address: tuple[str, int], RequestHandlerClass: type, app: Any) -> None:
+  """Initializes the server instance with an app reference."""
   super().__init__(server_address, RequestHandlerClass)
   self.app = app
 
 def _serialize_for_api(obj: Any) -> Any:
+ """Serializes complex objects into API-friendly formats (dicts/lists)."""
  if hasattr(obj, "to_dict"):
   return obj.to_dict()
  if isinstance(obj, list):
@@ -81,6 +86,7 @@ def _serialize_for_api(obj: Any) -> Any:
 class HookHandler(BaseHTTPRequestHandler):
  """Handles incoming HTTP requests for the API hooks."""
  def do_GET(self) -> None:
+  """Handles GET requests by routing to the appropriate state provider."""
   try:
    app = self.server.app
    session_logger.log_api_hook("GET", self.path, "")