V0.2.0

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ main, dev, ci-multi ]
+    branches: [ main, dev, experimental, ci-multi ]
   pull_request:
-    branches: [ main, dev, ci-multi ]
+    branches: [ main, dev, experimental, ci-multi ]
 
 jobs:
   test:
@@ -49,7 +49,7 @@ jobs:
 
     # 6) Set up Python & install dependencies
     - uses: actions/setup-python@v5
-      with: { python-version: "3.9" }
+      with: { python-version: "3.10" }
     - name: Install Python deps
       run: |
         pip install -e .

.github/workflows/python-app.yml

@@ -19,10 +19,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python 3.9
+    - name: Set up Python 3.10
       uses: actions/setup-python@v3
       with:
-        python-version: "3.9"
+        python-version: "3.10"
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

CONTRIBUTING.md

@@ -1,27 +1,69 @@
-# Contribution Guide
+# Contribution Guideline
 
-Trace is an actively growing project and under active maintenance and development! We welcome your contributions and involvement. Below are instructions for how to contribute to Trace.
+Trace is an actively growing project and under active maintenance and development! We maintain two major branches `main` and `experimental`. The `main` branch is the most stable, version-controlled branch and it is what the PyPI package is linked to.  On the other hand, the `experimental` branch is the dev branch, which will change more dynamically in preparation for the next version update. 
+
+### Development and Review Process
+
+Contribution to these two branches requires going through a review process via PR and passing all unit tests in CI. 
+Merging a PR requires at least one reviewer different from the contributor, except for those marked as [**LIGHT**] below. 
+
+Here is an outline: 
+
+1. `main` will be regularly updated by PRs based on the development of the `experimental` branch following the [roadmap doc](https://docs.google.com/spreadsheets/d/1dMoECd2Soj6bATpkNDeaMxl0ymOYCtGq7ZiHr0JRdJU/edit?usp=sharing). Each update will result in a version update.
+
+2. Except for the planned roadmap, `main` will only be updated to fix bugs.  Bug fix to what is in `main` should be submitted as PR to `main`. This will trigger a quicker review (< 3 days) and result in a version update in the third digit, and the `experimental` branch will then rebase on the updated `main`.
+
+3. For feature development, PR should be submitted to the `experimental` branch without version update. Generally, the `experimental` branch aims to realize the milestones listed in the next version update in the [roadmap doc](https://docs.google.com/spreadsheets/d/1dMoECd2Soj6bATpkNDeaMxl0ymOYCtGq7ZiHr0JRdJU/edit?usp=sharing). If applicable, new determinstic unit tests should be added under `tests/unit_tests`, or an example run script should be added in `examples`.
+
+4. [**LIGHT**]  Bugs fix to the new changes introduced in the `experimental` branch should be submitted as a PR to the `experimental` branch. This PR will be incoporated quickly with a light review. 
+
+5. [**LIGHT**]  For contributions under the directory `opto/features`, they should be submitted as PR to the `experimental` branch. These usually are not under roadmap and are content not made as dependable by codes in other directories. That is, contents under `opto/features/A` should not be imported by files other than those under `opto/features/A`. So long as this rule is met, the PR will be incorprated under a light review.
+
+6. Updates to non-coding elements (like documents) do not require a PR.
+
+The above is applicable to all contributors, including the core contributors and maintainers.
+
+In a regular development cycle, all features and bug fixes are merged into the experimental branch. After the items listed in the [roadmap doc](https://docs.google.com/spreadsheets/d/1dMoECd2Soj6bATpkNDeaMxl0ymOYCtGq7ZiHr0JRdJU/edit?usp=sharing) are all added to the `experimental` branch, a version branch (e.g., `v0.2.1`) will be created from `experimental`, and it will be staged for a release (to be merged into the `main` branch with a PR). At this point, the version number of the `experimental` branch will be updated to start the development of the next version.
+
+![workflow](https://github.com/AgentOpt/Trace/blob/experimental/docs/images/contributing_workflow.png?raw=true)
+
+### Communication
+
+1. Quick questions should be posted on Discord channel.
+
+2. For bugs, feature requests, contributions, or questions that might be related to a broader audience, post them as issues on the github page.
+
+### Other Branches
+
+In addition to `main` and `experimental`, other branches have a naming convention or `vx.x.x` for version branchs, or of `feature/xxx` or `fix/xxx`, which implements the items on the roadmap. They will be merged into the `main` or `experimental` accordingly following the rules above. Once merged, they will be removed.
+
+
+# Steps for Contributions
+
+We welcome your contributions and involvement. Below are instructions for how to contribute to Trace.
 
 ## Quick Bug Fix
 
-If there is a minor, isolated bug that can be directly fixed, the bug fix should be submitted as a pull request and will be merged into the `main` branch. 
+If there is a minor, isolated bug that can be directly fixed, please report it as an issue or submit a PR to be merged into the `main` branch or `experimental` branch, depending on where the issue arises.
+
 
 ## Contributing Feature
 
 We welcome new ideas. 
 
-### Step 1: Feature Spec Doc 
-A feature should first be written as a Google Doc (an example is [here](https://docs.google.com/document/d/1FX1ygc8lgFpFn3ni3E2A_DCGtn505PpAM8QaAjEovsA/edit?usp=sharing)).
+### Step 1: Create an Issue
 
-### Step 2: Create an Issue
-An issue should be created, and under the issue, the doc is linked. People should be allowed to comment on the doc.
+If your changes are expected to involve in less 50 lines of codes, create an issue titled "[LIGHT] XXX". You should describe the motivation, give an overview of the change (e.g., by a pseudo-code) and its desired effects. Otherwise, create an issue titled "[MAJOR] XXX". You should write a more detailed description of your motivation, design, and demo. If more space is needed, you can attach a link to a Google doc. People should be allowed to comment on the doc.
 
-### Step 3: Implement Feature
-Create a separate branch, extending from the `experimental` branch. This branch contains all the new features that have not been merged into the `main` branch yet. 
+### Step 2: Implement Feature
+
+Create a separate branch, extending from the `experimental` branch, which contains all the new features that have not been merged into the `main` branch yet. 
 Make sure your features are implemented, along with `unit tests` or `examples` to show how it's used.
 
-### Step 4: Create a Pull Request
-Create a pull request formally to merge into the experiment branch and request a review. This is a lightweight review that only checks for malicious code, or if the feature does not pass its own unit tests.
+### Step 3: Create a Pull Request
+
+Create a PR formally to merge into the experiment branch and request a review. For standalone features, put the changes under `opto/features/`. This will trigger the lightest review that only checks for malicious code, or if the feature does not pass its own unit tests. For changes to the rest, expect a slightly longer review process as we work out how the changes should be integrated with the core library. Also, [LIGHT] issues can expect faster review than [MAJOR].
 
-### Step 5: Merge into Experimental
+### Step 4: Merge into Experimental
 Once the request is approved, it will be merged into the `experimental` branch.
+

OVERVIEW.md

@@ -1,32 +1,57 @@
 # Overview of Trace and Development Guide
 
-The library of Trace is designed to be a lightweight, modularized package to allow developers to easily try new ideas on generative optimization and integrate learning wtih their pipelines. 
-
-Currently, the Trace library has three main modules collected under the `opto` top module. 
-
-1. `opto.trace` provides the infrastructure for tracing computational workflows. It defines two primitives `trace.node` and `@trace.bundle`. They can be applied to Python objects and methods, respectively, which define the root nodes and operators of the directed acyclic graph (DAG) of computation. They both have a `trainable` flag. When set `True`, the wrapped objects are viewed as *parameters* of the computational worflow. Users can use `trace.node` and `@trace.bundle` to declare the data and computation that they wish to trace and/or adapt, and we call the resulting workflow defined by these two primitives a *traced* workflow. When running a traced workflow, a DAG will be automatiically created by Trace as a data structure, which will later be sent to optimizers in `opto.optimizers`for updates (upon calling `node.backward` with soem feedback).
-
-2. `opto.optimizers` has a collection of generative optimization algorithms, whose API is defined by an abstract class `Optimizer`. Think them like gradient algorithms. Their job is to propose a new version of the parameters (i.e. those set with `trainable=True`) when receiving a computational graph (DAG) and the feedback given to the computed output. Typically, these algorithms can be viewed as an LLM agent, which makes calls to LLM to analyze the computational graph and the feedback, and to propose updates. In Trace library, we provide implementation of several popular optimizers, such `OptoPrime`, `TextGrad`, and `OPRO`.
-
-3. `opto.trainers` are a collection of training algorithms (under the `AlgorithmBase` class) that use optimizers in `opto.optimizers` as subroutines to improve a given workflow following a feedback oracle constructed by datasets, interactive environments, etc. While `Optimizer` defines a low-level *optimization* API, `AlgorithmBase` defines a high-level *learning* API which standarizes the format of agent (by the `Module` class created by `@trace.model`), the data loader (by the `DataLoader` class), and the feedback oracle (by the `AutoGuide` class). With this common abstraction, we offer training algorithms, from the basic `MinibatchAlgorithm` which trains minibatches of samples to search algorithms like `BeamSearch`. The `AlgorithmBase` also handles logging of the training process. While there are overlapping between the functions of `Optimizer` and `AlgorithmBase`, the main distinction is that algorithms under `AlgorithmBase` are meta algorithms, as they should work for different optimizers in `opto.optimizers`.
-
-
-4. `opto.utils` has a collection of helper functions and backends, which are reusable for various applications. This includes, e.g., abstraction of LLMs, database, etc. Making use of all these utils would requie installing optional depedencies.
-
-
-In summary, `opto.trace` is the infrastructure, `opto.optimizers` are algorithms that process feedback and propose new parameter candidates, and `opto.trainers` are algorithms built on top of `opto.trace` and `opto.optimizers` to train learning agents.
-
-## Common Workflow of Using Trace
-
-1. Use `trace.node` and `@trace.bundle` to define the traceable workflow and its trainable parameter. 
-2. Wrap the workflow as a `trace.Module` using `@trace.model`
-3. Create a dataloader using `DataLoader` and define the feedback oracle (an analogy of loss function) using `AutoGuide`. 
-4. Create a trainer from `opto.trainers` using optimizers from `opto.optimizers` and the above module, dataloader, and feedback oracle.
+The Trace library is a lightweight, modular package designed to allow developers to experiment easily with generative optimization and integrate feedback-driven learning into their computational workflows.
+The library has four modules within the `opto` top-level namespace:
+
+1. `opto.trace` provides the infrastructure for converting executing Python code into symbolic directed acyclic graphs (DAGs). 
+It defines two tracing primitives:
+    - `trace.node`: Wraps Python objects, designating them as nodes within the computational graph.
+    - `@trace.bundle`: Decorates Python methods/functions, marking them as operators within the graph.
+
+Each primitive has a `trainable` flag. 
+When set to `True`, these marked nodes and bundles become the trainable *parameters* of the workflow.
+By using these primitives, developers can create a *traced workflow* represented as a DAG.
+This DAG structure is automatically constructed at runtime, capturing both computational dependencies and trainable parameters, ready for optimization.
+
+2. `opto.optimizers` has an abstract class `Optimizer` that defines algorithms that take computation DAGs and associated feedback objects as input, and output values for the trainable parameters.
+These algorithms are analogous to gradient-based optimizers in PyTorch, but are typically implemented as generative optimization agents, leveraging LLMs to analyze feedback and propose parameter updates.
+We provide implementations of several generative optimizers:
+    - `OptoPrime`
+    - `TextGrad`
+    - `OPRO`
+
+3. `opto.trainers` has the `AlgorithmBase` abstraction that orchestrates the overall training process.
+Trainers manage data handling, tracing control, feedback collection, optimizer invocation, and iterating/stopping. Specifically, a trainer:
+    - Controls data sampling (via `DataLoader`).
+    - Determines when DAGs are constructed and when feedback (e.g. via `AutoGuide`) is collected .
+    - Invokes `optimizers` for parameter updates, possibly repeatedly and manages the training loop.
+    - Logs training progress.
+
+Although `optimizers` handle lower-level optimization decisions, trainers under `AlgorithmBase` manage broader training logic and are designed to be compatible across various `optimizers`.
+We provide implementations of common trainers: `MinibatchAlgorithm`(basic minibatch training) and `BeamSearch` (example of search-based training).
+
+4. `opto.utils` has a collection of reusable helper functions and backend utilities, including abstraction for:
+    - Large Language Models (LLMs)
+    - Databases
+    - Miscellaneous support tools.
+
+Note: Some utilities might require installing optional depedencies.
+
+## Concise Summary of Abstractions
+  - `trace`: Infrastructure to construct symbolic computational DAGs
+  - `optimizers`: Receive DAG and feedback, output parameter values.
+  - `trainer`: Manages DAG construction, data sampling, feedback collection, optimizer invocation, and training workflow control.
+
+## Common Workflow for Using Trace
+
+1. Define a traceable workflow with `trace.node` and `@trace.bundle`, marking trainable parameters. 
+2. Wrap this workflow into a `trace.Module` with `@trace.model`.
+3. Define a dataloader (`DataLoader`) and feedback oracle (analogous to a loss function, using e.g. `AutoGuide`). 
+4. Instantiate a trainer from `opto.trainers`, specifying the optimizer from `opto.optimizers` alongside the defined module above, dataloader, and feedback oracle.
 5. Run the trainer. 
 
-
-## Common Workflow of Improving Trace
-- **Developing new optimization agent** Contribute to `trace.optimizers` and design new algorithms under `Optimizer`
-- **Developing new learning algorithms** Contribute to `trace.trainers` (and `trace.optimizers` when necessary). Design new algorithms under `AlgorithmBase`, new dataloader under `DataLoader`, or new feedback oracle under `AutoGuide`. 
-- **Improving infrastructure**  Propose updates to change `opto.trace` (e.g., to improve UI, add new tracing, etc.)
-- **Onboarding other utility tools** Add to `opto.utils` and update `setup.py` with optional requirements.
+## Guidelines for Improving and Extending Trace
+  - **New optimization agents**: Contribute to `opto.optimizers`, sub-class from the `Optimizer` abstraction.
+  - **New learning algorithms**: Contribute to `opto.trainers` (and optionally `opto.optimizers` if necessary). Design new algorithms sub-classing `AlgorithmBase`, new dataloader under `DataLoader`, or new feedback oracle under `AutoGuide`. 
+  - **Improving infrastructure**: Propose modifications to `opto.trace` to improve tracing capability, user experience, or additional functionality.
+  - **Onboarding other utility tools**: Add helpful tools to `opto.utils` and update `setup.py` accordingly for optional dependencies.