analyxa 0.1.0__py3-none-any.whl

analyxa/__init__.py

@@ -0,0 +1,8 @@
+"""Analyxa — Multi-dimensional extraction engine for AI conversations."""
+
+__version__ = "0.1.0"
+
+from analyxa.analyzer import Analyzer, AnalysisResult, analyze
+from analyxa.schema import SchemaManager
+
+__all__ = ["Analyzer", "AnalysisResult", "analyze", "SchemaManager", "__version__"]

analyxa/analyzer.py

@@ -0,0 +1,183 @@
+"""Analyzer — main pipeline orchestrator for Analyxa."""
+
+import hashlib
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from analyxa.schema import SchemaManager
+from analyxa.prompt_builder import build_prompt
+from analyxa.llm_client import LLMClient, LLMResponse
+from analyxa.embeddings import EmbeddingGenerator
+
+
+@dataclass
+class AnalysisResult:
+    """Full result of a conversation analysis run."""
+
+    # Fields extracted by the LLM
+    fields: dict
+
+    # Schema metadata
+    schema_name: str
+    schema_version: str
+
+    # Auto-computed metadata
+    analyzed_at: str           # ISO 8601 UTC timestamp
+    analysis_model: str        # LLM model used
+    embedding_model: str | None
+    session_length: int        # Approximate line count
+    conversation_hash: str     # SHA-256 truncated to 16 hex chars
+
+    # Semantic vector
+    embedding: list[float] | None
+
+    # Execution metadata
+    llm_response: LLMResponse
+    validation_errors: list[str]
+
+    def to_dict(self) -> dict:
+        """Full dict with fields + nested _meta (for Qdrant/storage)."""
+        result = {}
+        result.update(self.fields)
+        result["_meta"] = {
+            "schema_name": self.schema_name,
+            "schema_version": self.schema_version,
+            "analyzed_at": self.analyzed_at,
+            "analysis_model": self.analysis_model,
+            "embedding_model": self.embedding_model,
+            "session_length": self.session_length,
+            "conversation_hash": self.conversation_hash,
+            "has_embedding": self.embedding is not None,
+            "input_tokens": self.llm_response.input_tokens,
+            "output_tokens": self.llm_response.output_tokens,
+            "latency_ms": self.llm_response.latency_ms,
+            "validation_errors": self.validation_errors,
+        }
+        return result
+
+    def to_flat_dict(self) -> dict:
+        """Flat dict with fields + meta at same level, no embedding (for JSON/CSV export)."""
+        result = {}
+        result.update(self.fields)
+        result["schema_name"] = self.schema_name
+        result["schema_version"] = self.schema_version
+        result["analyzed_at"] = self.analyzed_at
+        result["analysis_model"] = self.analysis_model
+        result["session_length"] = self.session_length
+        result["conversation_hash"] = self.conversation_hash
+        return result
+
+
+class Analyzer:
+    """Orchestrates the full analysis pipeline.
+
+    Pipeline:
+        conversation → build_prompt → LLMClient → validate → embed → AnalysisResult
+    """
+
+    def __init__(
+        self,
+        schema_name: str = "universal",
+        provider: str = "anthropic",
+        model: str | None = None,
+        api_key: str | None = None,
+        enable_embeddings: bool = True,
+        embedding_api_key: str | None = None,
+    ) -> None:
+        self.schema_name = schema_name
+        self.schema_manager = SchemaManager()
+        self.schema = self.schema_manager.load_schema(schema_name)
+        self.llm_client = LLMClient(provider=provider, model=model, api_key=api_key)
+
+        if enable_embeddings:
+            self.embedding_generator: EmbeddingGenerator | None = EmbeddingGenerator(
+                api_key=embedding_api_key
+            )
+        else:
+            self.embedding_generator = None
+
+    def analyze(
+        self, conversation: str, context: dict | None = None
+    ) -> AnalysisResult:
+        """Run the full pipeline on a conversation string."""
+        # Step 1 — build prompt
+        prompt = build_prompt(self.schema, conversation, context)
+
+        # Step 2 — call LLM
+        llm_response = self.llm_client.analyze(prompt)
+
+        # Compute auto-fields (used regardless of LLM success)
+        analyzed_at = datetime.now(timezone.utc).isoformat()
+        session_length = conversation.count("\n") + 1
+        conversation_hash = hashlib.sha256(conversation.encode()).hexdigest()[:16]
+
+        # Step 3 — handle LLM failure
+        if not llm_response.success or llm_response.parsed_json is None:
+            return AnalysisResult(
+                fields={},
+                schema_name=self.schema_name,
+                schema_version=self.schema["metadata"]["version"],
+                analyzed_at=analyzed_at,
+                analysis_model=self.llm_client.model,
+                embedding_model=None,
+                session_length=session_length,
+                conversation_hash=conversation_hash,
+                embedding=None,
+                llm_response=llm_response,
+                validation_errors=[
+                    f"LLM failed: {llm_response.error or 'Could not parse JSON'}"
+                ],
+            )
+
+        # Step 4 — validate against schema
+        _is_valid, errors = self.schema_manager.validate_result(
+            self.schema_name, llm_response.parsed_json
+        )
+
+        # Step 5 — generate embedding from summary field
+        embedding = None
+        embedding_model = None
+        if self.embedding_generator:
+            summary = llm_response.parsed_json.get("summary", "")
+            if summary:
+                embedding = self.embedding_generator.generate(summary)
+                if embedding is not None:
+                    embedding_model = "text-embedding-3-small"
+
+        # Step 6 — build and return result
+        return AnalysisResult(
+            fields=llm_response.parsed_json,
+            schema_name=self.schema_name,
+            schema_version=self.schema["metadata"]["version"],
+            analyzed_at=analyzed_at,
+            analysis_model=self.llm_client.model,
+            embedding_model=embedding_model,
+            session_length=session_length,
+            conversation_hash=conversation_hash,
+            embedding=embedding,
+            llm_response=llm_response,
+            validation_errors=errors,
+        )
+
+
+def analyze(
+    conversation: str,
+    schema: str = "universal",
+    provider: str = "anthropic",
+    model: str | None = None,
+    context: dict | None = None,
+    enable_embeddings: bool = True,
+) -> AnalysisResult:
+    """Convenience function for quick one-shot analysis.
+
+    Usage:
+        from analyxa import analyze
+        result = analyze("User: hello\\nAgent: hi", schema="support")
+    """
+    analyzer = Analyzer(
+        schema_name=schema,
+        provider=provider,
+        model=model,
+        enable_embeddings=enable_embeddings,
+    )
+    return analyzer.analyze(conversation, context=context)

analyxa/batch.py

@@ -0,0 +1,185 @@
+"""Batch processor — analyzes multiple conversations in sequence."""
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class BatchResult:
+    """Result of a batch analysis run."""
+
+    total: int
+    successful: int
+    failed: int
+    results: list  # list[AnalysisResult]
+    errors: list[dict]  # [{"id": str, "error": str}]
+    elapsed_seconds: float
+
+    @property
+    def success_rate(self) -> float:
+        return self.successful / self.total if self.total > 0 else 0.0
+
+
+def batch_analyze(
+    conversations: list[dict],
+    schema_name: str = "universal",
+    provider: str = "anthropic",
+    model: str | None = None,
+    enable_embeddings: bool = True,
+    sink: Any | None = None,
+    on_progress: Callable | None = None,
+) -> BatchResult:
+    """Analyze a list of conversations in sequence.
+
+    Args:
+        conversations: List of dicts with at least {"text": str}.
+                       Optional: {"text": str, "id": str, "context": dict}
+        schema_name: Schema to use for all analyses.
+        provider: LLM provider.
+        model: LLM model override.
+        enable_embeddings: Whether to generate embeddings.
+        sink: If provided, write each result immediately after analysis.
+              Supports QdrantSink.store() or JsonSink.write() / StdoutSink.write().
+        on_progress: Callback (current: int, total: int, result | None) -> None
+    """
+    from analyxa.analyzer import Analyzer
+
+    start = time.monotonic()
+    total = len(conversations)
+    successful = 0
+    failed = 0
+    results = []
+    errors = []
+
+    # Create a single Analyzer — reuses schema cache across all analyses
+    analyzer = Analyzer(
+        schema_name=schema_name,
+        provider=provider,
+        model=model,
+        enable_embeddings=enable_embeddings,
+    )
+
+    for i, conv in enumerate(conversations, 1):
+        text = conv.get("text", "")
+        conv_id = conv.get("id", str(i))
+        context = conv.get("context")
+
+        try:
+            result = analyzer.analyze(text, context=context)
+            results.append(result)
+            successful += 1
+
+            if sink is not None:
+                try:
+                    if hasattr(sink, "store"):
+                        sink.store(result)
+                    elif hasattr(sink, "write"):
+                        sink.write(result.to_flat_dict())
+                except Exception:
+                    pass  # Sink errors don't abort the batch
+
+        except Exception as exc:
+            failed += 1
+            errors.append({"id": conv_id, "error": f"{type(exc).__name__}: {exc}"})
+            results.append(None)
+
+        if on_progress is not None:
+            on_progress(i, total, results[-1])
+
+    elapsed = time.monotonic() - start
+    return BatchResult(
+        total=total,
+        successful=successful,
+        failed=failed,
+        results=[r for r in results if r is not None],
+        errors=errors,
+        elapsed_seconds=elapsed,
+    )
+
+
+def batch_analyze_from_redis(
+    redis_source=None,
+    qdrant_sink=None,
+    max_items: int | None = None,
+    provider: str = "anthropic",
+    model: str | None = None,
+    enable_embeddings: bool = True,
+    on_progress: Callable | None = None,
+) -> BatchResult:
+    """Process pending conversations from Redis queue and store in Qdrant.
+
+    Args:
+        redis_source: RedisSource instance. Created with defaults if None.
+        qdrant_sink: QdrantSink instance. Created with defaults if None.
+        max_items: Max conversations to process. None = all pending.
+        provider: LLM provider.
+        model: LLM model override.
+        enable_embeddings: Whether to generate embeddings.
+        on_progress: Callback (current: int, total: int, result | None) -> None
+    """
+    from analyxa.sources.redis_source import RedisSource
+    from analyxa.sinks.qdrant_sink import QdrantSink
+    from analyxa.analyzer import Analyzer
+
+    if redis_source is None:
+        redis_source = RedisSource()
+    if qdrant_sink is None:
+        qdrant_sink = QdrantSink()
+
+    # Gather pending conversations
+    pending_ids = redis_source.pending()
+    if max_items is not None:
+        pending_ids = pending_ids[:max_items]
+
+    total = len(pending_ids)
+    start = time.monotonic()
+    successful = 0
+    failed = 0
+    results = []
+    errors = []
+
+    for i, conv_id in enumerate(pending_ids, 1):
+        conv_data = redis_source.get(conv_id)
+        if conv_data is None:
+            failed += 1
+            errors.append({"id": conv_id, "error": "Conversation not found in Redis"})
+            if on_progress is not None:
+                on_progress(i, total, None)
+            continue
+
+        text = conv_data.get("text", "")
+        schema = conv_data.get("schema", "universal")
+        context = conv_data.get("context")
+
+        try:
+            analyzer = Analyzer(
+                schema_name=schema,
+                provider=provider,
+                model=model,
+                enable_embeddings=enable_embeddings,
+            )
+            result = analyzer.analyze(text, context=context)
+            redis_source.mark_analyzed(conv_id)
+            qdrant_sink.store(result)
+            results.append(result)
+            successful += 1
+
+        except Exception as exc:
+            error_msg = f"{type(exc).__name__}: {exc}"
+            redis_source.mark_failed(conv_id, error_msg)
+            failed += 1
+            errors.append({"id": conv_id, "error": error_msg})
+
+        if on_progress is not None:
+            on_progress(i, total, results[-1] if results else None)
+
+    elapsed = time.monotonic() - start
+    return BatchResult(
+        total=total,
+        successful=successful,
+        failed=failed,
+        results=results,
+        errors=errors,
+        elapsed_seconds=elapsed,
+    )