# komAI Agent Guidelines

## Репозиторий

https://git.komisar.gin.by/komisar/komAI

## Entry Point

```
python -m app.komAI
```

## Architecture

- `app/` - application entry point (komAI.py expected)
- `src/` - source code
- `src/utils/` - utilities (config_manager, log_manager)
- `config/` - YAML configuration; `config/global.yaml` is the main config
- `modules/` - pluggable modules
- `tests/` - standalone unit tests
- `log/` - runtime logs

## Config System

Access via:
```python
import src.utils.config_manager as config
config = config.config
```

Key APIs:
- `config.register(name, val, default, desc, cat, env, validator)`
- `config.get(name, cat)` / `config.getraw(key)`
- `config.set(name, value, cat)` / `config.setraw(key, value)`
- `config.getall(name, cat)` / `config.getrawall(cat)`
- `config.load()` / `config.save()` / `config.reset()`

Constants: `ROOT_KEY = "$root$"`, `DEFAULT_CATEGORY = "global"`

## Logging

Access via:
```python
import src.utils.log_manager as log
```

Key APIs:
- `log.register_global_params()` - register global logging params
- `log.register(module, log_console, log_stderr, log_file, log_level)` - register module
- `log.setup()` - initialize logging
- `log.get_logger(module)` - get logger instance
- `logger.print(msg, level)` - print to console (use instead of print())

**Rule: Never use `print()` - always use `logger.print()`**

Constants: `LOG_CATEGORY`, `LOG_CONSOLE`, `LOG_STDERR`, `LOG_FILE`, `LOG_LEVEL`, etc.

## Env Vars (see `.env.example`)

- `KOMAI_CONFIG_FILE` - path to config file (optional)

## Requirements

- Python >3.10

## Module Development

When creating new modules:

1. Register parameters:
```python
import src.utils.config_manager as config
config.register(name="param", val="value", cat="module_name", ...)
```

2. Use logging:
```python
import src.utils.log_manager as log
log.register(module="module_name", log_console=True, ...)
logger = log.get_logger("module_name")
logger.print("message")  # never print()
```

3. Never use `print()` directly - use `logger.print()` instead

## Testing

```bash
python -m tests.test_config_manager
python -m tests.test_log_manager
```