ملفات تعريف الإعدادات للتطوير والإنتاج

أهمية ملفات تعريف الإعدادات

اكتشاف البيئة باستخدام متغير ENV

import os

# Read the environment identifier
ENV = os.getenv('ENV', 'development').lower()

if ENV not in ('development', 'staging', 'production'):
    raise ValueError(
        f'Invalid ENV value: "{ENV}". '
        f'Must be: development, staging, or production'
    )

print(f'Running in {ENV} mode')

# Usage:
# ENV=development python agent.py   -> dev settings
# ENV=staging python agent.py       -> staging settings
# ENV=production python agent.py    -> prod settings
# python agent.py                   -> defaults to development

فئات إعدادات لكل بيئة

import os

class BaseConfig:
    OPENAI_API_KEY: str = os.environ.get('OPENAI_API_KEY', '')
    MAX_STEPS: int = 20
    LOG_LEVEL: str = 'INFO'
    CACHE_ENABLED: bool = True
    CACHE_TTL_SECONDS: int = 3600

class DevelopmentConfig(BaseConfig):
    MODEL: str = 'gpt-4o-mini'  # cheaper in dev
    LOG_LEVEL: str = 'DEBUG'    # verbose logging in dev
    CACHE_ENABLED: bool = False  # fresh results in dev
    MAX_STEPS: int = 10          # shorter loops in dev

class StagingConfig(BaseConfig):
    MODEL: str = 'gpt-4o-mini'
    LOG_LEVEL: str = 'INFO'
    MAX_STEPS: int = 20

class ProductionConfig(BaseConfig):
    MODEL: str = 'gpt-4o'       # best quality in prod
    LOG_LEVEL: str = 'WARNING'  # less noise in prod
    MAX_STEPS: int = 30         # more steps allowed in prod

if __name__ == '__main__':
    for cls in (DevelopmentConfig, StagingConfig, ProductionConfig):
        c = cls()
        print(f'{cls.__name__}: model={c.MODEL} log_level={c.LOG_LEVEL} max_steps={c.MAX_STEPS} cache={c.CACHE_ENABLED}')

مصنع الإعدادات: اختيار ملف التعريف المناسب

import os

def get_config():
    env = os.getenv('ENV', 'development').lower()
    configs = {
        'development': DevelopmentConfig,
        'staging': StagingConfig,
        'production': ProductionConfig
    }
    config_class = configs.get(env)
    if not config_class:
        raise ValueError(f'Unknown environment: {env}')
    return config_class()

# Usage throughout your agent:
config = get_config()
print(f'Model: {config.MODEL}')
print(f'Max steps: {config.MAX_STEPS}')
print(f'Log level: {config.LOG_LEVEL}')

# All code uses config.MODEL, config.LOG_LEVEL etc.
# Switching environments requires only changing ENV variable

إعدادات Pydantic للإعدادات المقيّدة بالأنواع

# pip install pydantic-settings
from pydantic_settings import BaseSettings
from pydantic import Field
from typing import Literal

class AgentSettings(BaseSettings):
    # Required fields — raise error if not set
    openai_api_key: str
    search_api_key: str

    # Optional with defaults
    env: Literal['development', 'staging', 'production'] = 'development'
    model: str = 'gpt-4o-mini'
    max_steps: int = Field(default=20, ge=1, le=100)  # validated range
    log_level: str = 'INFO'
    cache_enabled: bool = True
    cache_ttl_seconds: int = Field(default=3600, ge=60)

    class Config:
        env_file = '.env'
        case_sensitive = False  # OPENAI_API_KEY -> openai_api_key

# settings = AgentSettings()  # raises ValidationError if required vars missing

إعدادات Pydantic مع تجاوزات خاصة بكل بيئة

from pydantic_settings import BaseSettings
from pydantic import model_validator
import os

class AgentSettings(BaseSettings):
    openai_api_key: str
    env: str = 'development'
    model: str = ''
    log_level: str = ''
    max_steps: int = 0

    @model_validator(mode='after')
    def apply_env_defaults(self) -> 'AgentSettings':
        env_defaults = {
            'development': {'model': 'gpt-4o-mini', 'log_level': 'DEBUG', 'max_steps': 10},
            'staging':     {'model': 'gpt-4o-mini', 'log_level': 'INFO',  'max_steps': 20},
            'production':  {'model': 'gpt-4o',      'log_level': 'WARNING', 'max_steps': 30}
        }
        defaults = env_defaults.get(self.env, env_defaults['development'])
        if not self.model:     self.model     = defaults['model']
        if not self.log_level: self.log_level = defaults['log_level']
        if not self.max_steps: self.max_steps = defaults['max_steps']
        return self

    class Config:
        env_file = '.env'

أعلام الميزات لكل بيئة

import os

class AgentFeatureFlags:
    env = os.getenv('ENV', 'development')

    # Enable memory persistence (requires DB)
    MEMORY_ENABLED: bool = env in ('staging', 'production')

    # Use real payment processing
    REAL_PAYMENTS: bool = env == 'production'

    # Enable verbose step-by-step output
    VERBOSE_STEPS: bool = env == 'development'

    # Use cheap model for unit test runs
    FORCE_MINI_MODEL: bool = os.getenv('CI') == 'true'

flags = AgentFeatureFlags()
print(f'Memory: {flags.MEMORY_ENABLED}')
print(f'Verbose: {flags.VERBOSE_STEPS}')
print(f'Payments: {flags.REAL_PAYMENTS}')

التحقق من الإعدادات عند بدء التشغيل

import os
import sys

def validate_and_print_config(config) -> None:
    print(f'=== Agent Configuration ===')
    print(f'Environment : {config.env}')
    print(f'Model       : {config.model}')
    print(f'Max steps   : {config.max_steps}')
    print(f'Log level   : {config.log_level}')
    print(f'Cache       : {"enabled" if config.cache_enabled else "disabled"}')
    print(f'OpenAI key  : ...{config.openai_api_key[-4:]}')
    print('===========================')

    # Critical validations
    if config.env == 'production' and config.log_level == 'DEBUG':
        print('WARNING: DEBUG logging in production exposes sensitive data!')

    if not config.openai_api_key:
        print('FATAL: OPENAI_API_KEY not set')
        sys.exit(1)

    print('Configuration validated.')

if __name__ == '__main__':
    from types import SimpleNamespace
    demo_config = SimpleNamespace(
        env='development', model='gpt-4o-mini', max_steps=10,
        log_level='DEBUG', cache_enabled=False, openai_api_key='sk-demo-1234'
    )
    validate_and_print_config(demo_config)

تجاوز قيم الإعدادات حسب البيئة

# Staging deployment with custom model override:
# ENV=staging AGENT_MODEL=gpt-4o python agent.py

# Production with reduced max_steps for cost control:
# ENV=production AGENT_MAX_STEPS=15 python agent.py

# CI test run — use production profile but with cheap model:
# ENV=production AGENT_MODEL=gpt-4o-mini CI=true python agent.py

# The config class reads ENV first for the profile,
# then individual overrides take precedence:
import os

env = os.getenv('ENV', 'development')
config = get_config()  # loads base profile for env

# Individual overrides applied on top:
if os.getenv('AGENT_MODEL'):
    config.MODEL = os.getenv('AGENT_MODEL')
if os.getenv('AGENT_MAX_STEPS'):
    config.MAX_STEPS = int(os.getenv('AGENT_MAX_STEPS'))

print(f'Final model: {config.MODEL}')

توثيق ملفات تعريف الإعدادات لأعضاء الفريق

# config_profiles.py — Configuration per environment
#
# | Setting        | development    | staging        | production  |
# |----------------|----------------|----------------|-------------|
# | MODEL          | gpt-4o-mini    | gpt-4o-mini    | gpt-4o      |
# | MAX_STEPS      | 10             | 20             | 30          |
# | LOG_LEVEL      | DEBUG          | INFO           | WARNING     |
# | CACHE_ENABLED  | False          | True           | True        |
# | MEMORY_DB      | SQLite (local) | PostgreSQL     | PostgreSQL  |
#
# To switch environments:
#   ENV=staging python agent.py
#
# To override a single setting:
#   ENV=production AGENT_MAX_STEPS=15 python agent.py

print('Config profile table documents all per-environment differences')

الإعدادات في الاختبارات: فرض ملف تعريف الاختبار

import os
import pytest

@pytest.fixture(autouse=True)
def test_environment(monkeypatch):
    'Force test configuration for all tests'
    monkeypatch.setenv('ENV', 'test')
    monkeypatch.setenv('AGENT_MODEL', 'gpt-4o-mini')
    monkeypatch.setenv('AGENT_MAX_STEPS', '5')  # short loops in tests
    monkeypatch.setenv('LOG_LEVEL', 'DEBUG')
    monkeypatch.setenv('CACHE_ENABLED', 'false')
    # Use a fake API key — tests should mock all LLM calls
    monkeypatch.setenv('OPENAI_API_KEY', 'test-key-not-real')

# This fixture runs before every test automatically
# Tests cannot accidentally use production settings

اختبار المعرفة: ملفات تعريف الإعدادات

مراجعة: ملفات تعريف الإعدادات للتطوير والإنتاج