Files

ci/woodpecker/push/woodpecker Pipeline was successful

Details

docs(#1 ): SDK integration guide, API reference, and CI pipeline

- 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>

2026-02-14 22:39:19 -06:00

2.9 KiB

Raw Permalink Blame History

mosaicstack-telemetry (Python Client SDK)

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

Development

# 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.

# .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:

git pull --rebase before editing
git pull --rebase before pushing
If conflicts, alert the user — don't auto-resolve data conflicts

2.9 KiB Raw Permalink Blame History