Skip to content

armgit / burr

Public Imported from GitHub
0

Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.

Adds example stubbs to code for ml & simulation

Stefan Krawczykdc8043809ff5
diff --git a/examples/ml-training/README.md b/examples/ml-training/README.md
index 7cfd49ee..ff588aa2 100644
--- a/examples/ml-training/README.md
+++ b/examples/ml-training/README.md
@@ -42,4 +42,6 @@ but that task executor does not need to be complicated (all it needs to do is ru
Similar to epoch training, hyperparameter training can be modeled as a state machine. The system makes a decision about what
to look for next based on the prior results. Furthermore, one can model a step that handles multiple jobs, keeping them alive/
-launching new ones as they compleete (based on state).
+launching new ones as they complete (based on state).
+
+For a sketch of the latter see [application.py](./application.py) & ![diagram](./statemachine.png).
diff --git a/examples/ml-training/application.py b/examples/ml-training/application.py
new file mode 100644
index 00000000..7c36d080
--- /dev/null
+++ b/examples/ml-training/application.py
@@ -0,0 +1,141 @@
+"""
+This is a stubb out example of a machine learning training pipeline using Burr where you
+want to do something dynamic like train a model for a variable number of iterations and then
+pick the best model from each of the iterations based on some validation metric.
+
+You could adjust this example to continue training a model until you reach a certain validation metric,
+or hit a max number of iterations (or epochs), etc.
+
+Note: this example uses the class based API to define the actions. You could also use the function+decorator API.
+"""
+import burr.core.application
+from burr.core import Action, Condition, State, default
+
+
+class ProcessDataAction(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["data_path"]
+
+ def run(self, state: State, **run_kwargs) -> dict:
+ """This is where you would load and process your data.
+ You can take in state and reference object fields.
+
+ You need to return a dictionary of the results that `update()` will then use to update the state.
+ """
+ # load data, and run some feature engineering -- create the data sets
+ # TODO: fill in
+ return {"training_data": "SOME_OBJECT/PATH", "evaluation_data": "SOME_OBJECT/PATH"}
+
+ @property
+ def writes(self) -> list[str]:
+ return ["training_data", "evaluation_data"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.update(
+ training_data=result["training_data"], evaluation_data=result["evaluation_data"]
+ )
+
+
+class TrainModel(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["training_data", "iterations"]
+
+ def run(self, state: State, **run_kwargs) -> dict:
+ """This is where you'd build the model and on each iteration do something different.
+ E.g. hyperparameter search.
+ """
+ # train the model, i.e. run one "iteration" whatever that means for you.
+ # TODO: fill in
+ return {
+ "model": "SOME_MODEL",
+ "iterations": state["iterations"] + 1,
+ "metrics": "SOME_METRICS",
+ }
+
+ @property
+ def writes(self) -> list[str]:
+ return ["models", "training_metrics", "iterations"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.update(
+ iterations=result["iterations"], # set current iteration value
+ ).append(
+ models=result["model"], # append -- note this can get big if your model is big
+ # so you'll want to overwrite but store the conditions, or log somewhere
+ metrics=result["metrics"], # append the metrics
+ )
+
+
+class ValidateModel(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["models", "evaluation_data"]
+
+ def run(self, state: State, **run_kwargs) -> dict:
+ """Compute validation metrics using the model and evaluation data."""
+ # TODO: fill in
+ return {"validation_metrics": "SOME_METRICS"}
+
+ @property
+ def writes(self) -> list[str]:
+ return ["validation_metrics"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.append(validation_metrics=result["validation_metrics"])
+
+
+class BestModel(Action):
+ @property
+ def reads(self) -> list[str]:
+ return ["validation_metrics", "models"]
+
+ def run(self, state: State, **run_kwargs) -> dict:
+ """Select the best model based on the validation metrics."""
+ # TODO: fill in
+ return {"best_model": "SOME_MODEL"}
+
+ @property
+ def writes(self) -> list[str]:
+ return ["best_model"]
+
+ def update(self, result: dict, state: State) -> State:
+ return state.update(best_model=result["best_model"])
+
+
+def application(iterations: int) -> burr.core.application.Application:
+ return (
+ burr.core.ApplicationBuilder()
+ .with_state(
+ data_path="data.csv",
+ iterations=10,
+ training_data=None,
+ evaluation_data=None,
+ models=[],
+ training_metrics=[],
+ validation_metrics=[],
+ best_model=None,
+ )
+ .with_actions(
+ process_data=ProcessDataAction(),
+ train_model=TrainModel(),
+ validate_model=ValidateModel(),
+ best_model=BestModel(),
+ )
+ .with_transitions(
+ ("process_data", "train_model", default),
+ ("train_model", "validate_model", default),
+ ("validate_model", "best_model", Condition.expr(f"iterations>{iterations}")),
+ ("validate_model", "train_model", default),
+ )
+ .with_entrypoint("process_data")
+ .build()
+ )
+
+
+if __name__ == "__main__":
+ app = application(100) # doing good data science is up to you...
+ app.visualize(output_file_path="statemachine", include_conditions=True, view=True, format="png")
+ # you could run things like this:
+ # last_action, result, state = app.run(halt_after=["best_model"])
diff --git a/examples/ml-training/statemachine.png b/examples/ml-training/statemachine.png
new file mode 100644
index 00000000..c3458b20
Binary files /dev/null and b/examples/ml-training/statemachine.png differ
diff --git a/examples/simulation/README.md b/examples/simulation/README.md
index 96fc1d07..0dc0585d 100644
--- a/examples/simulation/README.md
+++ b/examples/simulation/README.md
@@ -8,7 +8,7 @@ the input to the next time step, as well as output data to analyze.
For instance:
### Time-series Forecast
-A time-series forecast will execute a computation (say, feature-engineering + a model) at each step for which the user is predicting. The
+A time-series forecast will execute a computation (say, feature-engineering + a model) at each step for which the user is predicting. The
user will then store a history of data (predictions, raw data, etc...), and use that to pass into the next step in the simulation.
The merge into state + query from state capabilities can be complicated -- windowed operations, rolling averages, etc.. may all be useful,
@@ -16,6 +16,8 @@ and they may want to visualize simulations live (E.G. by tracking some metrics a
if it is just a few actions (`query_data`, `feature_engineer`, `forecast`), the persistence capabilities + hooks can allow
for logging to whatever live framework one wants to visualize, and centralizing the logic of reading from/writing to state.
+For a sketch of the latter see [application.py](./application.py) & ![diagram](./statemachine.png).
+
### Portfolio Construction
@@ -32,8 +34,7 @@ Each one of these could be a DAG using [Hamilton](https://github.com/dagworks-in
See [Stanford Smallville](https://hai.stanford.edu/news/computational-agents-exhibit-believable-humanlike-behavior) for an example.
For multiple independent "agents", Burr could help model the way they interact. This could be multiplke Burr applications, applications called within
-actions, or an action that loops over all "users". We are still figuring out the best way to model this, so reach out if you have ideas!
+actions, or an action that loops over all "users". We are still figuring out the best way to model this, so reach out if you have ideas!
Please comment at [this issue](https://github.com/DAGWorks-Inc/burr/issues/136) if you have any opinions on the above! We would love user-contributed examples.
-
diff --git a/examples/simulation/application.py b/examples/simulation/application.py
new file mode 100644
index 00000000..7efb587b
--- /dev/null
+++ b/examples/simulation/application.py
@@ -0,0 +1,104 @@
+"""
+This module contains a stubbed out structure for one way of doing a simulation
+ for forecasting purposes.
+
+For more sophisticated forecasts where prediction of one timestep
+depends on the previous timestep, you need to forecast on a per-step basis. So
+you're effectively simulating the future at each step. This is a simple example of
+how you might structure such a simulation.
+"""
+
+from typing import Tuple
+
+from burr.core import Application, ApplicationBuilder, State, expr
+from burr.core.action import action
+
+
+@action(reads=["data_path"], writes=["data"])
+def prepare_data(state: State) -> Tuple[dict, State]:
+ """This would pull the data, prepare it, and return it."""
+ # pull data, prepare as necessary
+ result = {"data": _process_data(state["data_path"])}
+ return result, state.update(**result)
+
+
+@action(reads=["data", "simulation_start"], writes=["model"])
+def build_model(state: State) -> Tuple[dict, State]:
+ """This would fit the model on data before the simulation start date."""
+ training_data = state["data"]
+ model = _fit_model(training_data, upto=state["simulation_start"])
+ result = {"model": model}
+ return result, state.update(**result)
+
+
+@action(
+ reads=["simulation_start", "simulation_end", "model", "data", "current_timestep"],
+ writes=["data"],
+)
+def forecast(state: State) -> Tuple[dict, State]:
+ """This action forecasts the next timestep in the simulation and appends it to data."""
+ model = state["model"]
+ data = state["data"]
+ start_time = state["simulation_start"]
+ current_time_step = state.get("current_timestep", start_time)
+ next_timestep = _forecast_timestep(model, data, current_time_step)
+ data = _update_data(data, next_timestep)
+ result = {"data": data, "current_timestep": next_timestep}
+ return result, state.update(**result)
+
+
+@action(reads=["data"], writes=[])
+def terminate(state: State) -> Tuple[dict, State]:
+ """This is a terminal step that would save the forecast or do something else."""
+ return {}, state
+
+
+def application() -> Application:
+ app = (
+ ApplicationBuilder()
+ .with_actions(prepare_data, build_model, forecast, terminate)
+ .with_transitions(
+ ("prepare_data", "build_model"),
+ ("build_model", "forecast"),
+ ("forecast", "forecast", expr("current_timestep<simulation_end")),
+ ("forecast", "terminate", expr("current_timestep>=simulation_end")),
+ )
+ .with_state(
+ data_path="SOME_PATH",
+ simulation_start="some-value",
+ simulation_end="some-end-value",
+ )
+ .with_entrypoint("prepare_data")
+ .build()
+ )
+ return app
+
+
+# --- stubbed out functions to fill out for the simulation
+def _process_data(data_path: str) -> object:
+ """This function would read and process data from a file."""
+ return {}
+
+
+def _fit_model(data: object, upto: str) -> object:
+ """This function would fit a model on data upto a certain date."""
+ return {}
+
+
+def _forecast_timestep(model: object, data: object, current_timestep: str) -> object:
+ """This function would forecast the next timestep in the simulation given the model and data."""
+ return {}
+
+
+def _update_data(data: object, next_timestep: object) -> object:
+ """This function would update the data with the forecasted timestep."""
+ return {}
+
+
+if __name__ == "__main__":
+ _app = application()
+ _app.visualize(
+ output_file_path="statemachine", include_conditions=True, view=True, format="png"
+ )
+ # you could run things like this:
+ # last_action, result, state = _app.run(halt_after=["terminate"])
diff --git a/examples/simulation/statemachine.png b/examples/simulation/statemachine.png
new file mode 100644
index 00000000..06f4f2c5
Binary files /dev/null and b/examples/simulation/statemachine.png differ