# Visit https://github.com/omnirexflora-labs/OmniDaemon
# Click "Fork" button

# Clone your fork
git clone https://github.com/YOUR_USERNAME/OmniDaemon.git
cd OmniDaemon

# Install uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv sync

# Install development dependencies
uv add --dev pytest pytest-asyncio pytest-cov black ruff mypy

# Verify installation
python -c "import omnidaemon; print('✅ OmniDaemon installed')"

# Create a descriptive branch name
git checkout -b feature/add-kafka-support
# or
git checkout -b fix/redis-connection-timeout

# ✅ Good
async def process_message(message: dict) -> dict:
    """
    Process a message from the event bus.

    Args:
        message: Event envelope containing payload

    Returns:
        Processed result dictionary
    """
    result = await ai_agent.process(message["content"])
    return {"status": "success", "result": result}


# ❌ Bad
async def process(msg):  # Missing type hints, unclear name
    return await agent.run(msg['data'])  # No error handling

# Format code with black
black src/ tests/

# Check with ruff
ruff check src/ tests/

# Type checking with mypy
mypy src/

# Standard library
import os
import asyncio
from typing import Optional, Dict, Any

# Third-party
import redis.asyncio as redis
from pydantic import BaseModel

# Local
from omnidaemon import EventEnvelope
from omnidaemon.event_bus import get_event_bus

# Run all tests
pytest

# Run with coverage
pytest --cov=src/omnidaemon --cov-report=html

# Run specific test file
pytest tests/test_sdk.py

# Run specific test
pytest tests/test_sdk.py::test_publish_task

# tests/test_my_feature.py
import pytest
from omnidaemon import OmniDaemonSDK

@pytest.mark.asyncio
async def test_publish_task():
    """Test task publishing functionality."""
    sdk = OmniDaemonSDK()

    # Arrange
    topic = "test.topic"
    payload = {"content": "test message"}

    # Act
    message_id = await sdk.publish_task(
        topic=topic,
        payload=payload
    )

    # Assert
    assert message_id is not None
    assert isinstance(message_id, str)


@pytest.mark.asyncio
async def test_register_agent():
    """Test agent registration."""
    sdk = OmniDaemonSDK()

    async def test_callback(message):
        return {"status": "success"}

    # Act
    sdk.register_agent(
        agent_config=AgentConfig(
            name="TestAgent",
            topics=["test.topic"]
        ),
        callback=test_callback
    )

    # Assert
    agents = await sdk.list_agents()
    assert len(agents) > 0

# src/omnidaemon/event_bus/kafka_bus.py

from omnidaemon.event_bus.base import BaseEventBus
from typing import Callable, Optional

class KafkaEventBus(BaseEventBus):
    """
    Kafka-based event bus implementation.

    Uses Apache Kafka for durable, high-throughput messaging.

    Args:
        bootstrap_servers: Kafka bootstrap servers
        group_id: Consumer group ID
        **kafka_config: Additional Kafka configuration

    Example:
        >>> bus = KafkaEventBus(
        ...     bootstrap_servers="localhost:9092",
        ...     group_id="omnidaemon-agents"
        ... )
        >>> await bus.connect()
    """

    def __init__(
        self,
        bootstrap_servers: str,
        group_id: str = "omnidaemon",
        **kafka_config
    ):
        self.bootstrap_servers = bootstrap_servers
        self.group_id = group_id
        self.kafka_config = kafka_config
        self.producer = None
        self.consumer = None

    async def connect(self) -> None:
        """Establish connection to Kafka cluster."""
        from aiokafka import AIOKafkaProducer, AIOKafkaConsumer

        self.producer = AIOKafkaProducer(
            bootstrap_servers=self.bootstrap_servers,
            **self.kafka_config
        )
        await self.producer.start()

    async def publish(
        self,
        topic: str,
        payload: dict,
        **kwargs
    ) -> str:
        """Publish message to Kafka topic."""
        import json

        message = json.dumps(payload).encode('utf-8')
        metadata = await self.producer.send(topic, message)
        return f"{metadata.topic}-{metadata.partition}-{metadata.offset}"

    # Implement other abstract methods...

**Bug Description**
A clear description of the bug.

**To Reproduce**
Steps to reproduce the behavior:
1. Install OmniDaemon via `uv add omnidaemon`
2. Run agent with Redis backend
3. Publish task to topic
4. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Code Example**
```python
# Minimal reproducible example
from omnidaemon import OmniDaemonSDK

sdk = OmniDaemonSDK()
# Code that triggers the bug...

Paste full error traceback here

---

## 💡 Feature Requests

### Feature Request Template

```markdown
**Problem**
Describe the problem you're trying to solve.

**Proposed Solution**
Your suggested implementation.

**Alternatives**
Other solutions you've considered.

**Use Case**
How this feature would be used.

**Example**
```python
# How the API might look
await sdk.new_feature(...)

---

## 📚 Documentation Contributions

### Documentation Standards

- **Clear and concise** writing
- **Code examples** for all features
- **Real-world use cases**
- **Beginner-friendly** language
- **Enterprise perspective** where applicable

### Building Docs Locally

```bash
# Install MkDocs
uv add mkdocs-material

# Serve docs locally
mkdocs serve

# Open browser to http://127.0.0.1:8000

docs/
├── index.md                    # Home page
├── getting-started/
│   ├── introduction.md
│   └── quick-start.md
├── core-concepts/              # Architecture deep dives
├── examples/                   # Complete working examples
├── how-to-guides/              # Task-oriented guides
├── api-reference/              # API documentation
├── architecture/               # System architecture
├── enterprise/                 # Enterprise features
└── community/                  # This section

# Format: <type>(<scope>): <description>

feat(event-bus): add Kafka backend support
fix(sdk): handle Redis connection timeouts gracefully
docs(examples): add multi-agent pipeline example
test(storage): add tests for JSON store
refactor(runner): simplify message acknowledgment logic

**Description**
Brief description of changes.

**Related Issue**
Fixes #123

**Changes**
- Added Kafka event bus backend
- Updated documentation
- Added integration tests

**Testing**
- [ ] All existing tests pass
- [ ] Added new tests
- [ ] Manually tested

**Screenshots** (if applicable)
...

**Checklist**
- [ ] Code follows style guidelines
- [ ] Tests pass
- [ ] Documentation updated
- [ ] Backward compatible (or migration guide provided)

# Enable debug logging
export OMNIDAEMON_LOG_LEVEL=DEBUG

# Run with Python debugger
python -m pdb agent_runner.py

# Use ipdb for interactive debugging
pip install ipdb
# Add to code: import ipdb; ipdb.set_trace()

# Profile your agent
python -m cProfile -o profile.stats agent_runner.py

# Analyze with snakeviz
pip install snakeviz
snakeviz profile.stats

# Install memory profiler
pip install memory-profiler

# Profile specific function
python -m memory_profiler agent_runner.py