feat: add voice streaming, credits_used field, and documentation

Author: safenestdev

README.md

@@ -187,6 +187,62 @@ print(f"Risk: {report.risk_level}")
 print(f"Next Steps: {report.recommended_next_steps}")
 ```
 
+### Voice Streaming
+
+Real-time voice streaming with live safety analysis over WebSocket. Requires `websockets`:
+
+```bash
+pip install tuteliq[voice]
+```
+
+```python
+from tuteliq import VoiceStreamConfig, VoiceStreamHandlers
+
+session = client.voice_stream(
+    config=VoiceStreamConfig(
+        interval_seconds=10,
+        analysis_types=["bullying", "unsafe"],
+    ),
+    handlers=VoiceStreamHandlers(
+        on_transcription=lambda e: print(f"Transcript: {e.text}"),
+        on_alert=lambda e: print(f"Alert: {e.category} ({e.severity})"),
+    ),
+)
+
+await session.connect()
+
+# Send audio chunks as they arrive
+await session.send_audio(audio_bytes)
+
+# End session and get summary
+summary = await session.end()
+print(f"Risk: {summary.overall_risk}")
+print(f"Score: {summary.overall_risk_score}")
+print(f"Full transcript: {summary.transcript}")
+```
+
+---
+
+## Credits Tracking
+
+Each response includes the number of credits consumed:
+
+```python
+result = await client.detect_bullying("Test message")
+print(f"Credits used: {result.credits_used}")  # 1
+```
+
+| Method | Credits | Notes |
+|--------|---------|-------|
+| `detect_bullying()` | 1 | Single text analysis |
+| `detect_unsafe()` | 1 | Single text analysis |
+| `detect_grooming()` | 1 per 10 msgs | `ceil(messages / 10)`, min 1 |
+| `analyze_emotions()` | 1 per 10 msgs | `ceil(messages / 10)`, min 1 |
+| `get_action_plan()` | 2 | Longer generation |
+| `generate_report()` | 3 | Structured output |
+| `analyze_voice()` | 5 | Transcription + analysis |
+| `analyze_image()` | 3 | Vision + OCR + analysis |
+
 ---
 
 ## Tracking Fields

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tuteliq"
-version = "1.2.0"
+version = "2.2.0"
 description = "Official Python SDK for Tuteliq - AI-powered child safety API"
 readme = "README.md"
 license = "MIT"
@@ -41,6 +41,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+voice = [
+    "websockets>=12.0",
+]
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",

tuteliq/__init__.py

@@ -81,6 +81,18 @@
     AuditLogEntry,
     AuditLogsResult,
 )
+from tuteliq.voice_stream import (
+    VoiceStreamConfig,
+    VoiceStreamHandlers,
+    VoiceStreamSession,
+    VoiceReadyEvent,
+    VoiceTranscriptionEvent,
+    VoiceTranscriptionSegment,
+    VoiceAlertEvent,
+    VoiceSessionSummaryEvent,
+    VoiceConfigUpdatedEvent,
+    VoiceErrorEvent,
+)
 from tuteliq.errors import (
     TuteliqError,
     AuthenticationError,
@@ -94,7 +106,7 @@
     TierAccessError,
 )
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 __all__ = [
     # Client
     "Tuteliq",
@@ -166,6 +178,17 @@
     "RectifyDataResult",
     "AuditLogEntry",
     "AuditLogsResult",
+    # Voice streaming types
+    "VoiceStreamConfig",
+    "VoiceStreamHandlers",
+    "VoiceStreamSession",
+    "VoiceReadyEvent",
+    "VoiceTranscriptionEvent",
+    "VoiceTranscriptionSegment",
+    "VoiceAlertEvent",
+    "VoiceSessionSummaryEvent",
+    "VoiceConfigUpdatedEvent",
+    "VoiceErrorEvent",
     # Errors
     "TuteliqError",
     "AuthenticationError",

tuteliq/client.py

@@ -824,6 +824,52 @@ async def analyze_image(
         data = await self._multipart_request("/api/v1/safety/image", fields, files)
         return ImageAnalysisResult.from_dict(data)
 
+    # =========================================================================
+    # Voice Streaming
+    # =========================================================================
+
+    def voice_stream(
+        self,
+        config: Optional["VoiceStreamConfig"] = None,
+        handlers: Optional["VoiceStreamHandlers"] = None,
+    ) -> "VoiceStreamSession":
+        """Create a voice streaming session over WebSocket.
+
+        Requires the ``websockets`` package::
+
+            pip install websockets
+
+        Args:
+            config: Optional session configuration (interval, analysis types).
+            handlers: Optional event handler callbacks.
+
+        Returns:
+            A VoiceStreamSession. Call ``await session.connect()`` to start.
+
+        Example::
+
+            session = client.voice_stream(
+                config=VoiceStreamConfig(
+                    interval_seconds=10,
+                    analysis_types=["bullying", "unsafe"],
+                ),
+                handlers=VoiceStreamHandlers(
+                    on_transcription=lambda e: print("Transcript:", e.text),
+                    on_alert=lambda e: print("Alert:", e.category, e.severity),
+                ),
+            )
+            await session.connect()
+            await session.send_audio(audio_bytes)
+            summary = await session.end()
+        """
+        from tuteliq.voice_stream import VoiceStreamSession
+
+        return VoiceStreamSession(
+            api_key=self._api_key,
+            config=config,
+            handlers=handlers,
+        )
+
     # =========================================================================
     # Webhooks
     # =========================================================================

tuteliq/models.py

@@ -123,6 +123,7 @@ class BullyingResult:
     rationale: str
     recommended_action: str
     risk_score: float
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
 
@@ -137,6 +138,7 @@ def from_dict(cls, data: dict[str, Any]) -> "BullyingResult":
             rationale=data["rationale"],
             recommended_action=data["recommended_action"],
             risk_score=data["risk_score"],
+            credits_used=data.get("credits_used"),
             external_id=data.get("external_id"),
             metadata=data.get("metadata"),
         )
@@ -177,6 +179,7 @@ class GroomingResult:
     rationale: str
     risk_score: float
     recommended_action: str
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
 
@@ -190,6 +193,7 @@ def from_dict(cls, data: dict[str, Any]) -> "GroomingResult":
             rationale=data["rationale"],
             risk_score=data["risk_score"],
             recommended_action=data["recommended_action"],
+            credits_used=data.get("credits_used"),
             external_id=data.get("external_id"),
             metadata=data.get("metadata"),
         )
@@ -221,6 +225,7 @@ class UnsafeResult:
     risk_score: float
     rationale: str
     recommended_action: str
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
 
@@ -235,6 +240,7 @@ def from_dict(cls, data: dict[str, Any]) -> "UnsafeResult":
             risk_score=data["risk_score"],
             rationale=data["rationale"],
             recommended_action=data["recommended_action"],
+            credits_used=data.get("credits_used"),
             external_id=data.get("external_id"),
             metadata=data.get("metadata"),
         )
@@ -266,6 +272,7 @@ class AnalyzeResult:
     bullying: Optional[BullyingResult] = None
     unsafe: Optional[UnsafeResult] = None
     recommended_action: str = "none"
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
 
@@ -304,6 +311,7 @@ class EmotionsResult:
     trend: EmotionTrend
     summary: str
     recommended_followup: str
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
 
@@ -316,6 +324,7 @@ def from_dict(cls, data: dict[str, Any]) -> "EmotionsResult":
             trend=EmotionTrend(data["trend"]),
             summary=data["summary"],
             recommended_followup=data["recommended_followup"],
+            credits_used=data.get("credits_used"),
             external_id=data.get("external_id"),
             metadata=data.get("metadata"),
         )
@@ -346,6 +355,7 @@ class ActionPlanResult:
     steps: list[str]
     tone: str
     reading_level: Optional[str] = None
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
 
@@ -357,6 +367,7 @@ def from_dict(cls, data: dict[str, Any]) -> "ActionPlanResult":
             steps=data["steps"],
             tone=data["tone"],
             reading_level=data.get("approx_reading_level"),
+            credits_used=data.get("credits_used"),
             external_id=data.get("external_id"),
             metadata=data.get("metadata"),
         )
@@ -397,6 +408,7 @@ class ReportResult:
     risk_level: RiskLevel
     categories: list[str]
     recommended_next_steps: list[str]
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
 
@@ -408,6 +420,7 @@ def from_dict(cls, data: dict[str, Any]) -> "ReportResult":
             risk_level=RiskLevel(data["risk_level"]),
             categories=data["categories"],
             recommended_next_steps=data["recommended_next_steps"],
+            credits_used=data.get("credits_used"),
             external_id=data.get("external_id"),
             metadata=data.get("metadata"),
         )
@@ -802,6 +815,7 @@ class VoiceAnalysisResult:
     analysis: Optional[dict[str, Any]] = None
     overall_risk_score: Optional[float] = None
     overall_severity: Optional[str] = None
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     customer_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
@@ -818,6 +832,7 @@ def from_dict(cls, data: dict[str, Any]) -> "VoiceAnalysisResult":
             analysis=data.get("analysis"),
             overall_risk_score=data.get("overall_risk_score"),
             overall_severity=data.get("overall_severity"),
+            credits_used=data.get("credits_used"),
             external_id=data.get("external_id"),
             customer_id=data.get("customer_id"),
             metadata=data.get("metadata"),
@@ -864,6 +879,7 @@ class ImageAnalysisResult:
     text_analysis: Optional[dict[str, Any]] = None
     overall_risk_score: Optional[float] = None
     overall_severity: Optional[str] = None
+    credits_used: Optional[int] = None
     external_id: Optional[str] = None
     customer_id: Optional[str] = None
     metadata: Optional[dict[str, Any]] = None
@@ -880,6 +896,7 @@ def from_dict(cls, data: dict[str, Any]) -> "ImageAnalysisResult":
             text_analysis=data.get("text_analysis"),
             overall_risk_score=data.get("overall_risk_score"),
             overall_severity=data.get("overall_severity"),
+            credits_used=data.get("credits_used"),
             external_id=data.get("external_id"),
             customer_id=data.get("customer_id"),
             metadata=data.get("metadata"),