apache · vaquarkhan · May 8, 2026
diff --git 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
@@ -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=<queue-url>``
+* ``BURR_SQS_REGION=<aws-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 <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
@@ -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 <s3-tracking-aws>`
+* :ref:`Amazon Bedrock integration <bedrock-integration>`
diff --git 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
@@ -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 <https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html>`_
+* `Converse API reference <https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html>`_
+* `ConverseStream API reference <https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html>`_
+
+---------------
+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 <https://github.com/apache/burr/tree/main/examples/integrations/bedrock>`_.
 
 .. autoclass:: burr.integrations.bedrock.BedrockAction
    :members: run_and_update