WIP documentation generation via gh actions (#107)

Summary: Pull Request resolved: #107

Differential Revision: D67157339

.github/workflows/CI.yml

@@ -5,32 +5,60 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest]
     env:
       OS: ${{ matrix.os }}
-      PYTHON: '3.9'
+      PYTHON: "3.10"
     steps:
     - uses: actions/checkout@v4
     - name: Setup Python
       uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: "3.10"
     - name: Install dependencies
       run: |
+          pip install pdoc3
           pip install pytest
           pip install pytest-cov
           pip install -e .
-    - name: Generate coverage report
+    - name: Update documentation
       run: |
-        pytest --cov=./ --cov-report=xml
-    - name: Upload coverage to Codecov
-      if: success() || failure()
-      uses: codecov/codecov-action@v4
-      with:
-        env_vars: OS,PYTHON
-        file: ./coverage.xml
-        flags: unittests
-        name: codecov-umbrella
-        token: ${{ secrets.CODECOV_TOKEN }}
-        slug: facebookresearch/Pearl
-        verbose: true
+        pdoc --html pearl.neural_networks.common --html-dir .html --force
+    - name: Upload docs artifacts
+      uses: actions/upload-artifact@v4
+        with:
+          # Name of the artifact to upload.
+          # Optional. Default is 'artifact'
+          name: artifact
+
+          # A file, directory or wildcard pattern that describes what to upload
+          # Required.
+          path: .html/
+
+          # The desired behavior if no files are found using the provided path.
+          # Available Options:
+          #   warn: Output a warning but do not fail the action
+          #   error: Fail the action with an error message
+          #   ignore: Do not output any warnings or errors, the action does not fail
+          # Optional. Default is 'warn'
+          if-no-files-found: warn
+
+          # If true, an artifact with a matching name will be deleted before a new one is uploaded.
+          # If false, the action will fail if an artifact for the given name already exists.
+          # Does not fail if the artifact does not exist.
+          # Optional. Default is 'false'
+          overwrite: true
+    # - name: Generate coverage report
+    #   run: |
+    #     pytest --cov=./ --cov-report=xml
+    # - name: Upload coverage to Codecov
+    #   if: success() || failure()
+    #   uses: codecov/codecov-action@v4
+    #   with:
+    #     env_vars: OS,PYTHON
+    #     file: ./coverage.xml
+    #     flags: unittests
+    #     name: codecov-umbrella
+    #     token: ${{ secrets.CODECOV_TOKEN }}
+    #     slug: facebookresearch/Pearl
+    #     verbose: true

pearl/api/action_result.py

@@ -23,9 +23,9 @@ class ActionResult:
     reward: Reward
     terminated: bool
     truncated: bool
-    info: dict[str, Any] | None = None
-    cost: float | None = None
-    available_action_space: ActionSpace | None = None
+    info: Optional[dict[str, Any]] = None
+    cost: Optional[float] = None
+    available_action_space: Optional[ActionSpace] = None
 
     @property
     def done(self) -> bool:

pearl/history_summarization_modules/history_summarization_module.py

@@ -26,7 +26,7 @@ class HistorySummarizationModule(ABC, nn.Module):
 
     @abstractmethod
     def summarize_history(
-        self, observation: Observation, action: Action | None
+        self, observation: Observation, action: Optional[Action]
     ) -> SubjectiveState:
         pass
 

pearl/neural_networks/common/epistemic_neural_networks.py

@@ -37,7 +37,7 @@ def __init__(
         super().__init__()
 
     @abstractmethod
-    def forward(self, x: Tensor, z: Tensor) -> Tensor:
+    def forward(self, x: torch.Tensor, z: torch.Tensor) -> torch.Tensor:
         """
         Input:
             x: Feature vector of state action pairs
@@ -71,7 +71,7 @@ def __init__(
         self.prior_net: nn.Module = mlp_block(input_dim, hidden_dims, output_dim).eval()
         self.scale = scale
 
-    def forward(self, x: Tensor) -> Tensor:
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
         """
         Input:
             x: Tensor. Feature vector input
@@ -116,7 +116,7 @@ def __init__(
 
         self._resample_epistemic_index()
 
-    def forward(self, x: Tensor, z: Tensor, persistent: bool = False) -> Tensor:
+    def forward(self, x: torch.Tensor, z: torch.Tensor, persistent: bool = False) -> torch.Tensor:
         """
         Input:
             x: Feature vector of state action pairs
@@ -176,14 +176,14 @@ def generate_params_buffers(self) -> None:
         self.params, self.buffers = torch.func.stack_module_state(self.models)
 
     def call_single_model(
-        self, params: dict[str, Any], buffers: dict[str, Any], data: Tensor
-    ) -> Tensor:
+        self, params: dict[str, Any], buffers: dict[str, Any], data: torch.Tensor
+    ) -> torch.Tensor:
         """
         Method for parallelizing priornet forward passes with torch.vmap.
         """
         return torch.func.functional_call(self.base_model, (params, buffers), (data,))
 
-    def forward(self, x: Tensor, z: Tensor) -> Tensor:
+    def forward(self, x: torch.Tensor, z: torch.Tensor) -> torch.Tensor:
         """
         Perform forward pass on the priornet ensemble and weight by epistemic index
         x and z are assumed to already be formatted.
@@ -235,7 +235,7 @@ def __init__(
             self.input_dim, self.prior_hiddens, self.output_dim, self.index_dim
         )
 
-    def format_xz(self, x: Tensor, z: Tensor) -> Tensor:
+    def format_xz(self, x: torch.Tensor, z: torch.Tensor) -> torch.Tensor:
         """
         Take cartesian product of x and z and concatenate for forward pass.
         Input:
@@ -251,7 +251,7 @@ def format_xz(self, x: Tensor, z: Tensor) -> Tensor:
         xz = torch.cat([x_expanded, z_expanded], dim=-1)
         return xz.view(batch_size * num_indices, d + self.index_dim)
 
-    def forward(self, x: Tensor, z: Tensor, persistent: bool = False) -> Tensor:
+    def forward(self, x: torch.Tensor, z: torch.Tensor, persistent: bool = False) -> torch.Tensor:
         """
         Input:
             x: Feature vector containing item and user embeddings and interactions