Installation

FACT Installation Guide

Welcome to the comprehensive installation guide for FACT (Fast Augmented Context Tools). This guide covers all installation methods across different platforms and package managers.

📋 Table of Contents

System Requirements
Quick Start
Installation Methods
Development Setup
Verification & Testing
Troubleshooting
Platform-Specific Notes

🖥️ System Requirements

Minimum Requirements

Component	Requirement
Operating System	Windows 10+, macOS 10.14+, Linux (Ubuntu 18.04+)
Memory	2GB RAM
Storage	1GB free space
CPU	Single-core processor
Network	Internet connection for API access

Recommended Requirements

Component	Requirement
Memory	4GB+ RAM
Storage	5GB+ free space
CPU	Multi-core processor
Python	Python 3.11+
Node.js	Node.js 18+ (for NPM installation)
Rust	Rust 1.70+ (for Cargo installation)

Platform Support

Platform	Python	Rust	NPM	Docker	Status
Linux	✅	✅	✅	✅	Full Support
macOS	✅	✅	✅	✅	Full Support
Windows	✅	✅	✅	✅	Full Support
WSL2	✅	✅	✅	✅	Recommended

🚀 Quick Start

Choose your preferred installation method:

# Python (Recommended for most users)
pip install fact-system

# Rust/Cargo (High performance)
cargo install fact-tools

# NPM (JavaScript integration) - Coming Soon
npm install -g fact-cli

# Docker (Containerized deployment)
docker run -it factteam/fact:latest

📦 Installation Methods

Python Installation

Python is the recommended installation method for most users, providing the complete FACT system with all features.

Method 1: pip install (Stable Release)

# Install latest stable version
pip install fact-system

# Install with all optional dependencies
pip install fact-system[all]

# Install specific extras
pip install fact-system[security,monitoring]

Method 2: conda install

# Create conda environment
conda create -n fact python=3.11
conda activate fact

# Install from conda-forge (coming soon)
conda install -c conda-forge fact-system

Method 3: From Source (Development)

# 1. Clone repository
git clone https://github.com/ruvnet/FACT.git
cd FACT

# 2. Create virtual environment
python -m venv venv

# 3. Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# 4. Install in development mode
pip install -e .

# 5. Install development dependencies
pip install -e .[dev]

Python Environment Setup

# 1. Copy configuration template
cp .env.template .env

# 2. Edit configuration (see Configuration section below)
nano .env  # or your preferred editor

# 3. Initialize system
python -m fact init

# 4. Verify installation
python -m fact validate

Rust/Cargo Installation

The Rust implementation provides maximum performance and is ideal for high-throughput applications.

Method 1: cargo install (Stable Release)

# Install latest stable version
cargo install fact-tools

# Install with all features
cargo install fact-tools --features full

# Install specific features
cargo install fact-tools --features cli,progress,color

Method 2: From crates.io

Add to your Cargo.toml:

[dependencies]
fact-tools = "1.0"

# Or with specific features
fact-tools = { version = "1.0", features = ["full"] }

Method 3: From Source

# 1. Clone repository
git clone https://github.com/ruvnet/FACT.git
cd FACT/cargo-crate

# 2. Build and install
cargo build --release
cargo install --path .

# 3. Run tests
cargo test

# 4. Run benchmarks
cargo bench

Rust Usage Examples

# Basic usage
fact-tools --help

# Process data with caching
fact-tools process --cache --input data.json

# Benchmark performance
fact-tools benchmark --iterations 1000

NPM/NPX Installation

JavaScript/TypeScript integration for Node.js applications and CLI usage.

Note: NPM package is currently in development. Expected release: Q2 2025.

Method 1: Global Installation (Coming Soon)

# Install globally
npm install -g fact-cli

# Use via CLI
fact --help

Method 2: Local Project Installation (Coming Soon)

# Install in project
npm install fact-cli

# Use via npx
npx fact --help

# Add to package.json scripts

Method 3: From Source (Current)

# 1. Clone repository
git clone https://github.com/ruvnet/FACT.git
cd FACT

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

# 4. Test CLI
npm run dev -- --help

# 5. Link globally for development
npm link

NPM Usage Examples

# CLI usage (when available)
fact query "Show technology companies"

# Programmatic usage in Node.js

import { FactClient } from 'fact-cli';

const client = new FactClient({
  apiKey: process.env.ANTHROPIC_API_KEY
});

const result = await client.query("What is Q1 revenue?");
console.log(result);

MCP Server Setup

FACT includes a Model Context Protocol (MCP) server that integrates with Claude Desktop and other MCP-compatible applications.

Current Installation (Project-Specific)

The FACT MCP server is already built and configured for your current project:

# The server is automatically available in Claude Desktop
# No additional setup required for current session

Setup for New Projects

# 1. Clone FACT repository
git clone https://github.com/ruvnet/FACT.git
cd FACT

# 2. Build MCP Server
cd mcp-server
npm install
npm run build

# 3. Add to Claude Desktop
claude mcp add fact-mcp node $(pwd)/dist/index.js

Global NPX Installation (Coming Soon)

Once published to npm:

# Add FACT MCP server globally
claude mcp add fact-mcp npx @fact/mcp-server

# Verify installation
claude mcp list

Available MCP Tools

The FACT MCP server provides these tools to Claude:

mcp__fact-mcp__process_template - Process cognitive templates
mcp__fact-mcp__list_templates - List available templates
mcp__fact-mcp__analyze_context - Context analysis and template suggestions
mcp__fact-mcp__optimize_performance - Performance optimization
mcp__fact-mcp__create_template - Create new templates
mcp__fact-mcp__get_metrics - Performance metrics

MCP Server Verification

# Check if MCP server is running
claude mcp list

# Test MCP tools (ask Claude):
# "List available FACT templates"
# "Get FACT performance metrics"

For detailed MCP integration documentation, see MCP Integration Guide.

Docker Installation

Containerized deployment for easy deployment and scalability.

Method 1: Docker Hub (Coming Soon)

# Pull and run latest image
docker run -it --rm factteam/fact:latest

# Run with volume mounts
docker run -it --rm \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/data:/app/data \
  factteam/fact:latest

Method 2: Docker Compose

# 1. Clone repository
git clone https://github.com/ruvnet/FACT.git
cd FACT

# 2. Copy environment template
cp .env.template .env
# Edit .env with your API keys

# 3. Start services
docker-compose up -d

# 4. View logs
docker-compose logs -f

# 5. Access shell
docker-compose exec fact bash

Method 3: Build from Source

# 1. Clone repository
git clone https://github.com/ruvnet/FACT.git
cd FACT

# 2. Build image
docker build -t fact:local .

# 3. Run container
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your_key_here \
  fact:local

Docker Configuration

Create a docker-compose.yml:

version: '3.8'
services:
  fact:
    image: factteam/fact:latest
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - ARCADE_API_KEY=${ARCADE_API_KEY}
    volumes:
      - ./data:/app/data
      - ./.env:/app/.env
    ports:
      - "8000:8000"  # If running API server
    restart: unless-stopped

🛠️ Development Setup

For contributors and advanced users who want to modify FACT.

Prerequisites

# Install development tools
pip install pre-commit black flake8 mypy pytest

# Install Node.js and npm
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Full Development Environment

# 1. Clone with submodules
git clone --recursive https://github.com/ruvnet/FACT.git
cd FACT

# 2. Set up Python environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -e .[dev,security,monitoring]

# 3. Set up Node.js environment
npm install
npm run build

# 4. Set up Rust environment
cd cargo-crate
cargo build
cd ..

# 5. Install pre-commit hooks
pre-commit install

# 6. Run all tests
python -m pytest
npm test
cargo test

IDE Configuration

VS Code

Install recommended extensions:

Python
Rust Analyzer
TypeScript and JavaScript Language Features

.vscode/settings.json:

{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "rust-analyzer.cargo.target": "wasm32-unknown-unknown",
  "typescript.preferences.importModuleSpecifier": "relative"
}

PyCharm

Open project directory
Configure Python interpreter to use virtual environment
Enable Rust plugin
Configure code style to use Black formatting

✅ Verification & Testing

Quick Verification

# Check all installations
fact --version          # CLI version
python -c "import fact_system; print(fact_system.__version__)"  # Python
cargo --version && fact-tools --version  # Rust
node -e "console.log(require('fact-cli/package.json').version)"  # NPM

System Validation

# Python
python -m fact validate

# Rust
fact-tools validate

# NPM (when available)
fact validate

# Docker
docker run factteam/fact validate

Test Suite

# Python tests
python -m pytest tests/ -v

# Rust tests
cd cargo-crate && cargo test --all-features

# JavaScript tests (when available)
npm test

# Integration tests
python -m pytest tests/integration/ -v

Performance Benchmarks

# Python benchmarks
python scripts/run_benchmarks.py

# Rust benchmarks
cd cargo-crate && cargo bench

# Full system benchmark
python scripts/run_benchmarks.py --include-rust --include-wasm

🔧 Configuration

Environment Variables

Create .env file with required configuration:

# Required API Keys
ANTHROPIC_API_KEY=your_anthropic_api_key_here
ARCADE_API_KEY=your_arcade_api_key_here  # Optional

# Database Configuration
DATABASE_PATH=data/fact_demo.db

# Claude Model Configuration
CLAUDE_MODEL=claude-3-5-sonnet-20241022

# Cache Configuration
CACHE_PREFIX=fact_v1
CACHE_TTL=3600
CACHE_MAX_SIZE=1000

# Performance Configuration
MAX_RETRIES=3
REQUEST_TIMEOUT=30
CONNECTION_POOL_SIZE=10

# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=logs/fact.log

# Security Configuration (Optional)
ENABLE_QUERY_VALIDATION=true
MAX_QUERY_LENGTH=1000
ALLOWED_SQL_OPERATIONS=["SELECT"]

API Key Setup

Anthropic API Key

Visit console.anthropic.com
Create an account or sign in
Navigate to "API Keys"
Create a new key and copy it
Add to .env file

Arcade API Key (Optional)

Visit arcade.dev
Create an account and project
Generate API key
Add to .env file

Test API Connections

# Test Anthropic API
python -c "
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.getenv('ANTHROPIC_API_KEY'))
print('✅ Anthropic API: Connected')
"

# Test complete system
python -m fact demo

🚨 Troubleshooting

Common Installation Issues

Python Version Issues

Problem: Python version not supported

Solution:

# Check Python version
python --version

# Install Python 3.11+ (Ubuntu/Debian)
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-venv

# Install Python 3.11+ (macOS with Homebrew)
brew install [email protected]

# Install Python 3.11+ (Windows)
# Download from python.org and install

Dependency Installation Failures

Problem: pip install fails with permission errors

Solution:

# Use virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Or install with --user flag
pip install --user fact-system

# Upgrade pip first
pip install --upgrade pip

Rust Installation Issues

Problem: cargo install fails

Solution:

# Update Rust
rustup update

# Clear cargo cache
cargo clean

# Install with verbose output
cargo install fact-tools --verbose

# Install specific version
cargo install fact-tools --version 1.0.0

Node.js Issues

Problem: npm install fails

Solution:

# Clear npm cache
npm cache clean --force

# Update Node.js to latest LTS
# Use nvm (Linux/macOS)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts

# Or download from nodejs.org (Windows)

Runtime Issues

API Key Issues

Problem: Invalid API key

Solutions:

# Check if API key is set
echo $ANTHROPIC_API_KEY

# Verify key format (should start with 'sk-ant-')
# Check for trailing spaces or newlines

# Test API key directly
curl -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  https://api.anthropic.com/v1/messages

Database Issues

Problem: Database connection failed

Solutions:

# Check database file permissions
ls -la data/fact_demo.db

# Recreate database
rm data/fact_demo.db
python -m fact init

# Check disk space
df -h

Performance Issues

Problem: Slow response times

Solutions:

# Check system resources
top
free -h

# Clear cache
python -c "
from src.cache.manager import CacheManager
cache = CacheManager()
cache.clear()
"

# Optimize cache settings in .env
CACHE_MAX_SIZE=2000
CACHE_TTL=7200

Memory Issues

Problem: Out of memory errors

Solutions:

# Monitor memory usage
python -c "
import psutil, os
proc = psutil.Process(os.getpid())
print(f'Memory: {proc.memory_info().rss / 1024 / 1024:.1f} MB')
"

# Reduce cache size in .env
CACHE_MAX_SIZE=500

# Use swap file (Linux)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

🖥️ Platform-Specific Notes

Linux

Ubuntu/Debian

# Install system dependencies
sudo apt update
sudo apt install python3-pip python3-venv build-essential \
  libssl-dev libffi-dev python3-dev

# For Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

CentOS/RHEL/Fedora

# Install system dependencies
sudo dnf install python3-pip python3-virtualenv gcc openssl-devel \
  libffi-devel python3-devel

# Or on older systems
sudo yum install python3-pip gcc openssl-devel libffi-devel python3-devel

Arch Linux

# Install system dependencies
sudo pacman -S python-pip python-virtualenv base-devel openssl

# Install Rust
sudo pacman -S rust

macOS

Homebrew Installation

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install [email protected] rust node

# Set up Python
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Xcode Command Line Tools

# Install if not already installed
xcode-select --install

Windows

Using WSL2 (Recommended)

# Install WSL2
wsl --install

# Install Ubuntu in WSL2
wsl --install -d Ubuntu

# Follow Linux installation instructions inside WSL2

Native Windows Installation

# Install Python from python.org
# Download and install Git for Windows
# Install Visual Studio Build Tools

# Install via pip
pip install fact-system

# For Rust, download from rustup.rs

PowerShell Setup

# Set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install Python
winget install Python.Python.3.11

# Install Rust
winget install Rustlang.Rustup

Docker-Specific Notes

Resource Limits

# Increase memory limit for Docker Desktop
# Recommended: 4GB+ RAM, 2GB+ Swap

# Check current limits
docker info | grep -i memory

Volume Mounts

# Correct volume mounting
docker run -it --rm \
  -v "$(pwd)/.env":/app/.env:ro \
  -v "$(pwd)/data":/app/data \
  factteam/fact

📚 Next Steps

After successful installation:

Quick Start Guide - Get started with FACT in 5 minutes
Core Concepts - Understand FACT's architecture
Python Guide - Python-specific usage
API Reference - Complete API documentation
Examples - Code examples and tutorials

🆘 Getting Help

If you encounter issues:

Check logs: Look in logs/fact.log for error details
Run diagnostics: Use python -m fact validate or fact-tools validate
Search issues: Check GitHub Issues
Create issue: Report bugs with logs and system information
Join community: Connect with other users and developers

Installation complete! 🎉 Continue to the Quick Start Guide to begin using FACT.