Chainlit for Amazon Brazil Build

Brazil-compatible version of Chainlit for Amazon's internal build system.

🚀 Quick Start

Prerequisites

• Brazil build system access
• uv installed (for virtual environment management)

Setup & Build

# 1. Navigate to project
cd /Volumes/workplace/Aki/src/Chainlit

# 2. Create proper virtual environment (CRITICAL for local builds)
uv venv .venv

# 3. Run Brazil build
brazil-build

Publish

1. make sure you update the version

2. run below command (temporarily use public PYPI, need to migrate to internal source)

uv publish build/* --token {PYPI_TOKEN}

✅ Build Status

Production Ready - All issues resolved:

• ✅ Remote Brazil builds: Working
• ✅ Local Brazil builds: Working
• ✅ Python 3.10/3.11 compatibility: Fixed
• ✅ PeruPython integration: Complete

🏗 Architecture

Polyglot Build System:

• Frontend: React/TypeScript (pnpm) → Build assets
• Backend: Python package → Integrate frontend assets
• Output: amazon_chainlit-2.6.2-py3-none-any.whl (~12MB)

📁 Project Structure

Chainlit/
├── README.md                          # This guide
├── BRAZIL_BUILD_INTEGRATION.md       # Troubleshooting FAQ
├── brazil.ion                         # Peru package config
├── .venv/                            # Virtual environment (create with uv)
├── build-tools/bin/polyglot-build.sh # Main build script
├── third-party-src/
│   ├── backend/                       # Python source
│   ├── frontend/                      # React frontend
│   └── libs/                         # React libraries
└── build/                            # Build output

🔧 Development

Local Development Setup

# Virtual environment (required for local Brazil builds)
uv venv .venv
source .venv/bin/activate

# Install development dependencies
cd third-party-src
pnpm install

Build Commands

# Full build (local)
brazil-build

# Clean build
brazil-build clean

# Test individual components
cd third-party-src
pnpm build        # Build all frontend components

Testing Your Changes

# 1. Local build test
brazil-build

# 2. Verify artifacts
ls -la build/
# Expected: amazon_chainlit-2.6.2-py3-none-any.whl (~12MB)

⚠️ Critical Setup Requirements

1. Virtual Environment Setup

Must use uv venv .venv - not mkdir .venv

# ✅ Correct
uv venv .venv

# ❌ Wrong - will fail
mkdir .venv

PeruPython expects proper activation scripts at .venv/bin/activate.

2. Build Dependencies

Automatically handled by brazil.ion:

• PeruPython (for virtual environment)
• PeruNPM (for frontend builds)

3. Build Process

1. Frontend Build: React components with pnpm
2. Backend Build: Python package with PeruPython
3. Asset Integration: Frontend → Python package
4. Output: Wheel file in build/

🧪 Verification

Successful Build Output:

=== Build completed successfully! ===
Artifacts available in: /path/to/build
BUILD SUCCEEDED

Expected Artifacts:

build/
├── amazon_chainlit-2.6.2-py3-none-any.whl  (~12MB)
└── amazon_chainlit-2.6.2.tar.gz            (~12MB)

🆘 Troubleshooting

Having build issues? See BRAZIL_BUILD_INTEGRATION.md for:

• Complete troubleshooting FAQ
• Common error solutions
• Debug commands
• Environment fixes

Quick Fixes

Build failing locally?

# Fix virtual environment
rm -rf .venv
uv venv .venv
brazil-build

PeruPython issues?

# Check availability
which perupy-get-venv
# Should return: /path/to/PeruPython/bin/perupy-get-venv

📚 Additional Resources

• Troubleshooting FAQ - Fix build failures
• Original Chainlit - Upstream documentation
• Brazil Build System - Amazon internal docs

Ready to build! Run brazil-build and expect BUILD SUCCEEDED ✅