knowledge2 0.4.0__py3-none-any.whl

sdk/types/onboarding.py

@@ -0,0 +1,395 @@
+"""SDK types for dataset onboarding."""
+
+from __future__ import annotations
+
+try:  # Python 3.11+
+    from typing import NotRequired, TypedDict
+except ImportError:  # pragma: no cover - Python < 3.11
+    from typing_extensions import NotRequired, TypedDict
+
+# =============================================================================
+# Gold Labels
+# =============================================================================
+
+
+class GoldLabelDocumentReference(TypedDict, total=False):
+    """Reference to a document for gold label resolution."""
+
+    type: str  # "filename" | "document_id" | "text_match"
+    value: str
+
+
+class GoldLabelChunkReference(TypedDict, total=False):
+    """Reference to a chunk within a document."""
+
+    type: str  # "line_range" | "text_excerpt" | "chunk_index" | "offset_range"
+    value: str | int | dict
+
+
+class GoldLabelEntry(TypedDict, total=False):
+    """A single gold label entry (query-chunk pair)."""
+
+    query: str
+    document_reference: NotRequired[GoldLabelDocumentReference]
+    chunk_reference: NotRequired[GoldLabelChunkReference]
+    relevant_text: NotRequired[str]
+    metadata: NotRequired[dict]
+
+
+class GoldLabelsUploadRequest(TypedDict, total=False):
+    """Request to upload gold labels for a corpus."""
+
+    labels: list[GoldLabelEntry]
+    description: NotRequired[str]
+
+
+class ResolvedLabelInfo(TypedDict):
+    """Information about a resolved gold label."""
+
+    label_id: str
+    query: str
+    chunk_id: str | None
+    document_id: str | None
+    confidence: float
+    resolution_method: str
+
+
+class GoldLabelsUploadResponse(TypedDict):
+    """Response after uploading gold labels."""
+
+    corpus_id: str
+    total_uploaded: int
+    resolved_count: int
+    unmatched_count: int
+    labels: list[ResolvedLabelInfo]
+
+
+class GoldLabelListItem(TypedDict):
+    """Gold label item for listing."""
+
+    id: str
+    query: str
+    chunk_id: str | None
+    document_id: str | None
+    source: str | None
+    confidence: float | None
+    created_at: str
+
+
+class GoldLabelsListResponse(TypedDict):
+    """Response listing gold labels for a corpus."""
+
+    corpus_id: str
+    total: int
+    labels: list[GoldLabelListItem]
+
+
+# =============================================================================
+# Dataset Analysis
+# =============================================================================
+
+
+class DatasetAnalysisRequest(TypedDict, total=False):
+    """Request to start dataset analysis pipeline."""
+
+    description: NotRequired[str]
+    auto_bootstrap: NotRequired[bool]
+    bootstrap_num_samples: NotRequired[int]
+    queries_per_chunk: NotRequired[int]
+
+
+class DatasetAnalysisResponse(TypedDict):
+    """Response after starting dataset analysis."""
+
+    analysis_id: str
+    corpus_id: str
+    status: str
+    job_id: str | None
+    estimated_duration_seconds: int | None
+    created_at: str
+
+
+class DatasetAnalysisSummary(TypedDict):
+    """Summary of a dataset analysis run."""
+
+    analysis_id: str
+    status: str
+    current_stage: str | None
+    stages_completed: list[str]
+    has_prompt: bool
+    has_evaluation: bool
+    bootstrap_enabled: bool
+    bootstrap_labels_count: int | None
+    documents_at_analysis: int | None
+    started_at: str
+    created_at: str
+    completed_at: str | None
+    error_message: str | None
+    domain: str | None
+    lexical_strategy: str | None
+    quality_score: float | None
+
+
+class OnboardingStatusResponse(TypedDict):
+    """Response showing onboarding status for a corpus."""
+
+    corpus_id: str
+    latest_analysis: DatasetAnalysisSummary | None
+    gold_labels_count: int
+    synthetic_batches_count: int
+    has_summaries: bool
+    analysis_stale: bool
+
+
+class SearcherPersona(TypedDict):
+    """Searcher persona from Stage 1 analysis."""
+
+    who: str
+    goal: str
+    knowledge_state: str
+
+
+class LexicalStrategy(TypedDict):
+    """Lexical strategy recommendation."""
+
+    recommendation: str
+    rationale: str
+    techniques: list[str]
+
+
+class DatasetAnalysisDetails(TypedDict):
+    """Detailed results of a dataset analysis run."""
+
+    analysis_id: str
+    corpus_id: str
+    status: str
+    created_at: str
+    completed_at: str | None
+    config: dict
+    schema_analysis: dict | None
+    domain: str | None
+    expertise_level: str | None
+    data_relationship: str | None
+    searcher_persona: SearcherPersona | None
+    lexical_strategy: LexicalStrategy | None
+    stage1_analysis: dict | None
+    artifact_uri: str | None
+    prompt_uri: str | None
+    bootstrap_enabled: bool
+    bootstrap_labels_count: int | None
+    error_message: str | None
+
+
+# =============================================================================
+# Synthetic Query Generation
+# =============================================================================
+
+
+class SyntheticQueryGenerationRequest(TypedDict, total=False):
+    """Request to generate synthetic queries."""
+
+    analysis_id: str
+    sample_size: NotRequired[int]
+    queries_per_chunk: NotRequired[int]
+    use_document_context: NotRequired[bool]
+    eval_sample_size: NotRequired[int]
+
+
+class SyntheticQueryBatchResponse(TypedDict):
+    """Response after starting synthetic query generation."""
+
+    batch_id: str
+    corpus_id: str
+    analysis_id: str
+    status: str
+    job_id: str | None
+    sample_size: int | None
+    queries_per_chunk: int
+    estimated_queries: int | None
+    created_at: str
+
+
+class SyntheticQueryBatchSummary(TypedDict):
+    """Summary of a synthetic query batch."""
+
+    batch_id: str
+    status: str
+    sample_size: int | None
+    queries_per_chunk: int
+    total_chunks_processed: int | None
+    total_queries_generated: int | None
+    created_at: str
+    completed_at: str | None
+
+
+class SyntheticQueryBatchListResponse(TypedDict):
+    """Response listing synthetic query batches."""
+
+    corpus_id: str
+    batches: list[SyntheticQueryBatchSummary]
+
+
+class SyntheticQuerySample(TypedDict):
+    """Sample synthetic query for preview."""
+
+    chunk_id: str
+    chunk_text_preview: str
+    queries: list[str]
+
+
+class SyntheticQueryBatchDetails(TypedDict):
+    """Detailed information about a synthetic query batch."""
+
+    batch_id: str
+    corpus_id: str
+    analysis_id: str
+    status: str
+    created_at: str
+    completed_at: str | None
+    sample_size: int | None
+    queries_per_chunk: int
+    use_document_context: bool
+    config: dict
+    total_chunks_processed: int | None
+    total_queries_generated: int | None
+    stats: dict
+    artifact_uri: str | None
+    sample_queries: list[SyntheticQuerySample]
+    error_message: str | None
+
+
+# =============================================================================
+# Evaluation
+# =============================================================================
+
+
+class EvaluationRequest(TypedDict, total=False):
+    """Request to evaluate synthetic queries."""
+
+    batch_id: str
+    sample_size: NotRequired[int]
+    generate_report: NotRequired[bool]
+    report_formats: NotRequired[list[str]]
+
+
+class EvaluationResponse(TypedDict):
+    """Response after starting evaluation."""
+
+    eval_id: str
+    corpus_id: str
+    batch_id: str
+    status: str
+    job_id: str | None
+    created_at: str
+
+
+class EvaluationMetrics(TypedDict, total=False):
+    """Aggregated evaluation metrics.
+
+    Scale contract:
+    - avg_relevance / avg_groundedness / avg_style: 0-10
+    - avg_lexical_diversity / pass_rate: 0-1
+    """
+
+    total_evaluated: int
+    avg_relevance: NotRequired[float]
+    avg_groundedness: NotRequired[float]
+    avg_style: NotRequired[float]
+    avg_lexical_diversity: NotRequired[float]
+    pass_rate: NotRequired[float]
+    score_distribution: NotRequired[dict]
+
+
+class EvaluationSummary(TypedDict):
+    """Summary of an evaluation run."""
+
+    eval_id: str
+    batch_id: str
+    status: str
+    sample_size: int | None
+    metrics: EvaluationMetrics | None
+    created_at: str
+    completed_at: str | None
+
+
+class EvaluationListResponse(TypedDict):
+    """Response listing evaluations for a corpus."""
+
+    corpus_id: str
+    evaluations: list[EvaluationSummary]
+
+
+class EvaluationDetails(TypedDict):
+    """Detailed evaluation results."""
+
+    eval_id: str
+    corpus_id: str
+    batch_id: str
+    status: str
+    created_at: str
+    completed_at: str | None
+    sample_size: int | None
+    config: dict
+    metrics: EvaluationMetrics | None
+    artifact_uri: str | None
+    report_uri: str | None
+    sample_results: list[dict]
+    error_message: str | None
+
+
+class EvaluationReportResponse(TypedDict):
+    """Response with evaluation report."""
+
+    eval_id: str
+    corpus_id: str
+    format: str
+    report_uri: str | None
+    metrics: EvaluationMetrics | None
+    recommendations: list[str]
+
+
+# =============================================================================
+# Document Summarization
+# =============================================================================
+
+
+class SummarizationRequest(TypedDict, total=False):
+    """Request to generate document summaries."""
+
+    force_regenerate: NotRequired[bool]
+
+
+class SummarizationResponse(TypedDict):
+    """Response after starting summarization."""
+
+    corpus_id: str
+    job_id: str | None
+    status: str
+    total_documents: int
+    documents_with_summaries: int
+    documents_to_summarize: int
+    created_at: str
+
+
+class SummarizationStatusResponse(TypedDict):
+    """Response showing summarization status for a corpus."""
+
+    corpus_id: str
+    total_documents: int
+    documents_with_summaries: int
+    coverage_percent: float
+    latest_job_status: str | None
+    latest_job_completed_at: str | None
+
+
+class DocumentSummaryResponse(TypedDict):
+    """Response with a document's summary."""
+
+    document_id: str
+    corpus_id: str
+    summary: str
+    document_type: str | None
+    entities: dict
+    key_facts: list[str]
+    generation_model: str | None
+    created_at: str

sdk/types/orgs.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class OrgResponse(TypedDict, total=False):
+    id: str
+    name: str
+    contact_email: str | None

sdk/types/pipelines.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class ValidationIssue(TypedDict, total=False):
+    """A single validation warning or error from dry-run or apply."""
+
+    severity: str
+    code: str
+    message: str
+    path: str | None
+
+
+class PipelineSpecResponse(TypedDict, total=False):
+    """A single pipeline spec record."""
+
+    id: str
+    org_id: str
+    project_id: str
+    name: str
+    description: str | None
+    topology: dict[str, Any]
+    status: str
+    has_draft: bool
+    parent_pipeline_spec_id: str | None
+    created_by: str | None
+    bound_entity_count: int
+    binding_summary: dict[str, Any]
+    created_at: str
+    updated_at: str
+
+
+class PipelineSpecListResponse(TypedDict):
+    """Paginated list of pipeline specs."""
+
+    pipeline_specs: list[PipelineSpecResponse]
+    total: int
+    limit: int
+    offset: int
+
+
+class DryRunResult(TypedDict, total=False):
+    """Result of a pipeline spec dry run (validation preview)."""
+
+    valid: bool
+    issues: list[ValidationIssue]
+    would_create_agents: int
+    would_create_feeds: int
+    would_create_corpora: int
+    would_bind_existing: int
+
+
+class ApplyResult(TypedDict, total=False):
+    """Result of applying a pipeline spec."""
+
+    success: bool
+    created_agent_ids: list[str]
+    created_feed_ids: list[str]
+    created_corpus_ids: list[str]
+    created_subscription_ids: list[str]
+    bound_entity_ids: list[str]
+    issues: list[ValidationIssue]
+
+
+class SkippedEntity(TypedDict, total=False):
+    """Entity skipped during cascade archive."""
+
+    entity_type: str
+    entity_id: str
+    entity_name: str
+    reason: str
+    other_pipeline_ids: list[str]
+
+
+class ArchiveResult(TypedDict, total=False):
+    """Result of archiving a pipeline spec with cascade."""
+
+    pipeline_spec: PipelineSpecResponse
+    archived_agents: list[str]
+    archived_feeds: list[str]
+    deactivated_subscriptions: list[str]
+    skipped_entities: list[SkippedEntity]
+
+
+class DraftActivateResult(TypedDict, total=False):
+    """Result of activating a pipeline spec draft (incremental apply)."""
+
+    success: bool
+    created_agent_ids: list[str]
+    created_feed_ids: list[str]
+    created_corpus_ids: list[str]
+    created_subscription_ids: list[str]
+    removed_binding_ids: list[str]
+    updated_entity_ids: list[str]
+    issues: list[ValidationIssue]
+
+
+class FieldDiff(TypedDict, total=False):
+    """Single field-level difference between spec and actual entity state."""
+
+    field: str
+    spec_value: str | None
+    actual_value: str | None
+
+
+class EntityDiff(TypedDict, total=False):
+    """Drift status and field diffs for a single bound entity."""
+
+    entity_type: str
+    entity_id: str
+    entity_name: str
+    drift_status: str
+    field_diffs: list[FieldDiff]
+
+
+class DriftSummary(TypedDict, total=False):
+    """Summary counts for a drift report."""
+
+    total_entities: int
+    in_sync: int
+    drifted: int
+    missing: int
+    untracked: int
+
+
+class DriftReport(TypedDict, total=False):
+    """Full drift report comparing pipeline spec topology vs actual entity state."""
+
+    pipeline_spec_id: str
+    status: str
+    entity_diffs: list[EntityDiff]
+    summary: DriftSummary
+
+
+class RefreshChanges(TypedDict, total=False):
+    """Summary of changes made during a pipeline spec refresh."""
+
+    updated_entities: list[str]
+    removed_entities: list[str]
+    unchanged_entities: list[str]
+
+
+class RefreshResult(TypedDict, total=False):
+    """Result of refreshing a pipeline spec from current entity state."""
+
+    draft_id: str
+    changes: RefreshChanges
+
+
+class GraphNode(TypedDict, total=False):
+    """A single node in the pipeline graph representation."""
+
+    id: str
+    type: str
+    label: str
+    metadata: dict[str, Any]
+    status: str | None
+    binding_role: str | None
+
+
+class GraphEdge(TypedDict, total=False):
+    """A single edge in the pipeline graph representation."""
+
+    source: str
+    target: str
+    type: str
+    metadata: dict[str, Any]
+
+
+class GraphResponse(TypedDict, total=False):
+    """Full graph representation of a pipeline spec topology."""
+
+    pipeline_spec_id: str
+    status: str
+    nodes: list[GraphNode]
+    edges: list[GraphEdge]

sdk/types/projects.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class ProjectResponse(TypedDict):
+    id: str
+    name: str
+    org_id: str
+
+
+class ProjectListResponse(TypedDict):
+    projects: list[ProjectResponse]
+    total: int

sdk/types/search.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class SearchHybridConfig(TypedDict, total=False):
+    enabled: bool
+    fusion_mode: str
+    rrf_k: int
+    dense_weight: float
+    sparse_weight: float
+    metadata_sparse_enabled: bool
+
+
+class SearchRerankConfig(TypedDict, total=False):
+    enabled: bool
+    top_k: int
+
+
+class SearchReturnConfig(TypedDict, total=False):
+    include_text: bool
+    include_scores: bool
+    include_provenance: bool
+
+
+class MetadataFilter(TypedDict, total=False):
+    """A single metadata filter predicate."""
+
+    key: str
+    op: str  # ==, !=, >, >=, <, <=, in, not_in, contains, text_match
+    value: Any
+
+
+class MetadataFilters(TypedDict, total=False):
+    """Structured metadata filters with logical condition."""
+
+    filters: list[MetadataFilter]
+    condition: str  # "and" or "or"
+
+
+class SearchGenerationConfig(TypedDict, total=False):
+    model: str
+    thinking_budget: int | None
+    temperature: float
+    max_tokens: int
+    context_top_k: int
+
+
+class SearchOptions(TypedDict, total=False):
+    query: str
+    top_k: int
+    filters: dict[str, Any] | MetadataFilters
+    hybrid: SearchHybridConfig
+    rerank: SearchRerankConfig
+    return_config: SearchReturnConfig
+
+
+class SearchGenerateOptions(TypedDict, total=False):
+    query: str
+    top_k: int
+    filters: dict[str, Any] | MetadataFilters
+    hybrid: SearchHybridConfig
+    rerank: SearchRerankConfig
+    return_config: SearchReturnConfig
+    generation: SearchGenerationConfig
+
+
+class SearchBatchOptions(TypedDict, total=False):
+    queries: list[str]
+    top_k: int
+    filters: dict[str, Any] | MetadataFilters
+    hybrid: SearchHybridConfig
+    rerank: SearchRerankConfig
+    return_config: SearchReturnConfig
+
+
+class SearchResult(TypedDict, total=False):
+    chunk_id: str
+    score: float | None
+    raw_score: float | None
+    text: str | None
+    custom_metadata: dict | None
+    system_metadata: dict | None
+    offset_start: int | None
+    offset_end: int | None
+    page_start: int | None
+    page_end: int | None
+
+
+class SearchColdStartMeta(TypedDict, total=False):
+    likely: bool
+    dense_cache_hit: bool | None
+    sparse_cache_hit: bool | None
+
+
+class SearchMeta(TypedDict, total=False):
+    cold_start: SearchColdStartMeta | None
+    warnings: list[str] | None
+
+
+class SearchResponse(TypedDict, total=False):
+    results: list[SearchResult]
+    meta: SearchMeta
+
+
+class SearchBatchResponse(TypedDict, total=False):
+    responses: list[SearchResponse]
+
+
+class SearchGenerateResponse(TypedDict, total=False):
+    answer: str
+    model: str
+    thinking_budget: int | None
+    results: list[SearchResult]
+    meta: SearchMeta
+    used_sources: list[str]