Skip to content

Latest commit

 

History

History
141 lines (106 loc) · 4.83 KB

cli_usage.md

File metadata and controls

141 lines (106 loc) · 4.83 KB

CLI Usage Guide

This guide provides examples and detailed information on using the gam-afs command-line tools.

Installation and Setup

Ensure you have installed the package:

pip install -e ".[all]"

Configure environment variables for convenience. GAM Agent and Chat Agent can be configured independently:

# GAM Agent (memory building)
export GAM_API_KEY="sk-your-api-key"
export GAM_MODEL="gpt-4o-mini"
export GAM_API_BASE="https://api.openai.com/v1"

# Chat Agent (Q&A) — falls back to GAM Agent config when not set
export GAM_CHAT_API_KEY="sk-your-chat-api-key"
export GAM_CHAT_MODEL="gpt-4o"
export GAM_CHAT_API_BASE="https://api.openai.com/v1"

Commands Overview

The primary commands are gam-add (for building memory) and gam-request (for querying memory). Use the --type text/video flag to switch between modalities.

gam-add — Building Memory

Text Mode (--type text)

# Add a single file
gam-add --type text --gam-dir ./my_gam --input paper.pdf

# Add multiple files
gam-add --type text --gam-dir ./my_gam --input paper1.pdf --input paper2.txt

# Add direct text content
gam-add --type text --gam-dir ./my_gam --content "Some text to memorize"

# Disable chunking (treat input as a single memory)
gam-add --type text --gam-dir ./my_gam --input paper.pdf --no-chunking

Video Mode (--type video)

# Build memory from a video directory (should contain video.mp4 + optional subtitles.srt)
gam-add --type video --gam-dir ./my_video_gam --input ./video_dir

# Use specific models
gam-add --type video --gam-dir ./my_video_gam --input ./video_dir \
    --model gpt-4o --api-key sk-xxx

gam-request — Querying Memory

Text Mode (--type text)

# Basic query
gam-request --type text --gam-dir ./my_gam --question "What is the main conclusion?"

# Custom system prompt + JSON output
gam-request --type text --gam-dir ./my_gam -q "Summarize the paper" \
    --system-prompt "You are a research assistant." --json

Video Mode (--type video)

# Video query
gam-request --type video --gam-dir ./my_video_gam --question "What happens in the video?"

# Use a specific multimodal vision model
gam-request --type video --gam-dir ./my_video_gam -q "Describe the scene" \
    --video-model gpt-4o

CLI Reference

Common Parameters (gam-add / gam-request):

Parameter Default Description
--type, -t (Required) GAM type: text or video
--gam-dir (Required) Path to GAM directory (created automatically)
--model gpt-4o-mini GAM Agent LLM model name (Env: GAM_MODEL)
--api-base https://api.openai.com/v1 GAM Agent API base URL (Env: GAM_API_BASE)
--api-key — GAM Agent API key (Env: GAM_API_KEY or OPENAI_API_KEY)
--max-tokens 4096 Maximum tokens to generate
--temperature 0.3 Sampling temperature
--verbose / --no-verbose --verbose Print detailed logs

gam-add --type text Specific:

Parameter Description
--input, -i Path to input files (can be repeated)
--content, -c Input text content directly (can be repeated)
--context Optional context/description for the input
--chunking / --no-chunking Enable intelligent chunking (default: on)
--output-dir Directory to save raw chunks
--force-reorganize Force reorganization of the directory structure
--memory-workers Parallel memory generation workers (default: 4)

gam-add --type video Specific:

Parameter Description
--input, -i Path to video directory (must contain video.mp4)
--segmentor-model LLM model for segment descriptions
--segmentor-api-base API base for the segmentor model
--segmentor-api-key API key for the segmentor model
--caption-subtitles Include subtitles in descriptions (default: on)

gam-request Specific:

Parameter Description
--question, -q User question (Required)
--system-prompt, -s Custom system prompt
--max-iter Maximum iterations for the exploratory agent (default: 10)
--json Output result in JSON format
--chat-model Chat Agent LLM model name (Env: GAM_CHAT_MODEL, default: same as --model)
--chat-api-base Chat Agent API base URL (Env: GAM_CHAT_API_BASE, default: same as --api-base)
--chat-api-key Chat Agent API key (Env: GAM_CHAT_API_KEY, default: same as --api-key)

gam-request --type video Specific:

Parameter Description
--video-model Multimodal model name for visual analysis
--video-api-base API base for the video model
--video-api-key API key for the video model
--video-fps Sampling rate for video frames (default: 1.0)
--video-max-resolution Max resolution for frames (default: 480)