Build from Source

Instructions for building Pixell components from source code.

Note: This documentation is generated by AI based on the source code, and therefore it may have some incorrect knowledge of the project. In that case, please contact engineering@pixell.global

Prerequisites

Before building Pixell from source, ensure you have the following installed:

System Requirements

• Operating System: Linux, macOS, or Windows
• Memory: At least 8GB RAM (16GB recommended)
• Storage: At least 10GB free disk space
• Network: Internet connection for downloading dependencies

Required Software

Core Dependencies

# Python 3.8+ (required for all components)
python3 --version  # Should be 3.8 or higher
pip3 --version

# Node.js 16+ (required for frontend and build tools)
node --version     # Should be 16 or higher
npm --version

# Go 1.19+ (required for some components)
go version        # Should be 1.19 or higher

# Git (required for version control)
git --version

Development Tools

# Docker (for containerized development)
docker --version
docker-compose --version

# Make (for build automation)
make --version

# curl (for downloading dependencies)
curl --version

Optional Tools

# VS Code (recommended IDE)
code --version

# Pre-commit (for code quality)
pip install pre-commit

# Terraform (for infrastructure)
terraform --version

Clone the Repository

1. Fork and Clone

# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/your-username/pixell.git
cd pixell

# Add upstream remote
git remote add upstream https://github.com/pixell-global/pixell.git

2. Initialize Submodules

# Initialize and update submodules
git submodule update --init --recursive

3. Verify Repository Structure

# Check repository structure
ls -la
# Should see: pak/, par/, pac/, paf-core/, docs/, examples/, tools/, tests/

Build PAK (Agent Kit)

PAK is the development toolkit for building and packaging agents.

Setup

# Navigate to PAK directory
cd pak

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

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

Build Steps

# Install PAK in development mode
pip install -e .

# Build the CLI
python -m pak.cli --help

# Build templates
python -m pak.templates list

# Validate installation
pak --version

Testing

# Run unit tests
pytest tests/

# Run with coverage
pytest --cov=pak tests/

# Run linting
flake8 src/
black --check src/
mypy src/

# Run integration tests
pytest tests/integration/

Build PAR (Runtime)

PAR is the runtime environment for executing agents.

Setup

# Navigate to PAR directory
cd par

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

Build Steps

# Install PAR in development mode
pip install -e .

# Build Docker image
docker build -t pixell-par:latest .

# Build Kubernetes manifests
kubectl apply -f k8s/

# Validate installation
par --version

Testing

# Run unit tests
pytest tests/

# Run with coverage
pytest --cov=par tests/

# Run linting
flake8 src/
black --check src/
mypy src/

# Run integration tests
pytest tests/integration/

# Run load tests
pytest tests/load/

Build PAC (Cloud)

PAC is the cloud platform for managing agents.

Setup

# Navigate to PAC directory
cd pac

# Backend setup
cd src/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Frontend setup
cd ../frontend/
npm install

Build Steps

# Backend build
cd src/
pip install -e .

# Frontend build
cd ../frontend/
npm run build

# Docker build
cd ..
docker build -t pixell-pac:latest .

# Infrastructure build
cd infrastructure/
terraform init
terraform plan

Testing

# Backend tests
cd src/
pytest tests/

# Frontend tests
cd ../frontend/
npm test

# Integration tests
cd ..
pytest tests/integration/

# E2E tests
npm run test:e2e

Build PAF-Core

PAF-Core is the core framework and shared libraries.

Setup

# Navigate to PAF-Core directory
cd paf-core

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

Build Steps

# Install PAF-Core in development mode
pip install -e .

# Build protocol buffers
python -m grpc_tools.protoc --python_out=. --grpc_python_out=. proto/*.proto

# Build documentation
cd docs/
make html

# Validate installation
python -c "import paf_core; print(paf_core.__version__)"

Testing

# Run unit tests
pytest tests/

# Run with coverage
pytest --cov=paf_core tests/

# Run linting
flake8 src/
black --check src/
mypy src/

# Run protocol buffer tests
pytest tests/proto/

Development Workflow

1. Daily Development

# Start development environment
docker-compose up -d

# Run tests
make test

# Run linting
make lint

# Run type checking
make type-check

# Run build
make build

2. Feature Development

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes
# ... edit code ...

# Run tests
make test

# Commit changes
git add .
git commit -m "feat: add your feature"

# Push branch
git push origin feature/your-feature-name

# Create pull request
# ... on GitHub ...

3. Release Process

# Update version
# ... edit version files ...

# Run full test suite
make test-all

# Build release
make build-release

# Tag release
git tag v1.0.0
git push origin v1.0.0

# Publish packages
make publish

Docker Development

Development Environment

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Individual Services

# Start specific service
docker-compose up -d par

# Rebuild service
docker-compose build par
docker-compose up -d par

# Execute commands in container
docker-compose exec par bash

Custom Development

# Build custom image
docker build -t pixell-custom:latest .

# Run with custom configuration
docker run -p 8080:8080 -v $(pwd)/config:/app/config pixell-custom:latest

Kubernetes Development

Local Kubernetes

# Start local cluster
minikube start

# Deploy to Kubernetes
kubectl apply -f k8s/

# View pods
kubectl get pods

# View logs
kubectl logs -f deployment/pixell-par

Production Kubernetes

# Deploy with Helm
helm install pixell ./helm/pixell

# Upgrade deployment
helm upgrade pixell ./helm/pixell

# View status
helm status pixell

Performance Optimization

Build Optimization

# Parallel builds
make -j$(nproc) build

# Cache dependencies
docker build --cache-from pixell-base:latest .

# Optimize Docker images
docker build --target production .

Runtime Optimization

# Profile performance
python -m cProfile -o profile.stats main.py

# Memory profiling
python -m memory_profiler main.py

# CPU profiling
python -m py-spy record -o profile.svg -- python main.py

Troubleshooting

Common Issues

1. Python Version Issues

Problem: Python version mismatch Solution:

# Check Python version
python3 --version

# Use pyenv to manage versions
pyenv install 3.9.0
pyenv local 3.9.0

2. Dependency Conflicts

Problem: Package dependency conflicts Solution:

# Create fresh virtual environment
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

3. Docker Build Issues

Problem: Docker build fails Solution:

# Clean Docker cache
docker system prune -a

# Rebuild without cache
docker build --no-cache -t pixell:latest .

4. Port Conflicts

Problem: Port already in use Solution:

# Find process using port
lsof -i :8080

# Kill process
kill -9 <PID>

# Or use different port
export PAR_PORT=8081

Debug Mode

# Enable debug logging
export PIXELL_DEBUG=true
export PIXELL_LOG_LEVEL=debug

# Run with debugger
python -m pdb main.py

# Run with profiling
python -m cProfile main.py

Log Analysis

# View logs
tail -f logs/pixell.log

# Filter logs
grep "ERROR" logs/pixell.log

# Analyze logs
python -m log_analyzer logs/pixell.log

Environment Configuration

Development Environment

# Set development environment
export PIXELL_ENV=development
export PIXELL_DEBUG=true
export PIXELL_LOG_LEVEL=debug

# Database
export DATABASE_URL=sqlite:///dev.db

# Cache
export REDIS_URL=redis://localhost:6379

Staging Environment

# Set staging environment
export PIXELL_ENV=staging
export PIXELL_DEBUG=false
export PIXELL_LOG_LEVEL=info

# Database
export DATABASE_URL=postgresql://staging.db

# Cache
export REDIS_URL=redis://staging-redis:6379

Production Environment

# Set production environment
export PIXELL_ENV=production
export PIXELL_DEBUG=false
export PIXELL_LOG_LEVEL=warn

# Database
export DATABASE_URL=postgresql://prod.db

# Cache
export REDIS_URL=redis://prod-redis:6379

Continuous Integration

GitHub Actions

# .github/workflows/build.yml
name: Build and Test

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.9
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install -r requirements-dev.txt
      - name: Run tests
        run: pytest
      - name: Run linting
        run: |
          flake8 src/
          black --check src/
          mypy src/

Pre-commit Hooks

# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run hooks
pre-commit run --all-files

Next Steps

After building from source:

1. How to Contribute - Start contributing to the project
2. Code Structure - Understand the codebase organization
3. Roadmap - See what features are planned
4. Run examples - Try the example agents
5. Start developing - Make your first contribution!

---

Ready to start developing? Check out How to Contribute to start contributing to Pixell!