[](https://github.com/Mike-Animal-Counseling/aws-lambda-slo-optimizer/actions/workflows/ci.yml) · Beta · Python 3.11+
-LambdaOpt compares benchmark candidates by estimated cost and tail latency. Use CloudWatch metrics and cold-start logs to investigate why a deployed function is missing its target.
+A smaller Lambda can cost less per invocation and still be the wrong choice if it misses your latency target. LambdaOpt compares memory and architecture candidates using benchmark data, then shows the p95, p99, estimated cost, and reason behind its recommendation.
+
+## Features
+
+- **Benchmark candidates.** Start with synthetic data, load existing benchmark results, or invoke explicitly mapped test functions.
+- **Compare cost and latency.** Filter candidates by p95 target and errors, then rank the passing configurations by estimated monthly cost.
+- **Investigate a deployed function.** Inspect CloudWatch latency, errors, and throttles. Include logs to check cold-start signals.
+- **Share the evidence.** Export Markdown and JSON reports with recommendations, measurements, and rejected candidates. Charts are optional.
-## Try it locally
+## Example recommendation
+
+Two rows from the synthetic demo report for a **500 ms p95 target** and 1 million monthly requests.
+
+| Candidate | p95 | p99 | Est. monthly cost | Result |
+| --- | ---: | ---: | ---: | --- |
+| 512 MB arm64 | 633.1 ms | 692.9 ms | `$3.91` | Misses target |
+| 1024 MB arm64 | 357.9 ms | 479.4 ms | `$4.38` | Recommended |
+
+## Architecture
+
+```mermaid
+flowchart LR
+ benchmarks["Benchmark results"] --> optimizer["Cost + p95 selection"]
+ metrics["CloudWatch metrics and logs"] --> diagnostics["Latency + risk analysis"]
+ optimizer --> reports["Markdown and JSON reports"]
+ diagnostics --> reports
+```
+
+The optimizer works on typed benchmark data and runs locally. The CloudWatch workflow produces a separate diagnostic report. See the [module boundaries and report formats](docs/architecture.md).
+
+## Quickstart
Requires Python 3.11+. On Windows, use the [PowerShell setup](docs/installation.md#from-source).
@@ -19,23 +50,14 @@ python -m pip install .
lambdaopt start
```
-The demo uses synthetic data and needs no AWS credentials. Open `reports/start/optimization_report.md` for the recommendation, p95/p99 measurements, and cost estimates.
-
-Two rows from the demo report for a **500 ms p95 target** and 1 million monthly requests.
-
-| Candidate | p95 | p99 | Est. monthly cost | Result |
-| --- | ---: | ---: | ---: | --- |
-| 512 MB arm64 | 633.1 ms | 692.9 ms | `$3.91` | Misses target |
-| 1024 MB arm64 | 357.9 ms | 479.4 ms | `$4.38` | Recommended |
-
-## Use it with AWS
+The demo needs no AWS credentials. Open `reports/start/optimization_report.md` for the full candidate comparison.
-Start with the [sandbox walkthrough](docs/smoke-test.md). CloudWatch analysis reads metrics and optional logs. Benchmarking can invoke explicitly selected functions, so use test targets. LambdaOpt leaves Lambda configuration unchanged.
+For AWS, start with the [sandbox walkthrough](docs/smoke-test.md). CloudWatch analysis reads metrics and optional logs. Benchmarking can invoke explicitly selected functions, so use test targets. LambdaOpt leaves Lambda configuration unchanged.
## Documentation
- [CLI workflows](docs/usage.md) and [IAM permissions](docs/iam-permissions.md)
-- [Architecture](docs/architecture.md) and [recommendation logic](docs/design.md)
+- [Recommendation logic](docs/design.md) and [cost model](docs/cost-model.md)
- [Safety](docs/safety.md) and [contributing](CONTRIBUTING.md)
[MIT license](LICENSE)
diff --git a/docs/assets/lambdaopt-mark.svg b/docs/assets/lambdaopt-mark.svg
new file mode 100644
index 0000000..d0d3c9a
--- /dev/null
+++ b/docs/assets/lambdaopt-mark.svg
@@ -0,0 +1,6 @@
+