Jason Woltje
883fd4d60f
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
- Rewrite README with quick start, FastAPI snippet, async/sync patterns, config reference with env vars, and API version targeting (v1, schema 1.0) - Add docs/integration-guide.md with full FastAPI and generic Python integration examples, environment-specific config, prediction queries, error handling, and dry-run mode documentation - Add docs/api-reference.md covering all exported classes, methods, Pydantic models, enums (TaskType, Complexity, Harness, Provider, QualityGate, Outcome, RepoSizeCategory), and internal components - Add Woodpecker CI pipeline (.woodpecker.yml) with quality gates: lint, format check, typecheck, bandit security scan, pip-audit, and pytest with 85% coverage gate - Add bandit and pip-audit to dev dependencies Fixes #1 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
94 lines
2.9 KiB
Markdown
94 lines
2.9 KiB
Markdown
# 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
|
|
|