From a4124c4545fdcd2c5da9bc42121dcf47aecd573f Mon Sep 17 00:00:00 2001 From: vaquarkhan Date: Fri, 8 May 2026 01:55:06 -0500 Subject: [PATCH] docs: add AWS deployment and Bedrock documentation for issue 724 Document S3 tracking deployment patterns and event-driven SQS mode, expand Bedrock integration guidance, and wire new AWS concept/example pages into existing docs navigation. --- docs/concepts/index.rst | 1 + docs/concepts/s3-tracking-aws.rst | 141 ++++++++++++++++++++++++ docs/examples/deployment/aws.rst | 104 +++++++++++++++++ docs/examples/deployment/index.rst | 1 + docs/reference/integrations/bedrock.rst | 73 +++++++++++- 5 files changed, 318 insertions(+), 2 deletions(-) create mode 100644 docs/concepts/s3-tracking-aws.rst create mode 100644 docs/examples/deployment/aws.rst diff --git a/docs/concepts/index.rst b/docs/concepts/index.rst index 3a58bd012..99dd9dbf0 100644 --- a/docs/concepts/index.rst +++ b/docs/concepts/index.rst @@ -35,6 +35,7 @@ Overview of the concepts -- read these to get a mental model for how Burr works. state-machine transitions tracking + s3-tracking-aws state-persistence serde streaming-actions diff --git a/docs/concepts/s3-tracking-aws.rst b/docs/concepts/s3-tracking-aws.rst new file mode 100644 index 000000000..500927e24 --- /dev/null +++ b/docs/concepts/s3-tracking-aws.rst @@ -0,0 +1,141 @@ +.. + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _s3-tracking-aws: + +============================ +S3 Tracking on AWS (Concepts) +============================ + +This guide explains how Burr tracking works with S3-backed storage, and how to +choose between local, hybrid, and production deployment modes. + +Use the S3 client in your app: + +.. code-block:: bash + + pip install "burr[tracking-client-s3]" + +and run the S3-backed tracking server/UI: + +.. code-block:: bash + + pip install "burr[tracking-server-s3,cli]" + +----------------- +Deployment Models +----------------- + +Local +^^^^^ + +Use ``LocalTrackingClient`` and local filesystem storage (default ``~/.burr``). +This is the simplest setup for development and debugging. + +Hybrid +^^^^^^ + +Use ``S3TrackingClient`` from applications while running the tracking server in +one environment (for example a shared development server). Applications can run +from local machines, jobs, or services as long as they can write to the bucket. + +Production +^^^^^^^^^^ + +Use ``S3TrackingClient`` for all application writes and a dedicated S3-backed +tracking server for indexing and visualization. For near-real-time updates, pair +S3 object events with SQS event-driven mode. + +--------------- +SQS Event-Driven +--------------- + +S3 tracking server supports two modes: + +* ``POLLING``: periodic S3 scans (simpler infra) +* ``EVENT_DRIVEN``: SQS-backed event consumption for lower latency + +To use event-driven mode, configure these environment variables on the tracking server: + +* ``BURR_TRACKING_MODE=EVENT_DRIVEN`` +* ``BURR_SQS_QUEUE_URL=`` +* ``BURR_SQS_REGION=`` +* ``BURR_SQS_WAIT_TIME_SECONDS=20`` (default long-poll value) + +-------------- +Stream Buffering +-------------- + +S3 reads are buffered to improve reliability and large-object handling in the +tracking server. Tune buffering memory with: + +* ``BURR_S3_BUFFER_SIZE_MB`` (default: ``10``) + +The S3 tracking client also batches writes before flushes (default flush interval +is 5 seconds), reducing object churn for high event volume. + +----------------------- +Configuration Reference +----------------------- + +Common S3 server environment variables: + +* ``BURR_S3_BUCKET`` (required) +* ``BURR_UPDATE_INTERVAL_MILLISECONDS`` (default ``120000``) +* ``BURR_AWS_MAX_CONCURRENCY`` (default ``100``) +* ``BURR_SNAPSHOT_INTERVAL_MILLISECONDS`` (default ``3600000``) +* ``BURR_LOAD_SNAPSHOT_ON_START`` (default ``True``) +* ``BURR_PRIOR_SNAPSHOTS_TO_KEEP`` (default ``5``) +* ``BURR_TRACKING_MODE`` (``POLLING`` or ``EVENT_DRIVEN``) +* ``BURR_SQS_QUEUE_URL`` / ``BURR_SQS_REGION`` / ``BURR_SQS_WAIT_TIME_SECONDS`` +* ``BURR_S3_BUFFER_SIZE_MB`` + +------------- +Terraform Setup +------------- + +Use the included AWS Terraform example to provision S3-only or S3+SQS tracking +infrastructure: + +* ``examples/deployment/aws/terraform`` +* :ref:`AWS deployment example ` + +--------------- +Migration Guide +--------------- + +From local tracking to S3 tracking: + +#. Keep your existing Burr graph logic unchanged. +#. Replace ``LocalTrackingClient`` with ``S3TrackingClient`` in + ``ApplicationBuilder.with_tracker(...)``. +#. Provision bucket/IAM (and optionally SQS) in AWS. +#. Configure tracking server environment variables. +#. Validate with one test project before enabling for all workloads. + +Example client wiring: + +.. code-block:: python + + from burr.tracking.s3client import S3TrackingClient + + tracker = S3TrackingClient( + project="my_project", + bucket="my-burr-tracking-bucket", + region="us-east-1", + ) diff --git a/docs/examples/deployment/aws.rst b/docs/examples/deployment/aws.rst new file mode 100644 index 000000000..222543b6a --- /dev/null +++ b/docs/examples/deployment/aws.rst @@ -0,0 +1,104 @@ +.. + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _aws-deployment-example: + +====================== +AWS Deployment Example +====================== + +This example covers deploying Burr tracking infrastructure on AWS with S3, and +optionally SQS for event-driven updates. + +The Terraform module lives in: + +* ``examples/deployment/aws/terraform`` + +------------ +Architecture +------------ + +S3-only (polling mode): + +* Burr applications write tracking data to S3. +* Tracking server polls/indexes S3 and serves the UI. + +S3+SQS (event-driven mode): + +* S3 object notifications are delivered to SQS. +* Tracking server consumes SQS and ingests updates with lower latency. + +----------- +Quick Start +----------- + +.. code-block:: bash + + cd examples/deployment/aws/terraform + terraform init + terraform apply -var-file=dev.tfvars # S3 polling mode + # or + terraform apply -var-file=prod.tfvars # S3 + SQS event-driven mode + +After apply, inspect outputs: + +.. code-block:: bash + + terraform output burr_environment_variables + +Set these environment variables in the runtime where you launch ``burr``. + +----------------------------- +Terraform Variables and Modes +----------------------------- + +Key variables: + +* ``aws_region`` (default ``us-east-1``) +* ``environment`` (for example ``dev`` / ``prod``) +* ``s3_bucket_name`` (optional custom name) +* ``enable_sqs`` (``true`` for event-driven mode) +* ``sqs_queue_name`` +* ``log_retention_days`` +* ``snapshot_retention_days`` +* ``dlq_alarm_notification_emails`` + +Mode mapping: + +* ``dev.tfvars``: S3-only (polling) +* ``prod.tfvars``: S3 + SQS (event-driven) + +----------------- +Terraform Outputs +----------------- + +Useful outputs include: + +* ``s3_bucket_name`` +* ``sqs_queue_url`` +* ``sqs_dlq_url`` +* ``dlq_alarm_arn`` +* ``dlq_alarm_sns_topic_arn`` +* ``burr_environment_variables`` + +-------------- +Related Guides +-------------- + +* :ref:`S3 tracking concepts ` +* :ref:`Amazon Bedrock integration ` diff --git a/docs/examples/deployment/index.rst b/docs/examples/deployment/index.rst index e1afd91c3..39d1e5d6e 100644 --- a/docs/examples/deployment/index.rst +++ b/docs/examples/deployment/index.rst @@ -40,3 +40,4 @@ have an example that would add to this guide. We have created a variety of issue web-server infrastructure monitoring + aws diff --git a/docs/reference/integrations/bedrock.rst b/docs/reference/integrations/bedrock.rst index 934b62694..6e6cfd981 100644 --- a/docs/reference/integrations/bedrock.rst +++ b/docs/reference/integrations/bedrock.rst @@ -32,8 +32,77 @@ Install the optional extra (pulls ``boto3``): pip install "burr[bedrock]" -IAM permissions must allow ``bedrock:InvokeModel`` / streaming equivalents for your -chosen models; see AWS documentation for your account and model IDs. +---------------- +Available Actions +---------------- + +``BedrockAction`` is a single-step action for standard request/response flows. +``BedrockStreamingAction`` is a streaming action that emits chunks during execution +and applies final state updates when complete. + +Both actions accept: + +* ``model_id``: Bedrock model identifier (for example Claude models on Bedrock) +* ``input_mapper``: maps Burr state to Bedrock ``messages`` (and optional ``system``) +* ``reads`` / ``writes``: standard Burr state wiring +* Optional AWS settings: ``region``, ``max_retries``, optional injected ``client`` +* Optional guardrails: ``guardrail_id`` + required ``guardrail_version`` +* Optional ``inference_config`` passed through to Bedrock + +.. note:: + + If ``guardrail_id`` is set, ``guardrail_version`` is required. + +---------------- +Supported Models +---------------- + +Burr passes ``model_id`` directly to Bedrock Runtime. Any model that supports +the Bedrock **Converse** / **ConverseStream** API in your account and region can be +used. See AWS model availability by region and account entitlement: + +* `Supported foundation models in Amazon Bedrock `_ +* `Converse API reference `_ +* `ConverseStream API reference `_ + +--------------- +IAM Permissions +--------------- + +At minimum, the runtime identity used by Burr should have permission to invoke +the specific Bedrock model(s) you choose: + +* ``bedrock:InvokeModel`` +* ``bedrock:InvokeModelWithResponseStream`` (for streaming) + +Depending on your setup, you may also need permissions for guardrails and +cross-account resource access. Restrict resources to specific model ARNs whenever possible. + +------------- +Quick Example +------------- + +.. code-block:: python + + from burr.integrations.bedrock import BedrockAction + + def map_state_to_prompt(state): + return { + "messages": [{"role": "user", "content": [{"text": state["question"]}]}], + "system": [{"text": "You are a concise assistant."}], + } + + ask_model = BedrockAction( + name="ask_model", + model_id="anthropic.claude-3-haiku-20240307-v1:0", + input_mapper=map_state_to_prompt, + reads=["question"], + writes=["response", "usage", "stop_reason"], + region="us-east-1", + ) + +See the runnable integration example in the repository: +`examples/integrations/bedrock `_. .. autoclass:: burr.integrations.bedrock.BedrockAction :members: run_and_update