# mosaicstack-telemetry (Python Client SDK)

Python client SDK for Mosaic Stack Telemetry. Reports AI coding task-completion telemetry and queries crowd-sourced predictions.

## Development

```bash
# Install dependencies (including dev)
uv sync --all-extras

# Run tests (85%+ coverage required)
uv run pytest

# Lint
uv run ruff check src/ tests/

# Format check
uv run ruff format --check src/ tests/

# Type check
uv run mypy src/
```

## Architecture

- `src/mosaicstack_telemetry/client.py` — Main TelemetryClient (public API)
- `src/mosaicstack_telemetry/config.py` — TelemetryConfig dataclass with env var support
- `src/mosaicstack_telemetry/queue.py` — Thread-safe bounded event queue
- `src/mosaicstack_telemetry/submitter.py` — Batch submission with retry/backoff
- `src/mosaicstack_telemetry/_sync.py` — Threading-based periodic submitter
- `src/mosaicstack_telemetry/_async.py` — Asyncio-based periodic submitter
- `src/mosaicstack_telemetry/event_builder.py` — Fluent event builder
- `src/mosaicstack_telemetry/prediction_cache.py` — TTL-based prediction cache
- `src/mosaicstack_telemetry/types/` — All Pydantic models and enums

## Key Rules

- `track()` must NEVER throw or block the caller
- All logging uses `logging.getLogger("mosaicstack_telemetry")`
- Runtime deps: httpx + pydantic only
- Python 3.10+ compatible (uses `str, Enum` mixin instead of StrEnum)

## Conditional Documentation Loading

**Read the relevant guide before starting work:**

| Task Type | Guide |
|-----------|-------|
| Bootstrapping a new project | `~/.claude/agent-guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.claude/agent-guides/orchestrator.md` |
| Ralph autonomous development | `~/.claude/agent-guides/ralph-autonomous.md` |
| Frontend development | `~/.claude/agent-guides/frontend.md` |
| Backend/API development | `~/.claude/agent-guides/backend.md` |
| TypeScript strict typing | `~/.claude/agent-guides/typescript.md` |
| Code review | `~/.claude/agent-guides/code-review.md` |
| Authentication/Authorization | `~/.claude/agent-guides/authentication.md` |
| Infrastructure/DevOps | `~/.claude/agent-guides/infrastructure.md` |
| QA/Testing | `~/.claude/agent-guides/qa-testing.md` |
| Secrets management (Vault) | `~/.claude/agent-guides/vault-secrets.md` |


## Commits

```
<type>(#issue): Brief description

Detailed explanation if needed.

Fixes #123
```

Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`


## Secrets Management

**NEVER hardcode secrets.** Use `.env` files (gitignored) or a secrets manager.

```bash
# .env.example is committed (with placeholders)
# .env is NOT committed (contains real values)
```

Ensure `.gitignore` includes `.env*` (except `.env.example`).


## Multi-Agent Coordination

When multiple agents work on this project:
1. `git pull --rebase` before editing
2. `git pull --rebase` before pushing
3. If conflicts, **alert the user** — don't auto-resolve data conflicts