Documentation: SDK Integration Guide & API Reference #1

New Issue

2026-02-14T05:22:36Z

jason.woltje commented

2026-02-14 05:22:36 +00:00

Context

The Mosaic Telemetry monorepo (API + Web) is now operational. The telemetry agent is documenting the API contract, endpoints, auth, and data schema on the server side.

This issue covers the Python client SDK documentation.

Scope

Integration Guide

Installation and setup (pip/uv install)
Configuration options (API URL, auth token, batch settings, retry behavior)
Quick start example — instrumenting a FastAPI service
Quick start example — instrumenting a generic Python app

SDK API Reference

All exported classes and methods
Configuration dataclass/model
Event types and payload schemas
Error handling behavior
Async vs sync usage patterns

Examples

Basic event tracking
Custom metadata/tags
Batch vs real-time mode
Context manager usage
Environment-specific configuration (dev vs prod)

Dependency

This documentation should be written against the API contract documented in mosaic/telemetry. Coordinate with the telemetry monorepo docs for the authoritative endpoint specs, auth requirements, and data schema.

Acceptance Criteria

README.md updated with clear quick start
Full API reference in docs/ or README
At least 2 integration examples (FastAPI + generic Python)
Documents async vs sync client usage
Documents which telemetry API version this SDK targets

## Context The Mosaic Telemetry monorepo (API + Web) is now operational. The telemetry agent is documenting the API contract, endpoints, auth, and data schema on the server side. This issue covers the Python client SDK documentation. ## Scope ### Integration Guide - Installation and setup (pip/uv install) - Configuration options (API URL, auth token, batch settings, retry behavior) - Quick start example — instrumenting a FastAPI service - Quick start example — instrumenting a generic Python app ### SDK API Reference - All exported classes and methods - Configuration dataclass/model - Event types and payload schemas - Error handling behavior - Async vs sync usage patterns ### Examples - Basic event tracking - Custom metadata/tags - Batch vs real-time mode - Context manager usage - Environment-specific configuration (dev vs prod) ## Dependency This documentation should be written against the API contract documented in mosaic/telemetry. Coordinate with the telemetry monorepo docs for the authoritative endpoint specs, auth requirements, and data schema. ## Acceptance Criteria - [ ] README.md updated with clear quick start - [ ] Full API reference in docs/ or README - [ ] At least 2 integration examples (FastAPI + generic Python) - [ ] Documents async vs sync client usage - [ ] Documents which telemetry API version this SDK targets

jason.woltje referenced this issue from a commit

2026-02-15 04:39:25 +00:00

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

jason.woltje referenced this issue from a commit

2026-02-15 04:43:44 +00:00

chore(#1): Add PyPI publish step and Gitea registry install instructions

jason.woltje referenced this issue from a commit

2026-02-15 04:44:53 +00:00

fix(#1): Use uv run for twine in publish pipeline step

jason.woltje referenced this issue from a commit

2026-02-15 04:46:58 +00:00

fix(#1): Fix publish step - check simple index for existing version