fastaiagent 0.1.0a1__tar.gz

fastaiagent-0.1.0a1/.claude/settings.local.json

@@ -0,0 +1,58 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(curl -s \"https://pypi.org/pypi/langgraph-checkpoint/json\")",
+      "Bash(curl -s \"https://pypi.org/pypi/langgraph-checkpoint-sqlite/json\")",
+      "Bash(curl -s \"https://pypi.org/pypi/langgraph-checkpoint-postgres/json\")",
+      "Bash(grep -l \"parallel\\\\|hitl\\\\|checkpoint\" /Users/upendrabhandari/fastaiagent-sdk/fastaiagent/chain/*.py)",
+      "WebSearch",
+      "WebFetch(domain:www.langchain.com)",
+      "Bash(python -c \"import fastaiagent; print\\(fastaiagent.__file__\\)\")",
+      "Bash(.venv/bin/python -c \"import fastaiagent; print\\('SDK available'\\)\")",
+      "Bash(.venv/bin/python -c ':*)",
+      "Bash(ls /Users/upendrabhandari/fastaiagent-sdk/docs/05*)",
+      "Bash(ls /Users/upendrabhandari/fastaiagent-sdk/docs/06*)",
+      "Bash(ls /Users/upendrabhandari/fastaiagent-sdk/docs/07*)",
+      "Bash(ls /Users/upendrabhandari/fastaiagent-sdk/docs/08*)",
+      "Bash(ls /Users/upendrabhandari/fastaiagent-sdk/docs/09*)",
+      "Bash(xargs ls:*)",
+      "Bash(wc -l /Users/upendrabhandari/fastaiagent-sdk/docs/*.md)",
+      "Bash(grep -c \"def test_\" tests/*.py)",
+      "Read(//Users/upendrabhandari/fastaiagent-sdk/**)",
+      "Bash(grep -c \"def test_\" /Users/upendrabhandari/fastaiagent-sdk/tests/*.py)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(python -m pytest tests/ --collect-only -q)",
+      "Bash(python -m pytest tests/ -x -q)",
+      "Bash(python -m mypy fastaiagent/ --ignore-missing-imports)",
+      "Bash(python benchmarks/bench_trace_overhead.py)",
+      "Bash(python benchmarks/bench_checkpoint_overhead.py)",
+      "Bash(python benchmarks/bench_cycle_performance.py)",
+      "Bash(python benchmarks/bench_replay_load.py)",
+      "Bash(python benchmarks/bench_local_kb.py)",
+      "Bash(python benchmarks/bench_eval.py)",
+      "Bash(python -m pytest tests/test_edge_cases.py tests/test_integrations.py -v --tb=short)",
+      "Bash(python -c \"from fastaiagent.prompt.prompt import Prompt; p = Prompt\\(name='x', template='Hello World!', version=1\\); print\\(dir\\(p\\)\\)\")",
+      "Bash(python -c \"from fastaiagent.chain import Chain; print\\([m for m in dir\\(Chain\\) if not m.startswith\\('_'\\)]\\)\")",
+      "Bash(python -c \"from fastaiagent.guardrail import Guardrail; print\\([m for m in dir\\(Guardrail\\) if not m.startswith\\('_'\\)]\\)\")",
+      "Bash(python -c \"from fastaiagent.prompt.prompt import Prompt; p = Prompt\\(name='x', template='Hello World!', version=1\\); print\\(p.render\\(\\)\\)\")",
+      "Bash(python -m pytest tests/ -q)",
+      "Bash(ruff check:*)",
+      "Bash([ ! -f \"docs/$d/index.md\" ])",
+      "Bash(python -m mypy fastaiagent/chain/chain.py --ignore-missing-imports)",
+      "Bash(ruff format:*)",
+      "Bash(python -m pytest tests/ -v --tb=no)",
+      "Bash(OPENAI_API_KEY=\"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\" python -m pytest tests/test_integration_live.py -v --tb=short)",
+      "Bash(python -c \"from fastaiagent.agent import AgentResult; print\\([a for a in dir\\(AgentResult\\) if not a.startswith\\('_'\\)]\\)\")",
+      "Bash(python -c \"from fastaiagent.eval.results import EvalResults; print\\([a for a in dir\\(EvalResults\\) if not a.startswith\\('_'\\)]\\)\")",
+      "Bash(python -c \"from fastaiagent.guardrail import no_pii; g = no_pii\\(\\); print\\(g.position, g.blocking, g.guardrail_type\\)\")",
+      "Bash(python -c \"from fastaiagent.agent import AgentResult; print\\(AgentResult.model_fields.keys\\(\\)\\)\")",
+      "Bash(python -c ':*)",
+      "Bash(python -m pytest tests/ -q --ignore=tests/test_integration_live.py)",
+      "Bash(pip install:*)",
+      "Bash(python -m build)"
+    ],
+    "additionalDirectories": [
+      "/Users/upendrabhandari/fastaiagent-sdk"
+    ]
+  }
+}

fastaiagent-0.1.0a1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,103 @@
+name: Bug Report
+description: Report a bug in the FastAIAgent SDK
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the information below to help us reproduce and fix it.
+
+  - type: input
+    id: version
+    attributes:
+      label: SDK Version
+      description: Output of `pip show fastaiagent | grep Version`
+      placeholder: "0.1.0a1"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: python-version
+    attributes:
+      label: Python Version
+      options:
+        - "3.10"
+        - "3.11"
+        - "3.12"
+        - "3.13"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Linux
+        - macOS
+        - Windows
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of the SDK is affected?
+      options:
+        - Agent
+        - Chain
+        - Tool (Function/REST/MCP)
+        - LLM Client
+        - Guardrail
+        - Tracing
+        - Agent Replay
+        - Prompts
+        - Knowledge Base
+        - Evaluation
+        - CLI
+        - Platform Sync
+        - Integration (OpenAI/Anthropic/LangChain/CrewAI)
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the bug
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code to reproduce the issue
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened (include error messages/tracebacks)
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other relevant information (logs, screenshots, etc.)

fastaiagent-0.1.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & Discussions
+    url: https://github.com/fastaifoundry/fastaiagent-sdk/discussions
+    about: Ask questions, share ideas, and discuss FastAIAgent SDK
+  - name: Discord Community
+    url: https://discord.gg/fastaiagent
+    about: Chat with the community and get help in real-time

fastaiagent-0.1.0a1/.github/ISSUE_TEMPLATE/docs_improvement.yml

@@ -0,0 +1,40 @@
+name: Documentation Improvement
+description: Suggest an improvement to the documentation
+labels: ["documentation"]
+body:
+  - type: input
+    id: page
+    attributes:
+      label: Page / Section
+      description: Which documentation page or section needs improvement?
+      placeholder: "e.g., getting-started/installation.md or Chains > Checkpointing"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: type
+    attributes:
+      label: Type of Improvement
+      options:
+        - Fix incorrect information
+        - Add missing information
+        - Improve clarity / wording
+        - Add code example
+        - Fix broken link
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What needs to be changed and why?
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested Improvement
+      description: How you think it should read (optional)

fastaiagent-0.1.0a1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Feature Summary
+      description: A brief description of the feature
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation / Use Case
+      description: Why do you need this? What problem does it solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed
+    attributes:
+      label: Proposed API / Implementation
+      description: How you imagine the feature would work (code examples welcome)
+      render: python
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Other approaches you've considered
+
+  - type: dropdown
+    id: willingness
+    attributes:
+      label: Willingness to Contribute
+      options:
+        - "I'd like to implement this myself"
+        - "I could help with implementation"
+        - "I'd prefer the team to implement this"

fastaiagent-0.1.0a1/.github/ISSUE_TEMPLATE/new_integration.yml

@@ -0,0 +1,43 @@
+name: New Integration Request
+description: Request auto-tracing support for a new framework
+labels: ["enhancement", "integration"]
+body:
+  - type: input
+    id: framework
+    attributes:
+      label: Framework / Library Name
+      placeholder: "e.g., DSPy, PydanticAI, AutoGen"
+    validations:
+      required: true
+
+  - type: input
+    id: framework-version
+    attributes:
+      label: Framework Version
+      placeholder: "e.g., >= 2.0"
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What Should Be Traced?
+      description: What spans/events would be useful to capture?
+    validations:
+      required: true
+
+  - type: textarea
+    id: api-design
+    attributes:
+      label: Proposed API
+      description: How the integration should work from the user's perspective
+      render: python
+      value: |
+        import fastaiagent
+        fastaiagent.integrations.<framework>.enable()
+
+        # Existing framework code runs as usual, now with tracing
+
+  - type: input
+    id: docs-link
+    attributes:
+      label: Framework Documentation Link
+      placeholder: "https://..."

fastaiagent-0.1.0a1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Summary
+<!-- Brief description of changes -->
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Enhancement
+- [ ] Documentation
+- [ ] Refactoring
+- [ ] Tests
+
+## Related Issues
+<!-- Link to related issues: Fixes #123, Relates to #456 -->
+
+## Checklist
+- [ ] Tests pass (`pytest tests/ -v`)
+- [ ] Linting passes (`ruff check . && ruff format --check .`)
+- [ ] Type checking passes (`mypy fastaiagent/`)
+- [ ] Documentation updated (if applicable)
+- [ ] Changelog updated (if user-facing change)
+
+## Test Plan
+<!-- How to verify these changes work correctly -->

fastaiagent-0.1.0a1/.github/labeler.yml

@@ -0,0 +1,42 @@
+documentation:
+  - changed-files:
+      - any-glob-to-any-file: ["docs/**", "*.md"]
+tests:
+  - changed-files:
+      - any-glob-to-any-file: ["tests/**"]
+ci:
+  - changed-files:
+      - any-glob-to-any-file: [".github/**"]
+agents:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/agent/**"]
+chains:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/chain/**"]
+tools:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/tool/**"]
+guardrails:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/guardrail/**"]
+tracing:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/trace/**"]
+evaluation:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/eval/**"]
+knowledge-base:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/kb/**"]
+prompts:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/prompt/**"]
+integrations:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/integrations/**"]
+platform:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/_platform/**", "fastaiagent/deploy/**"]
+cli:
+  - changed-files:
+      - any-glob-to-any-file: ["fastaiagent/cli/**"]

fastaiagent-0.1.0a1/.github/workflows/auto-label.yml

@@ -0,0 +1,18 @@
+name: Auto Label PRs
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          configuration-path: .github/labeler.yml

fastaiagent-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v --tb=short --cov=fastaiagent --cov-report=xml
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        uses: codecov/codecov-action@v4
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run mypy
+        run: mypy fastaiagent/ --ignore-missing-imports
+
+  optional-deps:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        extras: ["", "openai", "anthropic", "kb", "all"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install with extras
+        run: |
+          if [ -z "${{ matrix.extras }}" ]; then
+            pip install -e ".[dev]"
+          else
+            pip install -e ".[${{ matrix.extras }},dev]"
+          fi
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

fastaiagent-0.1.0a1/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build docs (PR validation)
+        if: github.event_name == 'pull_request'
+        run: mkdocs build --strict
+
+      - name: Deploy docs (main branch)
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        run: mkdocs gh-deploy --force

fastaiagent-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastaiagent-0.1.0a1/.github/workflows/welcome.yml

@@ -0,0 +1,35 @@
+name: Welcome New Contributors
+
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  welcome:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/first-interaction@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-message: |
+            Welcome to FastAIAgent SDK! Thanks for opening your first issue.
+
+            A maintainer will review this shortly. In the meantime:
+            - Check the [documentation](https://docs.fastaiagent.net)
+            - Browse [discussions](https://github.com/fastaifoundry/fastaiagent-sdk/discussions) for similar topics
+            - Join our [Discord](https://discord.gg/fastaiagent) for real-time help
+          pr-message: |
+            Welcome to FastAIAgent SDK! Thanks for your first pull request.
+
+            A maintainer will review this shortly. Please make sure:
+            - Tests pass: `pytest tests/ -v`
+            - Linting passes: `ruff check . && ruff format --check .`
+            - Type checks pass: `mypy fastaiagent/`
+
+            Check the [contributing guide](https://github.com/fastaifoundry/fastaiagent-sdk/blob/main/CONTRIBUTING.md) for details.

fastaiagent-0.1.0a1/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# SDK local data
+.fastaiagent/
+.prompts/
+
+# MkDocs build output
+site/
+
+# Internal / private
+claude_files/
+
+# OS
+.DS_Store
+Thumbs.db

fastaiagent-0.1.0a1/.python-version

@@ -0,0 +1 @@
+3.12

fastaiagent-0.1.0a1/BENCHMARKS.md

@@ -0,0 +1,70 @@
+# FastAIAgent SDK — Performance Benchmarks
+
+## Summary
+
+| Benchmark | Target | Measured | Status |
+|-----------|--------|----------|--------|
+| Trace overhead | < 5% | 19.5% | ⚠️ Above target |
+| Checkpoint per node | < 50ms | 0.1ms | ✅ Pass |
+| Cycle performance (100 iterations) | < 10s | < 0.001s | ✅ Pass |
+| Replay load (1000 spans) | < 2s | 0.001s | ✅ Pass |
+| KB search (1000 chunks) | < 500ms | 9.4ms | ✅ Pass |
+| Eval throughput (100 cases, 2 scorers) | < 60s | 0.001s | ✅ Pass |
+
+## Environment
+
+- Python 3.12, macOS (Apple Silicon)
+- fastaiagent v0.1.0a1
+- Benchmarks use synthetic data (no real LLM calls)
+
+## Known Issues
+
+**Trace overhead (19.5%):** The OTel `TracerProvider` + `LocalStorageProcessor` adds
+measurable overhead on high-frequency synthetic calls. In real-world usage with LLM
+latency (100ms–2s per call), trace overhead is negligible (< 0.5%). Optimization
+candidates: batch SQLite writes, reduce span attribute serialization.
+
+## How to Reproduce
+
+```bash
+pip install -e ".[dev]"
+
+python benchmarks/bench_trace_overhead.py
+python benchmarks/bench_checkpoint_overhead.py
+python benchmarks/bench_cycle_performance.py
+python benchmarks/bench_replay_load.py
+python benchmarks/bench_local_kb.py
+python benchmarks/bench_eval.py
+```
+
+## Benchmark Details
+
+### Trace Overhead (`bench_trace_overhead.py`)
+
+Measures the cost of OTel tracing on agent execution. Runs 1000 iterations with
+and without tracing, compares median execution time. Target: < 5% overhead.
+
+### Checkpoint Overhead (`bench_checkpoint_overhead.py`)
+
+Measures SQLite checkpoint write time per chain node. Runs 100 checkpoints and
+reports per-node time. Target: < 50ms per node.
+
+### Cycle Performance (`bench_cycle_performance.py`)
+
+Measures chain cycle execution with 100 iterations. Reports total time excluding
+LLM calls. Target: < 10s total.
+
+### Replay Load (`bench_replay_load.py`)
+
+Measures time to load and parse a trace with 1000 spans from SQLite storage.
+Target: < 2s.
+
+### Local KB Search (`bench_local_kb.py`)
+
+Indexes 1000 chunks with SimpleEmbedder, then searches 10 queries. Reports
+per-query search latency. Target: < 500ms per query.
+
+### Eval Throughput (`bench_eval.py`)
+
+Evaluates 100 test cases with 2 scorers (exact_match, contains). Reports total
+evaluation time excluding LLM calls. Target: < 60s total.