Contributing

Contributions are welcome. Here's how to get started.

Getting Started

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/your-username/zero-ichi
   cd zero-ichi

3. Install dependencies:

   pip install uv
   uv sync

Development Workflow

1. Create a new branch for your feature or fix:

   git checkout -b feature/my-cool-feature

2. Make your changes. All source code lives under src/.

3. Format and Lint your code:

   uv run ruff format .
   uv run ruff check .

   IMPORTANT

   CI will fail if code is not formatted or has lint errors.

4. Run the bot to test your changes:

   uv run zero-ichi --debug --auto-reload

   The bot supports auto-reload — file changes are picked up without restarting.

Project Structure

See Architecture for a full breakdown.

• src/commands/ — Add new commands here.
• src/core/ — Core logic (client, middleware, logger, etc.).
• src/ai/ — AI agent, context, memory, and tools.
• src/locales/ — Translation JSON files.
• src/config/ — Static settings loaded from config.json.

Pull Requests

• Keep PRs focused on a single feature or fix.
• Use clear, descriptive titles.
• Describe what you changed and why.
• If you added a feature, include a screenshot or usage example.

Database Migrations (Alembic)

Runtime persistence uses SQLAlchemy with Alembic migration support.

# Apply migrations
uv run alembic upgrade head

# Create a new migration
uv run alembic revision -m "your migration message"

Default database is SQLite (data/zeroichi.db) unless DATABASE_URL is set.

Adding a Command

Create a new file in the appropriate src/commands/<category>/ directory:

from core.command import Command

class MyCommand(Command):
    name = "mycommand"
    description = "Does something cool"
    usage = "/mycommand <arg>"

    async def execute(self, msg, bot, args, prefix):
        await bot.reply(msg, "Hello!")

Commands are auto-discovered — no registration needed.

Adding Translations

Translation files live in src/locales/.

1. Copy src/locales/en.json to src/locales/<code>.json.
2. Update _meta.label with the language name.
3. Translate the values.
4. Submit a PR.

Reporting Bugs

Please use GitHub Issues to report bugs. Include:

• Steps to reproduce
• Expected vs actual behavior
• Logs or screenshots