feat: enhance SDK architecture and documentation

.gitignore

@@ -1,10 +1,95 @@
-*.pth
-*.env
-*#
+# Git Ignore File Guide
+# ---------------------
+# - Each line specifies a pattern for files/directories that Git should ignore
+# - '*' means "match any characters"
+# - A trailing '/' indicates a directory
+# - Lines starting with '#' are comments
+# - Patterns are matched relative to the location of the .gitignore file
+# - More specific rules override more general rules
+# - Use '!' to negate a pattern (include something that would otherwise be ignored)
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.env
+.venv
+.python-version
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
 *~
-*.pyc
-*__pycache__
-*.json
+.project
+.pydevproject
+.settings/
+*.sublime-workspace
+*.sublime-project
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# Distribution / packaging
+.Python
+*.pth
+*.whl
+
+# Logs and databases
+*.log
+*.sqlite
+*.db
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
 
-*.DS_Store
-dist/
+# Project specific
+*.json  # Temporary JSON files
+.env.local
+.env.*.local
+config.local.py

README.md

@@ -98,6 +98,12 @@ Want to help improve the project? Please see our detailed [Contribution Guide](.
 ## Documentation
 Detailed documentation to better understand the configurable components and the GAME architecture can be found on [here](https://whitepaper.virtuals.io/developer-documents/game-framework).
 
+For detailed SDK documentation, see:
+- [Configuration Guide](docs/configuration.md)
+- [Error Handling Guide](docs/error-handling.md)
+- [Testing Guide](docs/testing.md)
+- [SDK Guide](docs/sdk_guide.md)
+
 ## Useful Resources
 - [GAME TypeScript SDK](https://github.com/game-by-virtuals/game-node): The core logic of this SDK mirrors the logic of this python SDK if you prefer to develop your agents in TypeScript. Typescript SDK repository and contributed typescript plugins can be found [here](https://github.com/game-by-virtuals/game-node).
 - [Hosted GAME Agent](./src/game_sdk/hosted_game/README.md): This SDK also enables configuration and deployment of an out-of-the-box hosted agent that can be used to interact with the Twitter/X platform, powered by GAME. This agent comes with existing functions/actions that can be used to interact with the Twitter/X platform and can be immediately hosted/deployed as you configure it. This is similar to configuring your agent in the [Agent Sandbox](https://game-lite.virtuals.io/) on the [Virtuals Platform](https://app.virtuals.io/) but through a developer-friendly SDK interface.

docs/configuration.md

@@ -0,0 +1,126 @@
+# Configuration Guide
+
+The GAME SDK provides a flexible configuration system that allows you to customize its behavior. This guide explains how to configure the SDK for your needs.
+
+## Default Configuration
+
+The SDK comes with sensible defaults:
+
+```python
+DEFAULT_CONFIG = {
+    "api_base_url": "https://game.virtuals.io",
+    "api_version": "v1",
+    "request_timeout": 30,
+    "max_retries": 3,
+    "retry_delay": 1,
+}
+```
+
+## Configuration Methods
+
+There are three ways to configure the SDK:
+
+1. **Environment Variables**:
+   ```bash
+   export GAME_API_BASE_URL="https://custom.api.url"
+   export GAME_API_VERSION="v2"
+   export GAME_REQUEST_TIMEOUT="60"
+   export GAME_MAX_RETRIES="5"
+   export GAME_RETRY_DELAY="2"
+   ```
+
+2. **Runtime Configuration**:
+   ```python
+   from game_sdk.game.config import config
+
+   # Set individual values
+   config.set("request_timeout", 60)
+   config.set("max_retries", 5)
+
+   # Get configuration values
+   timeout = config.get("request_timeout")
+   ```
+
+3. **Initialization Configuration**:
+   ```python
+   from game_sdk.game.config import SDKConfig
+
+   custom_config = SDKConfig(
+       api_base_url="https://custom.api.url",
+       request_timeout=60
+   )
+   ```
+
+## Configuration Priority
+
+The configuration values are applied in the following order (highest priority first):
+1. Runtime configuration (`config.set()`)
+2. Environment variables
+3. Initialization values
+4. Default values
+
+## Available Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `api_base_url` | str | "https://game.virtuals.io" | Base URL for API calls |
+| `api_version` | str | "v1" | API version to use |
+| `request_timeout` | int | 30 | Request timeout in seconds |
+| `max_retries` | int | 3 | Maximum number of retries |
+| `retry_delay` | int | 1 | Delay between retries in seconds |
+
+## Best Practices
+
+1. **Environment-Specific Configuration**:
+   - Use environment variables for environment-specific settings
+   - Use different configurations for development and production
+
+2. **Timeouts**:
+   - Set appropriate timeouts based on your use case
+   - Consider network latency when setting timeouts
+
+3. **Retries**:
+   - Adjust retry settings based on your reliability needs
+   - Consider exponential backoff for production use
+
+## Example Usage
+
+```python
+from game_sdk.game.config import config
+
+# Check current configuration
+print(config.as_dict())
+
+# Update configuration
+config.set("request_timeout", 60)
+
+# Use in API calls
+from game_sdk.game.utils import create_agent
+
+# The API calls will use the updated configuration
+agent = create_agent(
+    base_url="https://api.example.com",
+    api_key="your-key",
+    name="Test Agent",
+    description="Test Description",
+    goal="Test Goal"
+)
+```
+
+## Error Handling
+
+The configuration system will raise `ConfigurationError` if:
+- An invalid configuration key is used
+- An invalid value type is provided
+- Environment variables have invalid values
+
+Example:
+```python
+from game_sdk.game.config import config
+from game_sdk.game.exceptions import ConfigurationError
+
+try:
+    config.set("invalid_key", "value")
+except ConfigurationError as e:
+    print(f"Configuration error: {e}")
+```