substrai-lambdallm 1.0.0__tar.gz

substrai_lambdallm-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Verify package
+        run: |
+          pip install dist/*.whl
+          python -c "import lambdallm; print(f'LambdaLLM v{lambdallm.__version__}')"

substrai_lambdallm-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

substrai_lambdallm-1.0.0/.gitignore

@@ -0,0 +1,71 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.manifest
+*.spec
+pip-log.txt
+pip-delete-this-directory.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+instance/
+.webassets-cache
+.scrapy
+docs/_build/
+.pybuilder/
+target/
+.ipynb_checkpoints
+profile_default/
+ipython_config.py
+.pdm.toml
+.pdm-python.txt
+__pypackages__/
+celerybeat-schedule
+celerybeat.pid
+*.sage.py
+.env
+.venv
+env/
+venv/
+ENV/
+.spyderproject
+.spyproject
+.ropeproject
+/site
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+cython_debug/

substrai_lambdallm-1.0.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to LambdaLLM will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-10
+
+### Added
+- `@handler` decorator with IoC pattern for Lambda functions
+- `Prompt` class with type-safe templates and structured output
+- `Model` enum with Bedrock model IDs (Claude, Titan, Llama)
+- `BedrockProvider` with lazy initialization and cost tracking
+- Middleware system: `LoggingMiddleware`, `CostTrackingMiddleware`
+- Retry with exponential backoff and fallback model support
+- Timeout awareness with checkpoint/truncate/fail-fast strategies
+- GitHub Actions CI/CD (test + publish)
+- Examples: basic summarizer, chat with memory
+- Full test suite with mocked providers
+
+### Architecture
+- Core package size: < 50KB (no dependencies in core)
+- Plugin-based provider system (BaseProvider interface)
+- Middleware pipeline (before/after hooks)
+- Convention over configuration (works with zero config)
+- Escape hatch: `context.get_raw_client()` for direct boto3 access

substrai_lambdallm-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to LambdaLLM
+
+Thank you for your interest in contributing to LambdaLLM! This document provides guidelines for contributing.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/lambdallm.git`
+3. Create a virtual environment: `python -m venv .venv && source .venv/bin/activate`
+4. Install dev dependencies: `pip install -e ".[dev]"`
+5. Create a branch: `git checkout -b feat/your-feature`
+
+## Development Workflow
+
+```bash
+# Run tests
+pytest tests/ -v
+
+# Run linter
+ruff check src/ tests/
+
+# Format code
+ruff format src/ tests/
+```
+
+## Commit Messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `test:` Tests
+- `ci:` CI/CD changes
+- `refactor:` Code refactoring
+- `chore:` Maintenance
+
+## Pull Request Process
+
+1. Ensure all tests pass
+2. Update documentation if needed
+3. Add tests for new features
+4. Keep PRs focused — one feature per PR
+5. Reference any related issues
+
+## Code Style
+
+- Python 3.10+ type hints
+- Docstrings on all public functions/classes
+- Max line length: 100 characters
+- Use `ruff` for linting and formatting
+
+## Architecture Principles
+
+When contributing, keep these framework principles in mind:
+
+1. **Convention over configuration** — sensible defaults everywhere
+2. **< 5MB package size** — no heavy dependencies in core
+3. **Lambda-first** — every feature must work within Lambda constraints
+4. **Observable by default** — log and trace without user configuration
+5. **Escape hatches** — never trap the user
+
+## Questions?
+
+Open a [Discussion](https://github.com/substrai/lambdallm/discussions) or reach out at contact@substrai.dev.

substrai_lambdallm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SubStrai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

substrai_lambdallm-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: substrai-lambdallm
+Version: 1.0.0
+Summary: Serverless-native LLM orchestration framework for AWS Lambda
+Project-URL: Homepage, https://substrai.dev
+Project-URL: Repository, https://github.com/substrai/lambdallm
+Project-URL: Documentation, https://docs.substrai.dev/lambdallm
+Project-URL: Issues, https://github.com/substrai/lambdallm/issues
+Project-URL: Changelog, https://github.com/substrai/lambdallm/blob/main/CHANGELOG.md
+Author-email: Gaurav Kumar Sinha <gaurav@substrai.dev>
+License: MIT
+License-File: LICENSE
+Keywords: agents,aws,bedrock,chains,framework,genai,lambda,llm,serverless
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: aws-xray-sdk>=2.12.0; extra == 'all'
+Requires-Dist: boto3>=1.28.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.28.0; extra == 'bedrock'
+Provides-Extra: dev
+Requires-Dist: moto>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: xray
+Requires-Dist: aws-xray-sdk>=2.12.0; extra == 'xray'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# LambdaLLM
+
+**Serverless-native LLM orchestration framework for AWS Lambda.**
+
+> Built by [SubstrAI](https://github.com/substrai) — Open-source GenAI frameworks for serverless infrastructure.
+
+## The Problem
+
+Existing LLM frameworks (LangChain, LlamaIndex) assume long-running servers. They break on Lambda:
+- Cold starts: 500MB+ dependency trees add seconds
+- Stateless: No conversation memory between invocations
+- 15-min timeout: Long agent loops crash
+- 250MB limit: LangChain alone exceeds this
+
+## The Solution
+
+LambdaLLM is purpose-built for Lambda's constraints:
+
+```python
+from lambdallm import handler, Prompt, Model
+
+summarize = Prompt(
+    template="Summarize in {max_words} words:\n\n{document}",
+    output_schema={"summary": str, "key_points": list}
+)
+
+@handler(model=Model.CLAUDE_3_HAIKU)
+def lambda_handler(event, context):
+    return summarize.invoke(
+        document=event["body"]["text"],
+        max_words=100
+    )
+```
+
+## Features
+
+- **< 5MB** package size (vs 400MB+ for LangChain)
+- **Cold-start optimized** — lazy imports, connection pooling
+- **DynamoDB-native state** — conversation memory that survives stateless execution
+- **Cost-aware routing** — auto-select cheapest model that meets quality threshold
+- **One-command deploy** — `lambdallm deploy` generates all AWS infrastructure
+- **Timeout handling** — checkpoint/resume for long chains
+
+## Installation
+
+```bash
+pip install lambdallm[bedrock]
+```
+
+## Quick Start
+
+```bash
+lambdallm init my-project
+cd my-project
+lambdallm dev
+```
+
+## Documentation
+
+- [Getting Started](https://docs.substrai.dev/lambdallm/getting-started)
+- [API Reference](https://docs.substrai.dev/lambdallm/api)
+- [Examples](https://github.com/substrai/lambdallm/tree/main/examples)
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+## Author
+
+**Gaurav Kumar Sinha** — Founder, [SubstrAI](https://github.com/substrai)

substrai_lambdallm-1.0.0/README.md

@@ -0,0 +1,70 @@
+# LambdaLLM
+
+**Serverless-native LLM orchestration framework for AWS Lambda.**
+
+> Built by [SubstrAI](https://github.com/substrai) — Open-source GenAI frameworks for serverless infrastructure.
+
+## The Problem
+
+Existing LLM frameworks (LangChain, LlamaIndex) assume long-running servers. They break on Lambda:
+- Cold starts: 500MB+ dependency trees add seconds
+- Stateless: No conversation memory between invocations
+- 15-min timeout: Long agent loops crash
+- 250MB limit: LangChain alone exceeds this
+
+## The Solution
+
+LambdaLLM is purpose-built for Lambda's constraints:
+
+```python
+from lambdallm import handler, Prompt, Model
+
+summarize = Prompt(
+    template="Summarize in {max_words} words:\n\n{document}",
+    output_schema={"summary": str, "key_points": list}
+)
+
+@handler(model=Model.CLAUDE_3_HAIKU)
+def lambda_handler(event, context):
+    return summarize.invoke(
+        document=event["body"]["text"],
+        max_words=100
+    )
+```
+
+## Features
+
+- **< 5MB** package size (vs 400MB+ for LangChain)
+- **Cold-start optimized** — lazy imports, connection pooling
+- **DynamoDB-native state** — conversation memory that survives stateless execution
+- **Cost-aware routing** — auto-select cheapest model that meets quality threshold
+- **One-command deploy** — `lambdallm deploy` generates all AWS infrastructure
+- **Timeout handling** — checkpoint/resume for long chains
+
+## Installation
+
+```bash
+pip install lambdallm[bedrock]
+```
+
+## Quick Start
+
+```bash
+lambdallm init my-project
+cd my-project
+lambdallm dev
+```
+
+## Documentation
+
+- [Getting Started](https://docs.substrai.dev/lambdallm/getting-started)
+- [API Reference](https://docs.substrai.dev/lambdallm/api)
+- [Examples](https://github.com/substrai/lambdallm/tree/main/examples)
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+## Author
+
+**Gaurav Kumar Sinha** — Founder, [SubstrAI](https://github.com/substrai)

substrai_lambdallm-1.0.0/examples/agent_with_tools.py

@@ -0,0 +1,97 @@
+"""Example: AI agent with tools for research and analysis.
+
+Demonstrates how to build a ReAct-style agent that uses tools
+to answer complex questions, all within Lambda's constraints.
+"""
+
+from lambdallm import handler, Model
+from lambdallm.agents import Tool, Agent
+
+
+# Define tools the agent can use
+@Tool(description="Search the knowledge base for relevant documents")
+def search_kb(query: str, max_results: int = 3) -> list[dict]:
+    """Search for documents matching the query.
+
+    Args:
+        query: The search query string.
+        max_results: Maximum number of results to return.
+    """
+    # In production, this would call OpenSearch, Bedrock KB, etc.
+    return [
+        {"title": f"Result for '{query}'", "content": f"Relevant information about {query}..."},
+    ]
+
+
+@Tool(description="Calculate a mathematical expression")
+def calculate(expression: str) -> float:
+    """Safely evaluate a mathematical expression.
+
+    Args:
+        expression: Mathematical expression to evaluate (e.g., '2 + 2', '100 * 0.15').
+    """
+    # Safe eval for basic math
+    allowed_chars = set("0123456789+-*/.() ")
+    if not all(c in allowed_chars for c in expression):
+        raise ValueError(f"Invalid expression: {expression}")
+    return eval(expression)
+
+
+@Tool(description="Get current date and time")
+def get_current_time() -> str:
+    """Get the current UTC date and time."""
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()
+
+
+# Create the agent
+research_agent = Agent(
+    name="research-analyst",
+    system_prompt="""You are a research analyst. Use the available tools to 
+    gather information and perform calculations to answer questions accurately.
+    Always cite your sources and show your work for calculations.""",
+    tools=[search_kb, calculate, get_current_time],
+    max_iterations=5,
+    timeout_buffer=30,  # Reserve 30s before Lambda timeout
+    max_cost_usd=0.10,  # Stop if cost exceeds $0.10
+    verbose=True,
+)
+
+
+@handler(model=Model.CLAUDE_3_SONNET)
+def lambda_handler(event, context):
+    """Research agent Lambda handler.
+
+    Expected event body:
+    {
+        "question": "What is the total revenue if we grow 15% from $1M?"
+    }
+    """
+    import json
+
+    body = json.loads(event.get("body", "{}")) if isinstance(event.get("body"), str) else event.get("body", {})
+
+    question = body.get("question", "")
+
+    # Run the agent
+    result = research_agent.run(query=question, context=context)
+
+    return {
+        "statusCode": 200,
+        "body": {
+            "answer": result.answer,
+            "status": result.status,
+            "iterations": result.total_iterations,
+            "tool_calls": result.total_tool_calls,
+            "cost_usd": result.total_cost_usd,
+            "latency_ms": result.total_latency_ms,
+            "steps": [
+                {
+                    "thought": s.thought[:200],
+                    "tool": s.tool_name,
+                    "tool_output": str(s.tool_output)[:200] if s.tool_output else None,
+                }
+                for s in result.steps
+            ],
+        },
+    }

substrai_lambdallm-1.0.0/examples/basic_summarizer.py

@@ -0,0 +1,53 @@
+"""Example: Basic document summarizer using LambdaLLM.
+
+Deploy this as a Lambda function to get a GenAI-powered
+summarization API in under 5 minutes.
+
+Usage:
+    lambdallm init --template basic
+    lambdallm deploy
+"""
+
+from lambdallm import handler, Prompt, Model
+
+# Define a reusable, type-safe prompt
+summarize = Prompt(
+    name="summarize",
+    template="""Summarize the following document in {max_words} words or less.
+Focus on the key points and main conclusions.
+
+Document:
+{document}""",
+    input_schema={"document": str, "max_words": int},
+    output_schema={"summary": str, "key_points": list},
+)
+
+
+@handler(model=Model.CLAUDE_3_HAIKU, timeout_strategy="truncate")
+def lambda_handler(event, context):
+    """Lambda handler for document summarization.
+
+    Expected event body:
+    {
+        "text": "The document to summarize...",
+        "max_words": 100
+    }
+    """
+    import json
+
+    body = json.loads(event.get("body", "{}")) if isinstance(event.get("body"), str) else event.get("body", {})
+
+    result = summarize.invoke(
+        _context=context,
+        document=body.get("text", ""),
+        max_words=body.get("max_words", 100),
+    )
+
+    return {
+        "statusCode": 200,
+        "body": {
+            "result": result,
+            "cost_usd": context.total_cost,
+            "model": context.model.model_id,
+        },
+    }

substrai_lambdallm-1.0.0/examples/chat_with_memory.py

@@ -0,0 +1,49 @@
+"""Example: Multi-turn chat with conversation memory.
+
+Demonstrates how LambdaLLM handles stateless Lambda + stateful conversations
+using DynamoDB-backed session management.
+"""
+
+from lambdallm import handler, Model
+from lambdallm.core.context import LambdaLLMContext
+
+
+@handler(
+    model=Model.CLAUDE_3_SONNET,
+    timeout_strategy="fail-fast",
+    timeout_buffer=10,
+)
+def lambda_handler(event, context: LambdaLLMContext):
+    """Multi-turn chat handler.
+
+    Expected event body:
+    {
+        "message": "User's message",
+        "session_id": "unique-session-id"
+    }
+    """
+    import json
+
+    body = json.loads(event.get("body", "{}")) if isinstance(event.get("body"), str) else event.get("body", {})
+
+    user_message = body.get("message", "")
+    session_id = body.get("session_id", "default")
+
+    # In Phase 2, this will auto-load from DynamoDB:
+    # session = context.session  # auto-loaded via session_id
+
+    # For now, simple single-turn response
+    response = context.invoke(
+        "You are a helpful assistant. Respond to: {message}",
+        message=user_message,
+    )
+
+    return {
+        "statusCode": 200,
+        "body": {
+            "reply": response,
+            "session_id": session_id,
+            "cost_usd": context.total_cost,
+            "remaining_time_ms": context.remaining_time_ms,
+        },
+    }