> ## Documentation Index
> Fetch the complete documentation index at: https://arkos.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get up and running with ARKOS in minutes

# Quick Start Guide

This guide will help you set up ARKOS and create your first intelligent agent with persistent memory.

## Prerequisites

Before you begin, ensure you have:

* Python 3.8 or higher
* Git
* PostgreSQL database (Supabase recommended)
* 8GB+ RAM recommended
* GPU optional but recommended for local models

## Installation

### 1. Clone the Repository

```bash theme={null}
git clone https://github.com/SGIARK/arkos.git
cd arkos
```

### 2. Install Dependencies

```bash theme={null}
pip install -r requirements.txt
```

### 3. Configure Your Environment

Create a `.env` file in the project root:

```bash theme={null}
cp .env.example .env
```

Edit `.env` with your configuration:

```env theme={null}
# 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
```

<Warning>
  The `DB_URL` environment variable is **required**. ARKOS uses PostgreSQL for storing conversation context and Supabase for vector memory.
</Warning>

## Starting the Inference Engine

### Check if LLM Server is Already Running

Since ARKOS is often deployed on shared servers, check if the LLM server is already running:

```bash theme={null}
# Check if port 30000 is in use
lsof -i :30000

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

If you see output, the LLM server is already running - you can skip starting it.

### Starting the LLM Server (if not running)

The project uses SGLang to run the Qwen 2.5-7B-Instruct model:

```bash theme={null}
bash model_module/run.sh
```

This starts the SGLang server on **port 30000** using Docker and GPU. Wait for "server started" messages.

### Starting the Embedding Server (if not running)

The project uses Huggingface-TEI to run the Qwen 2 1.5B-Instruct model

```bash theme={null}
bash model_module/run_tei.sh
```

This starts the SGLang server on **port 4444** using Docker and GPU. Wait for "server started" messages.

## Running Your First Agent

### 1. Start the API Server

```bash theme={null}
python base_module/app.py
```

This starts the FastAPI server on **port 1111**, providing the `/v1/chat/completions` endpoint.

### 2. Run the Test Interface

In another terminal:

```bash theme={null}
python base_module/main_interface.py
```

This provides an interactive CLI to test the agent. Type your messages and press Enter. Type `exit` or `quit` to stop.

## Basic Usage Examples

### Using the OpenAI-Compatible API

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1111/v1",
    api_key="not-needed"  # Local deployment
)

response = client.chat.completions.create(
    model="ark-agent",
    messages=[
        {"role": "user", "content": "Hello! What can you help me with?"}
    ]
)

print(response.choices[0].message.content)
```

### Streaming Responses

```python theme={null}
stream = client.chat.completions.create(
    model="ark-agent",
    messages=[{"role": "user", "content": "Tell me about ARKOS"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### Using Memory Directly

```python theme={null}
from memory_module.memory import Memory
from model_module.ArkModelNew import UserMessage, AIMessage, SystemMessage

# Initialize memory system
memory = Memory(
    user_id="alice",
    session_id=None,  # Auto-generates session ID
    db_url="postgresql://...",
    use_long_term=True  # Enable Mem0 vector memory
)

# Store a message
memory.add_memory(UserMessage(content="My favorite color is blue"))

# Retrieve recent context
context = memory.retrieve_short_memory(turns=5)

# Retrieve relevant long-term memories
long_term = memory.retrieve_long_memory(context=context)
```

## Configuration Files

### Main Configuration (`config_module/config.yaml`)

```yaml theme={null}
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  # Set to true to enable Mem0

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"]
```

### State Graph Configuration (`state_module/state_graph.yaml`)

```yaml theme={null}

initial: agent_reply

states:
  ask_user:
    description: "state used for input from user"
    type: user 
    transition:
      next: [agent_reply]

  agent_reply:
    description: "state used for your reasoning"
    type: agent
    transition:
      next: [ask_user, use_tool]

  use_tool:
    description: "state used for tool use"
    type: tool
    transition: 
      next: [agent_reply]

```

## Testing Your Setup

### Health Check

```bash theme={null}
curl http://localhost:1111/health
```

Expected response:

```json theme={null}
{"status": "ok", "llm_server": "running", "port": 1111}
```

### Test Chat Completion

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

## Common Issues and Solutions

<AccordionGroup>
  <Accordion title="Database connection failed">
    Ensure your `DB_URL` is correctly set in `.env`:

    ```bash theme={null}
    # Check if PostgreSQL is accessible
    psql $DB_URL -c "SELECT 1"
    ```

    Make sure the `conversation_context` table exists in your database.
  </Accordion>

  <Accordion title="LLM server not responding">
    Check if the SGLang server is running on port 30000:

    ```bash theme={null}
    curl http://localhost:30000/v1/models
    ```

    If not running, start it with `bash model_module/run.sh`
  </Accordion>

  <Accordion title="CUDA/GPU not detected">
    Ensure PyTorch is installed with CUDA support:

    ```bash theme={null}
    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
    ```
  </Accordion>

  <Accordion title="Port already in use">
    Find and kill the process using the port:

    ```bash theme={null}
    lsof -i :1111
    kill -9 <PID>
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture Overview" icon="building" href="/architecture/overview">
    Understand the system architecture
  </Card>

  <Card title="Module Documentation" icon="book" href="/modules/agent/overview">
    Deep dive into each module
  </Card>

  <Card title="Development Setup" icon="code" href="/development/setup">
    Set up your development environment
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Explore the API endpoints
  </Card>
</CardGroup>

## Getting Help

* **GitHub Issues**: [Report bugs or request features](https://github.com/SGIARK/arkos/issues)
* **Documentation**: You're already here!
* **Community**: Join our discussions on GitHub