pyproject.toml

[project]
name = "ZorkGPT"
version = "0.1.0"
description = "Teaching AI to play the classic text adventure Zork using Large Language Models"
requires-python = ">=3.11"
dependencies = [
    "openai>=1.79.0",
    "pydantic>=2.11.4",
    "requests>=2.31.0",
    "python-dotenv>=1.0.0",
    "jericho>=3.3.0",
    # needed for Jericho get_valid_actions() call
    "en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl",
    "langfuse>=3.8.1,<4.0",
    "filelock>=3.20.0",
    "pydantic-settings>=2.11.0",
]

[project.optional-dependencies]
test = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
]
s3 = [
    "boto3>=1.34.0",
]

[dependency-groups]
dev = [
    "pytest>=8.3.5",
]

[tool.zorkgpt.llm]
# LLM Configuration
client_base_url = "https://openrouter.ai/api/v1"
agent_model = "deepseek/deepseek-v3.2-exp"
info_ext_model = "google/gemma-3-27b-it"
critic_model = "deepseek/deepseek-v3.2-exp"
analysis_model = "deepseek/deepseek-v3.2-exp"
memory_model = "deepseek/deepseek-v3.2-exp"

# Per-model base URLs (optional, for cost optimization)
# If not specified, will fall back to client_base_url
# Examples:
# agent_base_url = "https://api.together.xyz/v1"
# info_ext_base_url = "http://oracle.nord:1234/v1"
# critic_base_url = "http://oracle.nord:1234/v1"
# analysis_base_url = "https://api.openai.com/v1"

[tool.zorkgpt.retry]
# Retry and Exponential Backoff Configuration
#
# The retry system automatically handles:
# - Empty or whitespace-only responses (reasoning models sometimes return these)
# - Rate limit errors (429 status code)
# - Server errors (5xx status codes)
# - Timeout errors
#
# Reasoning models (DeepSeek R1, QwQ, o1/o3) automatically get max_tokens=8000
# if not explicitly specified to prevent token exhaustion during long reasoning chains.
#
max_retries = 5
initial_delay = 1.0           # Initial retry delay in seconds
max_delay = 60.0              # Maximum retry delay in seconds
exponential_base = 2.0        # Multiplier for exponential backoff
jitter_factor = 0.1           # Random jitter to prevent thundering herd (0.0 to 1.0)
retry_on_timeout = true
retry_on_rate_limit = true
retry_on_server_error = true  # 5xx errors
timeout_seconds = 120.0
# Circuit breaker settings
circuit_breaker_enabled = true
circuit_breaker_failure_threshold = 10    # Number of failures before opening circuit
circuit_breaker_recovery_timeout = 300.0  # Seconds before trying to close circuit
circuit_breaker_success_threshold = 3     # Consecutive successes needed to close circuit

[tool.zorkgpt.agent_sampling]
# Agent LLM Sampling Parameters, taken from Qwen model card
temperature = 0.6
top_p = 0.95
top_k = 20
min_p = 0.0
max_tokens = 2000  # Prevent runaway thinking loops (prompt asks for 50-150 tokens, this gives 10-20x safety margin)

[tool.zorkgpt.critic_sampling]
# Critic LLM Sampling Parameters
temperature = 0.1  # Low temperature for consistent validation logic
max_tokens = 100
# top_p = null     # Optional - leave commented for default
# top_k = null     # Optional - leave commented for default
# min_p = null     # Optional - leave commented for default

[tool.zorkgpt.extractor_sampling]
# Information Extractor LLM Sampling Parameters
temperature = 0.1
max_tokens = 400
# top_p = null     # Optional - leave commented for default
# top_k = null     # Optional - leave commented for default
# min_p = null     # Optional - leave commented for default

[tool.zorkgpt.memory_sampling]
# Memory Synthesis LLM Sampling Parameters
temperature = 0.3
max_tokens = 6000  # Handles batch supersession of 10+ memories
memory_history_window = 3
# top_p = null     # Optional - leave commented for default
# top_k = null     # Optional - leave commented for default
# min_p = null     # Optional - leave commented for default

[tool.zorkgpt.analysis_sampling]
# Analysis Model LLM Sampling Parameters (for knowledge generation)
temperature = 0.3
top_p = 0.8     # Optional - leave commented for default
top_k = 20     # Optional - leave commented for default
min_p = 0.0     # Optional - leave commented for default
max_tokens = 5000  # Optional - leave commented to use default

[tool.zorkgpt.gameplay]
# Gameplay Configuration
turn_delay_seconds = 3.0
turn_window_size = 100
min_knowledge_quality = 6.0
critic_rejection_threshold = -0.2  # More permissive from -0.05 to allow more experimentation
enable_critic = true  # Toggle LLM critic evaluation (object tree validation always runs)
# Exit pruning configuration
enable_exit_pruning = true
exit_failure_threshold = 2  # Reduced from 3 to more quickly abandon failed directions
# Save/restore configuration
zork_save_filename_template = "zorkgpt_save_{timestamp}"
zork_game_workdir = "game_files"

[tool.zorkgpt.orchestrator]
# Orchestrator Configuration
max_turns_per_episode = 500
knowledge_update_interval = 100
objective_update_interval = 15
enable_state_export = true

enable_objective_refinement = true
objective_refinement_interval = 50
max_objectives_before_forced_refinement = 15
refined_objectives_target_count = 8

# Inter-episode synthesis configuration
enable_inter_episode_synthesis = true

[tool.zorkgpt.objective_completion]
enable_llm_check = true
check_interval = 1
history_window = 3
include_memories = true

[tool.zorkgpt.simple_memory]
# Simple Memory System Configuration
memory_file = "Memories.md"
max_memories_shown = 10

[tool.zorkgpt.files]
# File Configuration
episode_log_file = "zork_episode_log.txt"
json_log_file = "zork_episode_log.jsonl"
state_export_file = "current_state.json"
map_state_file = "map_state.json"
knowledge_file = "knowledgebase.md"
game_file_path = "jericho-game-suite/zork1.z5"

[tool.zorkgpt.loop_break]
# Progress velocity detection
max_turns_stuck = 40              # Conservative threshold
stuck_check_interval = 10         # Check every 10 turns
enable_objective_based_progress = true  # Enable objective completion as progress (alongside score increases)

# Location revisit penalty (programmatic)
enable_location_penalty = true
location_revisit_penalty = -0.2
location_revisit_window = 5       # Check last 5 locations

# Exploration guidance (context-based)
enable_exploration_hints = true
action_novelty_window = 15        # Check last 15 actions

# Stuck countdown warnings
enable_stuck_warnings = true
stuck_warning_threshold = 20      # Start warnings at 20 turns stuck

[tool.zorkgpt.aws]
# AWS Configuration (optional)
s3_key_prefix = "zorkgpt/"