Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.
Python aiburrchatbot-frameworkdagsgenerative-aigraphshacktoberfestllmopsllmsmlopspersistent-data-structurestate-machinestate-managementvisibility
Adds example stubbs to code for ml & simulation
Stefan Krawczykdc8043809ff5
diff --git a/examples/ml-training/README.md b/examples/ml-training/README.mdindex 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 ruSimilar to epoch training, hyperparameter training can be modeled as a state machine. The system makes a decision about whatto 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) & .diff --git a/examples/ml-training/application.py b/examples/ml-training/application.pynew file mode 100644index 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.pngnew file mode 100644index 00000000..c3458b20Binary files /dev/null and b/examples/ml-training/statemachine.png differdiff --git a/examples/simulation/README.md b/examples/simulation/README.mdindex 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. Theuser 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 aif it is just a few actions (`query_data`, `feature_engineer`, `forecast`), the persistence capabilities + hooks can allowfor 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) & .+### Portfolio Construction@@ -32,8 +34,7 @@ Each one of these could be a DAG using [Hamilton](https://github.com/dagworks-inSee [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.pynew file mode 100644index 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.pngnew file mode 100644index 00000000..06f4f2c5Binary files /dev/null and b/examples/simulation/statemachine.png differ