Development Setup

This guide will help you set up a complete development environment for ARKOS, including all dependencies and configurations.

System Requirements

Minimum Requirements

OS: Ubuntu 20.04+, macOS 11+, or Windows 10+ with WSL2
Python: 3.8 or higher
RAM: 8GB minimum
Storage: 20GB free space
CPU: 4 cores recommended

Recommended Requirements

RAM: 16GB or more
GPU: NVIDIA GPU with 8GB+ VRAM (for local models)
Storage: 50GB+ for model files
CPU: 8+ cores for better performance

Environment Setup

1. Python Environment

Using venv
Using conda

# Create virtual environment
python3 -m venv arkos-env

# Activate environment
# On Linux/Mac:
source arkos-env/bin/activate
# On Windows:
arkos-env\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Create conda environment
conda create -n arkos python=3.10

# Activate environment
conda activate arkos

# Install pip in conda env
conda install pip

2. Clone Repository

# Clone the repository
git clone https://github.com/SGIARK/arkos.git
cd arkos

3. Install Dependencies

pip install -r requirements.txt

Dependencies Overview

Current Dependencies (requirements.txt)

openai>=1.61.0
pyyaml>=6.0.2
pydantic>=2.10.6
requests>=2.32.3
fastapi>=0.115.0
uvicorn>=0.32.0
psycopg2-binary>=2.9.11
vecs
mem0ai
sentence-transformers
python-dotenv>=1.0.0
aiohttp>=3.9.0
google-auth-oauthlib>=1.2.0

Dependency Details

Package	Purpose
`openai`	AsyncOpenAI client for LLM communication
`pyyaml`	YAML configuration parsing
`pydantic`	Data validation and message schemas
`fastapi` + `uvicorn`	API server
`psycopg2-binary`	PostgreSQL database adapter
`mem0ai`	Vector memory with Supabase
`sentence-transformers`	Embeddings for memory
`python-dotenv`	Environment variable loading
`aiohttp`	Async HTTP client
`google-auth-oauthlib`	Google OAuth for calendar

Configuration Files

1. Environment Variables (.env)

Create a .env file in the project root:

cp .env.example .env

Edit .env with your configuration:

# Database Connection (REQUIRED)
# Format: postgresql://user:password@host:port/database
DB_URL=postgresql://postgres:your-password@localhost:54322/postgres

# Hugging Face Token (OPTIONAL - for gated models)
HF_TOKEN=

# MCP Server Credentials (OPTIONAL - for tool integrations)
GOOGLE_OAUTH_CREDENTIALS=
GOOGLE_CALENDAR_MCP_TOKEN_PATH=
BRAVE_API_KEY=

# OpenAI API Key (REQUIRED by mem0, but can be placeholder)
OPENAI_API_KEY=sk-placeholder

The DB_URL environment variable is required. ARKOS uses PostgreSQL for conversation context storage.

2. YAML Configuration

The main configuration file is config_module/config.yaml:

app:
  host: "0.0.0.0"
  port: 1111
  reload: false
  system_prompt: "You are a helpful AI assistant."

llm:
  base_url: "http://localhost:30000/v1"

database:
  url: "${DB_URL}"

memory:
  user_id: "default_user"
  use_long_term: false

state:
  graph_path: "state_module/state_graph.yaml"

# MCP Server Configuration (optional)
mcp_servers:
  google-calendar:
    transport: stdio
    command: npx
    args: ["-y", "@anthropic/google-calendar-mcp"]

Database Setup

PostgreSQL (Required)

ARKOS requires PostgreSQL for conversation context storage.

Using Supabase (Recommended)

Create a Supabase project
Get your connection string from Settings > Database
Set DB_URL in your .env file

Using Local PostgreSQL

# Install PostgreSQL
sudo apt-get install postgresql postgresql-contrib

# Create database
sudo -u postgres psql
CREATE DATABASE arkos;
CREATE USER arkos_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE arkos TO arkos_user;
\q

Database Schema

Create the required table:

CREATE TABLE conversation_context (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255) NOT NULL,
    session_id VARCHAR(255) NOT NULL,
    role VARCHAR(50) NOT NULL,
    message TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_user_id ON conversation_context(user_id);
CREATE INDEX idx_session_id ON conversation_context(session_id);

Running SGLANG

Check if Already Running

On shared servers, the LLM server may already be running:

# Check if port 30000 is in use
lsof -i :30000

# Or verify it's responding
curl http://localhost:30000/v1/models

Start the LLM Server

cd arkos
bash model_module/run.sh

This starts the SGLang server on port 30000 with the Qwen 2.5-7B-Instruct model.

Only one instance can run on port 30000 at a time. Coordinate with your team on shared servers.

Running the Application

1. Start the LLM Server

# Terminal 1
bash model_module/run.sh

Wait for “server started” messages.

2. Start the API Server

# Terminal 2
python base_module/app.py

This starts FastAPI on port 1111.

3. Start the CLI Interface (Optional)

# Terminal 3
python base_module/main_interface.py

Verify Setup

# Health check
curl http://localhost:1111/health

# Test chat
curl -X POST http://localhost:1111/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "ark-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

IDE Configuration

VS Code

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/arkos-env/bin/python",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"],
  "editor.formatOnSave": true
}

PyCharm

Set Python interpreter to virtual environment
Enable pytest as test runner
Configure code style with Black formatter

Testing

Running Tests

# Run specific test files
python model_module/tests_arkmodel.py
python config_module/test_config_loader.py
python tool_module/test_tool_call.py

# Run with pytest (if available)
pytest tests/

Test Configuration

# pytest.ini (if using pytest)
[pytest]
testpaths = tests
python_files = test_*.py
asyncio_mode = auto

Debugging

Enable Debug Logging

import logging
logging.basicConfig(level=logging.DEBUG)

VS Code Launch Configuration

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug API Server",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/base_module/app.py",
      "console": "integratedTerminal"
    },
    {
      "name": "Debug CLI",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/base_module/main_interface.py",
      "console": "integratedTerminal"
    }
  ]
}

Common Issues

ImportError: No module named 'module_name'

Add the project root to PYTHONPATH:

export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Database connection failed

Verify your DB_URL in .env:

psql $DB_URL -c "SELECT 1"

LLM server not responding

Check if SGLang is running:

curl http://localhost:30000/v1/models

If not, start it with bash model_module/run.sh

Port already in use

Find and kill the process:

lsof -i :1111
kill -9 <PID>

CUDA out of memory

Reduce batch size or use a smaller model:

os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'max_split_size_mb:512'

Environment variable not found

Ensure .env file exists and is in the project root:

ls -la .env
cat .env

Project Structure

arkos/
├── agent_module/         # Agent orchestration
│   ├── __init__.py
│   └── agent.py
├── base_module/          # API server and CLI
│   ├── __init__.py
│   ├── app.py           # FastAPI server
│   ├── auth.py          # OAuth routes
│   └── main_interface.py # CLI
├── config_module/        # Configuration
│   ├── __init__.py
│   ├── loader.py        # Config loading
│   ├── config.yaml      # Main config
│   └── state_graph.yaml # State machine
├── memory_module/        # Memory system
│   ├── __init__.py
│   └── memory.py
├── model_module/         # LLM interface
│   ├── __init__.py
│   ├── ArkModelNew.py
│   └── run.sh           # SGLang startup
├── state_module/         # State machine
│   ├── __init__.py
│   ├── state.py
│   ├── state_handler.py
│   └── state_registry.py
├── tool_module/          # MCP tools
│   ├── __init__.py
│   ├── tool_call.py     # MCP client
│   ├── token_store.py   # OAuth tokens
│   └── transports/      # Transport layer
├── .env.example
├── .gitignore
├── README.md
└── requirements.txt

Next Steps

Testing Guide

Learn about testing strategies

Quick Start

Start using ARKOS

Architecture

Understand the system design

API Reference

Explore the APIs

Getting Started

Architecture

Core Modules

Development

​Development Setup

​System Requirements

​Minimum Requirements

​Recommended Requirements

​Environment Setup

​1. Python Environment

​2. Clone Repository

​3. Install Dependencies

​Dependencies Overview

​Current Dependencies (requirements.txt)

​Dependency Details

​Configuration Files

​1. Environment Variables (.env)

​2. YAML Configuration

​Database Setup

​PostgreSQL (Required)

​Using Supabase (Recommended)

​Using Local PostgreSQL

​Database Schema

​Running SGLANG

​Check if Already Running

​Start the LLM Server

​Running the Application

​1. Start the LLM Server

​2. Start the API Server

​3. Start the CLI Interface (Optional)

​Verify Setup

​IDE Configuration

​VS Code

​PyCharm

​Testing

​Running Tests

​Test Configuration

​Debugging

​Enable Debug Logging

​VS Code Launch Configuration

​Common Issues

​Project Structure

​Next Steps

Testing Guide

Quick Start

Architecture

API Reference

Development Setup

System Requirements

Minimum Requirements

Recommended Requirements

Environment Setup

1. Python Environment

2. Clone Repository

3. Install Dependencies

Dependencies Overview

Current Dependencies (requirements.txt)

Dependency Details

Configuration Files

1. Environment Variables (.env)

2. YAML Configuration

Database Setup

PostgreSQL (Required)

Using Supabase (Recommended)

Using Local PostgreSQL

Database Schema

Running SGLANG

Check if Already Running

Start the LLM Server

Running the Application

1. Start the LLM Server

2. Start the API Server

3. Start the CLI Interface (Optional)

Verify Setup

IDE Configuration

VS Code

PyCharm

Testing

Running Tests

Test Configuration

Debugging

Enable Debug Logging

VS Code Launch Configuration

Common Issues

Project Structure

Next Steps