A comprehensive full-stack starter bundle combining AI capabilities with Web3 technology. This project provides a production-ready foundation for building decentralized applications with artificial intelligence features.

• Python/FastAPI Backend: High-performance async API with AI integration
• Next.js/TypeScript Frontend: Modern React framework with full TypeScript support
• Hardhat Smart Contracts: Professional Solidity development environment
• AI Integration: OpenAI GPT-5.1-Codex-Max support via LangChain
• Web3 Libraries: ethers.js, viem, and wagmi for blockchain interactions
• Production Ready: Comprehensive testing, linting, and CI/CD pipelines
• Config Validation: Runtime configuration validation with Pydantic and Zod
• Optional Telemetry: OpenTelemetry integration for observability
• Security Scanning: Automated Trivy vulnerability scanning and SBOM generation
• Dependency Management: Automated updates via Renovate

• Python 3.11 or higher
• Node.js 20.x or higher
• npm 9.x or higher

git clone https://github.com/lippytm/Web3AI.git
cd Web3AI

cd backend

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your API keys and settings

# Run development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Backend will be available at: http://localhost:8000

cd frontend

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env.local
# Edit .env.local with your settings

# Run development server
npm run dev

Frontend will be available at: http://localhost:3000

cd contracts

# Install dependencies
npm install

# Configure environment (optional for local development)
cp .env.example .env

# Compile contracts
npm run compile

# Run tests
npm test

# Start local Hardhat node (optional)
npm run node

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key-here
MODEL_NAME=GPT-5.1-Codex-Max

# Blockchain Configuration
ETH_RPC_URL=https://eth.llamarpc.com
NETWORK=mainnet

# Application Settings
DEBUG=false

# Optional Telemetry (requires pip install -r requirements-extras.txt)
TELEMETRY_ENABLED=false
TELEMETRY_ENDPOINT=

Config Validation: The backend automatically validates configuration on startup. Valid networks are: mainnet, sepolia, goerli, localhost.

# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8000

# Blockchain RPC
NEXT_PUBLIC_RPC_URL=https://eth.llamarpc.com
NEXT_PUBLIC_CHAIN_ID=1

# AI Model Configuration
NEXT_PUBLIC_MODEL_NAME=GPT-5.1-Codex-Max

# Optional Telemetry
NEXT_PUBLIC_TELEMETRY_ENABLED=false

Config Validation: Run npm run config:validate in the frontend directory to validate configuration without starting the server.

# Private key for deployment (NEVER commit real keys!)
PRIVATE_KEY=your-private-key-here

# RPC URLs
ETH_RPC_URL=https://eth.llamarpc.com
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR-PROJECT-ID

Web3AI/
├── backend/                    # Python/FastAPI backend
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py            # FastAPI application
│   │   └── settings.py        # Configuration settings
│   ├── tests/                 # Pytest tests
│   ├── requirements.txt       # Python dependencies
│   └── .env.example
├── frontend/                   # Next.js/TypeScript frontend
│   ├── app/
│   │   ├── page.tsx           # Main page
│   │   ├── layout.tsx         # Root layout
│   │   └── globals.css        # Global styles
│   ├── package.json
│   ├── tsconfig.json
│   └── .env.example
├── contracts/                  # Hardhat smart contracts
│   ├── contracts/
│   │   └── Lock.sol           # Sample contract
│   ├── scripts/
│   │   └── deploy.js          # Deployment script
│   ├── test/
│   │   └── Lock.test.js       # Contract tests
│   ├── hardhat.config.js
│   └── package.json
├── .github/
│   └── workflows/
│       └── ci-cd.yml          # GitHub Actions CI/CD
├── .pre-commit-config.yaml    # Pre-commit hooks
└── README.md

cd backend
pytest                    # Run all tests
pytest -v                 # Verbose output
pytest --cov=app          # With coverage report

cd frontend
npm test                  # Run tests
npm run type-check        # TypeScript check

cd contracts
npm test                  # Run Hardhat tests
npm run compile           # Compile contracts

cd backend
ruff check .              # Run linter
ruff format .             # Format code
black .                   # Format with black

cd frontend
npm run lint              # Run ESLint
npm run format            # Format with Prettier
npm run format:check      # Check formatting

Install pre-commit hooks (optional):

pip install pre-commit
pre-commit install
pre-commit run --all-files

cd contracts
npm run compile

npm test

Local deployment:

# Terminal 1: Start local node
npm run node

# Terminal 2: Deploy
npm run deploy

Testnet deployment:

npx hardhat run scripts/deploy.js --network sepolia

• hardhat: Local development network (chainId: 1337)
• localhost: Local node at http://127.0.0.1:8545
• mainnet: Ethereum mainnet (requires PRIVATE_KEY in .env)
• sepolia: Sepolia testnet (requires PRIVATE_KEY in .env)

The backend uses OpenAI's API through LangChain for AI capabilities:

1. Get API Key: Sign up at OpenAI Platform
2. Set Environment Variable: Add OPENAI_API_KEY to backend/.env
3. Configure Model: Set MODEL_NAME=GPT-5.1-Codex-Max (or your preferred model)

The FastAPI backend exposes AI endpoints at /api/info and can be extended with custom AI routes.

The project includes default public RPC endpoints:

• Ethereum Mainnet: https://eth.llamarpc.com
• Sepolia Testnet: Configure in .env files

For production, consider using:

• Infura
• Alchemy
• QuickNode

Update ETH_RPC_URL and NEXT_PUBLIC_RPC_URL in environment files.

GitHub Actions automatically runs on push/PR to main:

1. Pre-commit Hooks Validation: Validates code formatting and linting
2. Python Backend Job: Runs ruff linter, config validation, and pytest
3. Node Frontend Job: Runs ESLint, config validation, and builds Next.js app
4. Contracts Job: Compiles contracts and runs Hardhat tests

See .github/workflows/ci-cd.yml for configuration.

This project includes automated security scanning via Trivy:

# Security scans run automatically on:
# - Weekly schedule (Monday 6:00 AM UTC)
# - Push to main branch
# - Pull requests to main
# - Manual workflow dispatch

Software Bill of Materials (SBOM) is automatically generated for all components:

• Overall project SBOM (SPDX format)
• Backend SBOM (CycloneDX format)
• Frontend SBOM (CycloneDX format)
• Contracts SBOM (CycloneDX format)

SBOMs are available as workflow artifacts after each security scan run.

Pull requests automatically trigger dependency review to:

• Identify high-severity vulnerabilities
• Block GPL-3.0 and AGPL-3.0 licenses
• Review new dependencies

See .github/workflows/security-scan.yml for configuration.

Core Dependencies:

• fastapi: Modern web framework
• uvicorn[standard]: ASGI server
• pydantic: Data validation
• pydantic-settings: Settings management with validation
• httpx: Async HTTP client
• web3: Ethereum library
• langchain-openai: OpenAI integration
• pytest: Testing framework
• ruff: Linter and formatter
• black: Code formatter

Optional Heavy Dependencies (install with pip install -r requirements-extras.txt):

• AI/ML Models:

  • transformers==4.48.0: Hugging Face transformers (patched version)
  • torch==2.6.0: PyTorch (patched version)

• Vector Databases:

  • pinecone-client: Pinecone vector database
  • chromadb: Chroma vector database
  • weaviate-client: Weaviate vector database

• Blockchain:

  • anchorpy: Solana/Anchor integration

• Observability:

  • opentelemetry-api: OpenTelemetry API
  • opentelemetry-sdk: OpenTelemetry SDK
  • opentelemetry-instrumentation-fastapi: FastAPI instrumentation

Note: Heavy dependencies are optional to keep base installations lightweight. Only install what you need for your use case.

• next: React framework
• react: UI library
• typescript: Type safety
• zod: Runtime type validation
• eslint: Linter
• prettier: Code formatter
• @typescript-eslint/*: TypeScript ESLint plugins
• ethers: Ethereum library
• viem: Modern Ethereum library
• wagmi: React hooks for Ethereum
• husky: Git hooks
• tsx: TypeScript executor for scripts

• hardhat: Development environment
• @nomicfoundation/hardhat-toolbox: Hardhat plugins bundle

This project includes optional OpenTelemetry integration for observability with no vendor lock-in.

Backend:

# In backend/.env
TELEMETRY_ENABLED=true
TELEMETRY_ENDPOINT=http://localhost:4318  # Your OTLP endpoint

# Install telemetry dependencies
pip install -r requirements-extras.txt

Frontend:

# In frontend/.env.local
NEXT_PUBLIC_TELEMETRY_ENABLED=true

• OpenTelemetry Standards: Uses OTLP (OpenTelemetry Protocol)
• No Vendor Lock-in: Works with any OTLP-compatible backend
• FastAPI Instrumentation: Automatic tracing for API endpoints
• Optional by Default: Disabled unless explicitly enabled

Compatible with: Jaeger, Zipkin, Grafana Tempo, Honeycomb, Datadog, New Relic, and more.

This project uses Renovate for automated dependency updates.

• Schedule: Updates run weekly on Monday mornings (6:00 AM UTC)
• Grouped Updates: Related dependencies are updated together
• Heavy Dependencies: ML/AI packages update monthly
• Auto-merge: Minor and patch updates for non-critical packages
• Security Alerts: High-priority security updates are highlighted

• Python dependencies: All backend dependencies
• Frontend dependencies: Frontend npm packages
• Contract dependencies: Smart contract packages
• Heavy ML dependencies: Transformers, PyTorch (monthly updates)
• Vector databases: Pinecone, Chroma, Weaviate
• GitHub Actions: Workflow action updates

See renovate.json for detailed configuration.

1. Start Backend: cd backend && uvicorn app.main:app --reload
2. Start Frontend: cd frontend && npm run dev
3. Start Local Chain (optional): cd contracts && npm run node
4. Run Tests: Use npm/pytest in respective directories
5. Lint Code: Use ruff/eslint before committing
6. Commit Changes: Pre-commit hooks will run automatically

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linters
5. Commit with descriptive messages
6. Push and create a Pull Request

ISC

Web3AI Team

• FastAPI for the modern Python framework
• Next.js for the React framework
• Hardhat for smart contract development
• OpenAI for AI capabilities
• The open-source community