Merge pull request #101 from probcomp/mkdocs_branch

Mkdocs branch

.github/workflows/docs.yml

@@ -1,24 +1,46 @@
-name:                  Docs
+name:                  Doc
 
 on:
   push:
-    branches:          [main]
+    branches:
+      - main
+      - mkdocs_branch
   pull_request:
-    branches:          [main]
+    branches:
+
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
 
 jobs:
-  run_tests:
-    runs-on:           ubuntu-latest
+  build-deploy:
+    runs-on: ubuntu-latest
+
     steps:
-      # - name:          free disk space
-      #   uses:          jlumbroso/[email protected]
-      - name:          checkout repo
-        uses:          actions/[email protected]
-        with:
-          fetch-depth: 1
-      - name:          check docs build
-        run: |
-                      python -m venv venv
-                      source venv/bin/activate
-                      pip install --upgrade pip "setuptools>=62.4"
-                      make docs
+    - name: Check out repository
+      uses: actions/checkout@v4
+
+    - name: Install dependencies
+      run: |
+        python -m venv venv
+        source venv/bin/activate
+        pip install --upgrade pip "setuptools>=62.4"
+
+    - name: Build docs
+      run: |
+        make mkdocs
+
+    - name: Upload docs
+      uses: actions/upload-artifact@v4
+      with:
+        name: mkdocs-site
+        path: site/
+
+  publish:
+    needs: build-deploy
+    name: Deploy to private site
+    uses: probcomp/gen-website-private/.github/workflows/publish_private_website.yml@main
+    with:
+      artifact: mkdocs-site

NOTICE.txt

@@ -2,3 +2,25 @@ GenParse
 Copyright 2024 The Computation and Human Intelligence Focused Research Organization
 
 This product includes software developed at the Computation and Human Intelligence Focused Research Organization.
+
+This project includes dependencies with the following licenses:
+1. Arsenal - GNU General Public License v3.0
+2. FrozenDict - MIT License
+3. Graphviz - MIT License
+4. Interegular - MIT License
+5. IPython - BSD 3-Clause "New" or "Revised" License
+6. Jsons - MIT License
+7. Lark - MIT License
+8. NLTK - Apache 2.0 License
+9. NumPy - (Appears to be)BSD License
+10. Pandas - BSD 3-Clause "New" or "Revised" License
+11. Path - MIT License
+12. Rich - MIT License
+13. NumBa - BSD 2-Clause "Simplified" License
+14. Torch (PyTorch) - A BSD-"style" license
+15. Transformers - Apache 2.0 License
+16. Plotly - MIT License
+17. Maturin - Apache 2.0 License OR MIT License
+18. Psutil - BSD 3-Clause "New" or "Revised" License
+19. MkDocs - BSD 2-Clause "Simplified" License
+20. MKDocs Material - MIT License

docs/contributing.md

@@ -1,9 +1,46 @@
-## Contributing
+## Development
 
+After installation, you can use the following commands for development:
+
+- `make help`: Print available commands
+- `make update`: Update the repository from GitHub
+- `make format`: Format code style using ruff
+- `make docs`: Builds auto-generated API documentation using pdoc
+- `make mkdocs`: Build full documentation using mkdocs
+- `make test`: Run linting (ruff) and tests (pytest with coverage)
+
+## Testing
 Before pushing a new commit, always run:
 
 ```bash
 make test
 ```
 
 This will run all tests and ensure code quality.
+
+## Documentation
+
+To build the auto-generated API documentation, run:
+
+```bash
+make docs
+```
+
+To build the mkdocs documentation, run:
+
+```bash
+make mkdocs
+```
+
+> **💡Tip**: Note that the documentation index is symlinked from the README.md file. If you are on a Windows machine you will need to manually symlink the README.md file to docs/index.md before building the docs.
+
+mkdocs takes documentation in the /docs directory and builds a static html version of it, which it puts into /site. When PRs are approved and merged the docs are rebuilt by a github action and deployed to the [genparse.gen.dev](https://genparse.gen.dev) domain. 
+
+If you want to test the docs on your own branch, run:
+
+```bash
+serve mkdocs
+```
+The results will be served at [localhost:8000](http://localhost:8000).
+
+You can test a deployed version of the docs by pushing to a branch called mkdocs-branch. The github action will automatically deploy the branch to the genparse.dev domain. You can view the results of the action on github and also rerun the action there. 

docs/getting_started.md

@@ -0,0 +1,124 @@
+GenParse currently provides a high-level interface for constrained generation via the `InferenceSetup` class. We recommend using this class as its internals may be deprecated without prior warning. 
+
+```python
+from genparse import InferenceSetup
+```
+
+## 1. Define your grammar 
+
+GenParse uses Lark syntax for grammar specification. For example:
+
+```python
+grammar = """
+start: WS? "SELECT" WS column WS from_clause (WS group_clause)?
+from_clause: "FROM" WS table
+group_clause: "GROUP BY" WS column
+column: "age" | "name"
+table: "employees"
+WS: " "
+"""
+```
+
+For a comprehensive guide on how to write grammars using Lark syntax, please refer to the [official Lark documentation](https://lark-parser.readthedocs.io/en/latest/grammar.html).
+
+> **💡Tip:** GenParse supports grammars with arbitrary regular expressions. In practice, we recommend avoiding extremely permisive regular expressions (e.g., `/.+/`) since these will lead to significantly slower inference. See [issue #62](https://github.com/probcomp/genparse/issues/62).
+
+## 2. Create an `InferenceSetup` object
+
+Create an `InferenceSetup` object with your chosen language model and grammar:
+
+```python
+setup = InferenceSetup('gpt2', grammar)
+```
+
+`InferenceSetup` requires the following arguments:
+
+- **model_name** (str): Name of the language model to use. See the README for the list of models currently supported by GenParse.
+- **grammar** (str): The grammar specification in Lark format.
+
+
+It accepts the following optional arguments:
+
+- **proposal_name** (str): The type of proposal to use. Options include 'character' and 'token'. Default is 'character'.
+- **num_processes** (int): The number of processes to use for parallel proposals. This can help speed up the inference process by utilizing multiple CPU cores. Default: min(mp.cpu_count(), 2)
+- **use_rust_parser** (bool): Whether to use the Rust implementation of the Earley parser for faster inference. If False, the Python implementation is used. Default to True.
+- **use_vllm** (bool or None): Whether to use VLLM for LLM next token probability computations. If None, VLLM is used when possible (i.e., if the vllm library is available and CUDA is enabled). Default is None.
+- **seed** (int or None): A random seed for reproducibility. If provided, it ensures that the inference process is deterministic.
+- **guide_opts** (dict or None): Additional options for the guide, which may include specific configurations for the grammar-based model.
+- **proposal_opts** (dict or None): Additional options for the proposal mechanism, such as parameters specific to the proposal type (e.g., K for token proposal).
+- **llm_opts** (dict or None): Additional options for the language model, such as temperature or top-p settings for sampling.
+- **vllm_engine_opts** (dict or None): Additional options for the VLLM engine, such as data type (dtype). These options are ignored if VLLM is not used.
+
+
+> **💡Tip:** To try different grammars without having to instantiate new `InferenceSetup` objects each time, use the `update_grammar` method; `setup.update_grammar(new_grammar)` will replace the existing grammar in `setup` with `new_grammar`.
+
+
+## 3. Run inference
+
+Use the setup object to run SMC inference:
+
+```python
+# The result is a ParticleApproximation object
+result = setup('Write an SQL query:', n_particles=10, verbosity=1, max_tokens=25)
+```
+
+When calling `InferenceSetup`, the following arguments are required:
+
+- **prompt** (str): The input prompt to generate samples from. This is the starting text for the language model.
+- **n_particles** (int): The number of particles (samples) to generate.
+
+There are the following optional arguments:
+
+- **method** (str): The sampling method to use. Options include 'smc' for Sequential Monte Carlo and 'is' for importance sampling. Default to 'smc'.
+* **max_tokens** (int): The maximum number of tokens to generate. Defaults to 500.
+
+The following optional arguments are passed in as **kwargs**, which may be expanded over time:
+
+- **potential** (Callable): A function that when called on a list of particles, returns a list with the log potential values for each particle. Potentials can be used to guide generation with additional constraints. See below for an overview of potential functions.
+- **ess_threshold** (float): Effective sample size below which resampling is triggered, given as a fraction of **n_particles**. Default is 0.5.
+* **verbosity** (int): Verbosity level. When > 0, particles are printed at each step. Default is 0.
+- **return_record** (bool): Flag indicating whether to return a record of the inference steps. Default is False.
+- **resample_method** (str): Resampling method to use. Either 'multinomial' or 'stratified'. Default is 'multinomial'.
+
+The result from `InferenceSetup` is a `ParticleApproximation` object. This object contains a collection of particles, each representing a generated text sequence. Each particle has two main attributes:
+
+- `context`: The generated text sequence.
+- `weight`: A numerical value representing the particle's importance weight. The weights are not normalized probabilities. GenParse provides post-processing to convert these weights into meaningful probabilities, which can be accessed via the `.posterior` property:
+```python
+>>> result.posterior
+{"SELECT name FROM employees GROUP BY name▪" : 1}
+```
+
+## 4. Potential functions
+
+> **💡 Tip:** Incorporate constraints directly into the grammar when possible, as this will generally improve the quality of inference.
+
+Potential functions can be used to guide generation using additional constraints. A potential function maps (partial) generations to positive real numbers, with higher values indicating a stronger preference for those generations. Intuitively, when applied in SMC, potential functions offer richer signals for resampling steps, allowing computation to be redirected toward more promising particles during the course of generation.
+
+Potentials are provided as input to an `InferenceSetup` call via the `potential` argument and must be defined at the particle beam level. That is, `InferenceSetup` expects potentials to be callables which are provided a *list* of particles as input and return a *list* of log potential values, one for each particle. 
+
+## 5. Visualizing inference
+
+GenParse additionally provides methods to visualize inference runs. To display the visualization of an inference run:
+
+1. Specify `return_record=True` when calling `InferenceSetup`:
+
+```python
+result = setup(' ', n_particles=10, return_record=True)
+```
+
+2. Save the SMC record in `notes/smc_viz/`:
+
+```python
+import json
+with open('notes/smc_viz/record.json', 'w') as f:
+      f.write(json.dumps(result.record))
+```
+
+3. Run a server in `notes/smc_viz/`:
+
+```bash
+python -m http.server --directory notes/smc_viz 8000
+```
+
+4. Navigate to [localhost:8000/](http://localhost:8000/).