Add pytest-cov and improve error messages with actionable guidance

- Add pytest-cov to dev dependencies for coverage reporting
- Improve ValueError/RuntimeError messages across the codebase to include
  actionable guidance: what went wrong, why, and how to fix it
- Files updated: arguments.py, function.py, table_function.py,
  table_in_out_function.py, worker.py

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rustyconover

pyproject.toml

@@ -7,7 +7,7 @@ requires-python = ">=3.12.4"
 dependencies = ["click", "pyarrow", "structlog", "platformdirs"]
 
 [project.optional-dependencies]
-dev = ["mypy", "pyarrow-stubs", "pytest", "pytest-mypy", "pytest-ruff", "pytest-xdist", "ruff"]
+dev = ["mypy", "pyarrow-stubs", "pytest", "pytest-cov", "pytest-mypy", "pytest-ruff", "pytest-xdist", "ruff"]
 
 [project.scripts]
 vgi-client = "vgi.client.cli:main"

uv.lock

@@ -518,7 +518,12 @@ def __get__(
 
         # Instance access - parse and cache
         if self._name is None:
-            raise RuntimeError("Arg descriptor was not properly initialized")
+            raise RuntimeError(
+                "Arg descriptor was not properly initialized. "
+                "This typically means the descriptor was accessed before __set_name__ "
+                "was called. Ensure Arg is used as a class attribute, not instantiated "
+                "dynamically."
+            )
 
         if self._name not in obj.__dict__:
             obj.__dict__[self._name] = self._resolve(obj)
@@ -528,7 +533,12 @@ def _resolve(self, obj: object) -> ArgT:
         """Parse argument from obj.invocation.arguments and validate."""
         invocation = getattr(obj, "invocation", None)
         if invocation is None:
-            raise RuntimeError("Object does not have 'invocation' attribute")
+            raise RuntimeError(
+                f"Cannot resolve Arg '{self._name}': object {type(obj).__name__} does "
+                f"not have an 'invocation' attribute. Arg descriptors can only be used "
+                f"on classes that have an 'invocation' attribute (e.g., "
+                f"TableInOutFunction, TableFunctionGenerator)."
+            )
         arguments = invocation.arguments
 
         if self.default is _MISSING:

vgi/arguments.py

@@ -944,7 +944,13 @@ def process(self, batch: pa.RecordBatch) -> OutputGenerator:
 
         """
         if self.init_identifier is None:
-            raise ValueError("init_identifier must be set before storing state")
+            raise ValueError(
+                "init_identifier must be set before storing state. "
+                "This is typically set automatically during perform_init() or "
+                "retrieve_init(). Ensure your function calls super().perform_init() "
+                "in perform_init(), or that the worker correctly calls "
+                "retrieve_init() for secondary workers."
+            )
         self.state_storage.store(
             self.init_identifier,
             os.getpid(),
@@ -977,7 +983,13 @@ def finalize(self) -> OutputGenerator:
 
         """
         if self.init_identifier is None:
-            raise ValueError("init_identifier must be set before collecting states")
+            raise ValueError(
+                "init_identifier must be set before collecting states. "
+                "This is typically set automatically during perform_init() or "
+                "retrieve_init(). Ensure your function calls super().perform_init() "
+                "in perform_init(), or that the worker correctly calls "
+                "retrieve_init() for secondary workers."
+            )
         state_bytes_list = self.state_storage.collect_and_delete(self.init_identifier)
         return [state_class.deserialize(data) for data in state_bytes_list]
 
@@ -1008,7 +1020,11 @@ def perform_init(self, init_input: pa.RecordBatch) -> GlobalInitResult:
 
         """
         if self.init_identifier is None:
-            raise ValueError("init_identifier must be set before enqueuing work")
+            raise ValueError(
+                "init_identifier must be set before enqueuing work. "
+                "Call enqueue_work() after perform_init() has completed, typically "
+                "at the end of your perform_init() override or in setup()."
+            )
         return self.state_storage.enqueue_work(self.init_identifier, work_items)
 
     def dequeue_work(self) -> bytes | None:
@@ -1038,5 +1054,11 @@ def process(self) -> OutputGenerator:
 
         """
         if self.init_identifier is None:
-            raise ValueError("init_identifier must be set before dequeuing work")
+            raise ValueError(
+                "init_identifier must be set before dequeuing work. "
+                "This is typically set automatically during perform_init() or "
+                "retrieve_init(). Ensure your function calls super().perform_init() "
+                "in perform_init(), or that the worker correctly calls "
+                "retrieve_init() for secondary workers."
+            )
         return self.state_storage.dequeue_work(self.init_identifier)

vgi/function.py

@@ -383,7 +383,12 @@ def perform_init(self, init_input: pa.RecordBatch) -> vgi.function.GlobalInitRes
     def retrieve_init(self, init_input: vgi.function.GlobalInitResult) -> None:
         """Retrieve and store init data from the storage."""
         if init_input.global_init_identifier is None:
-            raise ValueError("global_init_identifier is required but was None")
+            raise ValueError(
+                "global_init_identifier is required but was None. "
+                "This indicates the GlobalInitResult was not properly initialized. "
+                "Ensure perform_init() returns a GlobalInitResult with a valid "
+                "identifier."
+            )
         self.init_identifier = init_input.global_init_identifier
         self.init_data = GlobalStateInitInput.deserialize_bytes(
             self.init_storage.get(self.init_identifier)

vgi/table_function.py

@@ -554,7 +554,13 @@ def __init__(
         """Initialize the function with invocation data and logger."""
         super().__init__(invocation=invocation, logger=logger)
         if invocation.in_out_function_input_schema is None:
-            raise ValueError("Function requires a non-null input schema")
+            raise ValueError(
+                f"{type(self).__name__} requires an input schema, but none was "
+                f"provided. TableInOutGeneratorFunction processes input batches and "
+                f"requires in_out_function_input_schema to be set in the Invocation. "
+                f"If your function generates output without input, inherit from "
+                f"TableFunctionGenerator instead."
+            )
 
     @property
     def input_schema(self) -> pa.Schema:

vgi/table_in_out_function.py

@@ -295,7 +295,11 @@ def _process_batches(
 
         """
         if invocation.global_init_identifier is None:
-            raise ValueError("global_init_identifier is required but was None")
+            raise ValueError(
+                "global_init_identifier is required but was None. "
+                "This is an internal protocol error - the worker should have set "
+                "global_init_identifier after perform_init() completed successfully."
+            )
         generator = instance.run()
         next(generator)  # Prime the run() generator
 
@@ -474,7 +478,10 @@ def run(self) -> None:
         else:
             raise TypeError(
                 f"Unsupported function type: {type(instance).__name__}. "
-                f"Expected TableInOutGeneratorFunction or TableFunctionGenerator."
+                f"Functions must inherit from TableInOutGeneratorFunction (for "
+                f"functions that process input batches) or TableFunctionGenerator "
+                f"(for functions that generate output without input). "
+                f"See vgi.table_in_out_function and vgi.table_function modules."
             )
 
         fn_log.info(