API Reference¶

Complete module reference for the Latent framework, organized by category.

Agent Protocol¶

The canonical import surface for the agent contract. New code should prefer latent.protocol over latent.events / latent.agents.invoke (both still re-export for back-compat).

Symbol	Description
`latent.protocol.AgentProtocol`	`@runtime_checkable` contract every agent satisfies (`stream()`, `invoke()`, optional `reset()`)
`latent.protocol.Message`	Conversation message (LiteLLM `ChatCompletionMessage` shape; `role`, `content`, `tool_calls`, `tool_call_id`)
`latent.protocol.AgentEvent`	Base class for all streamed agent events
`latent.protocol.Step`	Buffered per-iteration view returned inside `InvokeResult`
`latent.protocol.InvokeResult`	Result of `invoke()` — terminal `text` plus per-step `steps`
`latent.protocol.ToolCall` / `FunctionCall`	Tool-call wire shape (matches LiteLLM `ChatCompletionAssistantToolCall`)
`latent.protocol.StreamWrapper`	Type alias for the `stream_wrapper` callable of `invoke()`

Event subclasses (also re-exported from latent.events): TextDelta, ReasoningDelta, LLMCallStart, LLMCallEnd, ToolCall, ToolResult, RetrieverStart, RetrieverEnd, StepBoundary, Usage, Error, VerificationResult, GuidelineMatched, JourneyStepAdvanced, JourneyCompleted, PhaseStarted, PhaseCompleted, PhaseRouted.

Orchestration¶

Module	Description
`latent.prefect.decorators`	`@flow` and `@task` decorators with auto-config, caching, retries; `task.map(concurrency=...)`
`latent.prefect.config_loader`	YAML loading, `get_config()`, `get_catalog()`
`latent.prefect.checkpoint`	Checkpoint caching for intermediate results
`latent.prefect`	Package exports: context accessors `params`, `logger`, `get_flow_name()`

See Prefect Flows & Tasks for usage guide.

Agents¶

Module	Description
`latent.agents.BaseAgent`	Base class implementing the `AgentProtocol` (`stream`/`invoke`/guardrail discovery)
`latent.agents.ReActAgent`	General-purpose LLM agent with tool support (formerly `LiteLLMAgent`, deprecated alias)
`latent.agents.Judge`	Score data rows against a Pydantic output schema
`latent.agents.Classifier`	Semantic classification with accuracy/F1/precision/recall
`latent.agents.RAGAgent` / `RAGAgentConfig`	Config-driven agent with pluggable retrieval pipeline
`latent.agents.tool`	`@tool` decorator for standalone and method-based tools
`latent.agents.retriever`	`@retriever` decorator emitting `RetrieverStart`/`RetrieverEnd` events
`latent.agents.scores`	`ScoredModel`, `OrdinalScore`, `BinaryScore`, `ContinuousScore`, `build_scoring_prompt`, `get_score_metadata`, `get_all_score_metadata`
`latent.agents.respond_from_events`	Collapse an event stream into an `AgentResponse` (`END_CALL_TOOL_NAME`, `ToolCallRecord`)
`latent.agents.AgentResponse` / `StreamingAgent`	Buffered response value + streaming-agent protocol
`latent.agents.CallMetrics` / `collect_call_metrics`	Per-call token/tool metrics derived from an event list
`latent.agents.AgentEventSink` / `AgentSinkMiddleware`	Observability sink protocol + middleware that fans events to sinks
`latent.agent_registry` / `latent.agents.agent`	`@agent` decorator + `AgentRegistry`/`AgentEntry` for discovery

See Agents for usage guide.

Guided Agents¶

Symbol	Description
`latent.agents.guided.GuidedAgent`	Context-narrowing agent driven by guidelines, journeys, glossaries
`latent.agents.guided.Guideline` / `GuidelineMatch` / `CompositionMode`	Conditional `when/then` guidelines and match results
`latent.agents.guided.CannedResponse` / `Glossary`	Fixed responses and term glossary
`latent.agents.guided.Journey` / `JourneyState` / `Step`	Multi-step journey state machine
`latent.agents.guided.resolve_guidelines` / `build_system_prompt`	Match (`match_always`, `embedding_match_guidelines`, `batch_match_guidelines`) and assemble prompt
`latent.agents.guided.load_guidelines_config` / `infer_guideline_relationships`	Load guideline config; infer relationships

(Top-level aliases Guideline, Journey, Glossary, etc. are re-exported from latent.agents.)

Pre-built Judges¶

latent.agents.judges — ready-made Judge subclasses:

Symbol	Scores
`latent.agents.CompletenessJudge`	Response completeness
`latent.agents.ConcisenessJudge`	Conciseness
`latent.agents.ConsistencyJudge`	Internal consistency
`latent.agents.FaithfulnessJudge`	Faithfulness to context
`latent.agents.GuardrailsJudge`	Guardrail/policy adherence
`latent.agents.HallucinationJudge`	Hallucination detection
`latent.agents.InstructionFollowingJudge`	Instruction following
`latent.agents.RecoveryJudge`	Error recovery
`latent.agents.RelevanceJudge`	Relevance
`latent.agents.StyleJudge`	Style/tone

Pipeline Agents¶

Module	Description
`latent.agents.pipeline.PipelineAgent`	Phase-based agent with deterministic routing
`latent.agents.pipeline.decorators`	`@phase`, `@tool`, `@respond`, `@subagent`
`latent.agents.pipeline.types`	`PipelineState`, `Transition`, `Respond`

See Pipeline Agents for usage guide.

Simulators¶

Symbol	Description
`latent.simulators.ConversationSimulator`	Drives a multi-turn conversation between an agent and a simulated human
`latent.simulators.ConversationAgent`	Agent role wrapper used inside a simulation
`latent.simulators.HumanAgent`	LLM-backed simulated user (also re-exported as `latent.agents.HumanAgent`)
`latent.simulators.SimulationConfig` / `SimulationResult`	Simulation configuration and result objects

Context Engineering¶

Module	Description
`latent.context.tokens`	`estimate_tokens()` -- UTF-8 byte token estimation
`latent.context.budget`	`budget_breakdown()` -- per-component token allocation
`latent.context.compaction`	`mask_observations()`, `compact_history()`, `anchored_summarize()`
`latent.context.diffs`	`compact_diffs()` -- cap recent diffs, collapse older ones
`latent.context.decorators`	`@context_check` decorator for agent-level context checks
`latent.context.review`	`review_context()` -- offline context linter
`latent.context.models`	`ContextReport`, `Finding` -- report data models
`latent.context.events`	`ContextCheckViolation`, `ContextCheckEvent` -- event types

Context Scanners¶

Scanner	Type	Description
`latent.guardrails.scanners.context.TokenBudgetAuditor`	Static	Token utilization monitoring with severity thresholds
`latent.guardrails.scanners.context.MiddleContentDetector`	Static	Flags critical instructions in attention trough
`latent.guardrails.scanners.context.HistoryBloatDetector`	Static	Detects excessive history proportion
`latent.guardrails.scanners.context.KVCacheStabilityAuditor`	Static	Finds cache-breaking dynamic values in system prompt
`latent.guardrails.scanners.context.ToolDescriptionLinter`	Static	Validates tool definition quality
`latent.guardrails.scanners.context.SystemPromptStructureAuditor`	Static	Checks system prompt structure best practices
`latent.guardrails.scanners.context.ObservationMaskingScanner`	Compactor	Masks old tool outputs, keeps recent ones
`latent.guardrails.scanners.context.CompactionScanner`	Compactor	Triggers full context compaction at utilization threshold
`latent.guardrails.scanners.context.ToolOutputOffloadScanner`	Compactor	Offloads large tool outputs to scratch files
`latent.guardrails.scanners.context.SummaryInjectionScanner`	Compactor	Injects periodic conversation summaries
`latent.guardrails.scanners.context.PoisoningDetector`	Semantic	Detects hallucinated facts re-entering context
`latent.guardrails.scanners.context.DistractionScorer`	Semantic	Scores context elements for relevance
`latent.guardrails.scanners.context.ContradictionDetector`	Semantic	Finds contradictions between sources
`latent.guardrails.scanners.context.CompressionQualityAuditor`	Semantic	Evaluates compression quality via probe questions

See Context Engineering for usage guide.

Guardrails¶

Module	Description
`latent.guardrails.decorators`	`@guardrail` method decorator for auto-discovery
`latent.guardrails.middleware`	`GuardrailMiddleware` composable scanner pipeline
`latent.guardrails.scanners.builtin`	`LanguageScanner`, `InvisibleTextScanner`, `TokenLimitScanner`
`latent.guardrails.scanners.llm`	`LLMGuardrailScanner` for custom LLM-backed rules
`latent.guardrails.scanners.llmguard`	ML scanners via LLM Guard (`latent[guardrails-llmguard]`): `PromptInjectionScanner`, `ToxicityScanner`, `BanTopicsScanner`, `GibberishScanner`, `AnonymizeScanner`, `MaliciousURLsScanner`, `SensitiveScanner`
`latent.guardrails.config`	TOML-based guardrail configuration
`latent.guardrails.metrics`	Guardrail evaluation metrics
`latent.guardrails.events`	`GuardrailEvent` types emitted to sinks

Locales¶

Module	Description
`latent.guardrails.locales.hebrew`	`HebrewPromptInjectionScanner` + Hebrew pattern sets (`HEBREW_INSTRUCTION_INJECTION_PATTERNS`, `HEBREW_PROMPT_EXTRACTION_PATTERNS`, `HEBREW_DATA_EXTRACTION_PATTERNS`, `HEBREW_SOCIAL_ENGINEERING_PATTERNS`, `HEBREW_PROFANITY_PATTERNS`)

See Guardrails for usage guide.

Prompt Optimization¶

Module	Description
`latent.optimize.dspy`	`DSPyOptimizer` -- teleprompter-based prompt optimization
`latent.optimize.ace`	`ACEOptimizer` -- section-level prompt refinement
`latent.optimize.combined`	`CombinedOptimizer` -- DSPy then ACE pipeline
`latent.optimize.autoresearch`	`AutoResearchOptimizer` -- git-based codebase optimization
`latent.optimize.tracker`	`ExperimentTracker` for optimization history
`latent.optimize.analysis`	Trajectory analysis and optimizer comparison

See Prompt Optimization for usage guide.

RAG¶

Module	Description
`latent.rag.chroma`	`ChromaRetriever` -- vector store with automatic embedding
`latent.rag.hybrid`	`HybridRetriever` -- dense + BM25 with RRF fusion
`latent.rag.bm25`	`BM25Retriever` -- sparse keyword search
`latent.rag.adaptive`	Query rewriting, HyDE, reranking, CRAG, caching
`latent.rag.pipeline`	`PipelineBuilder` -- config-driven pipeline composition
`latent.rag.tune`	`rag_grid_search` -- hyperparameter sweep
`latent.rag.metrics`	Retrieval evaluation metrics (NDCG, MRR, recall)
`latent.rag.embeddings`	Embedding provider adapters
`latent.rag.raptor`	RAPTOR recursive abstractive retrieval

See RAG Pipelines and RAPTOR Integration for usage guides.

Pre-built Eval Flows¶

Scoring¶

Flow	Description
`latent.flows.judge_flow`	Score free-text outputs with LLM judge
`latent.flows.classification_flow`	Classify + compute accuracy/F1/precision/recall
`latent.flows.comparison_flow`	Compare model A vs B with statistical tests

Conversation¶

Flow	Description
`latent.flows.conversation_scoring_flow`	Turn-level scoring with aggregation
`latent.flows.conversation_sop_flow`	SOP compliance checking
`latent.flows.conversation_trajectory_flow`	Trajectory distance analysis

Agent Evaluation¶

Flow	Description
`latent.flows.agent_eval_flow`	End-to-end agent evaluation
`latent.flows.agent_inference_flow`	Batch agent inference with tool tracking
`latent.flows.agent_garden_flow`	Multi-agent comparison ("garden") evaluation
`latent.flows.conversation_simulation_flow`	Simulate conversations; `results_to_conversations` adapts results
`latent.flows.instrumented_judge_flow`	`judge_flow` variant with extra instrumentation

Analysis¶

Flow	Description
`latent.flows.drift_flow`	Distribution drift detection
`latent.flows.classify_failure_modes`	Failure mode clustering
`latent.flows.knowledge_coverage_flow`	Knowledge gap analysis
`latent.flows.retrieval_eval_flow`	RAG retrieval quality evaluation
`latent.flows.eval_report_flow`	Aggregate report generation

Specialized¶

Flow	Description
`latent.flows.ner_flow`	Named entity recognition evaluation
`latent.flows.text_to_sql_flow`	Text-to-SQL accuracy evaluation
`latent.flows.model_garden_flow`	Multi-model comparison
`latent.flows.autoresearch_agent_flow`	AutoResearch optimization experiment orchestration
`latent.flows.rag_optimization_flow`	RAG hyperparameter optimization
`latent.flows.rag_research_flow`	AutoResearch-driven RAG pipeline improvement
`latent.flows.validate_dataset`	Dataset schema validation

See Eval Flows for usage guide.

Statistical Analysis¶

Module	Description
`latent.stats.bootstrap`	Bootstrap confidence intervals
`latent.stats.intervals`	Wilson intervals, paired bootstrap
`latent.stats.comparison`	`compare_systems()`, McNemar's test, non-inferiority
`latent.stats.classification`	`classification_metrics()`, confusion matrices with CIs
`latent.stats.structured`	Field-level accuracy, composite accuracy, schema compliance
`latent.stats.ordinal`	Ordinal distributions, binarization
`latent.stats.drift`	`detect_drift()`, `drift_report()`, multi-run trends
`latent.stats.effect_size`	Cohen's d, odds ratio, risk ratio
`latent.stats.gating`	`threshold_gate()`, multiple comparison correction
`latent.stats.agreement`	Cohen's kappa, Fleiss' kappa, Krippendorff's alpha
`latent.stats.conversation`	Turn-level scoring, aggregation
`latent.stats.trajectory`	Edit distance, tool trajectory distance
`latent.stats.sop`	SOP compliance scoring
`latent.stats.bayesian`	Beta-binomial posterior
`latent.stats.calibration`	Score calibration
`latent.stats.ppi`	Prediction-powered inference
`latent.stats.markdown`	Markdown report rendering
`latent.stats.models`	`StatisticalReport`, `ComparisonResult`, `GatingResult`

See Statistical Analysis for usage guides.

Experiment Tracking¶

Module	Description
`latent.mlflow.mlflow`	Wrapped MLflow API (safe when tracking disabled)
`latent.mlflow.mlflow_setup`	Experiment creation and configuration
`latent.mlflow.evaluate`	MLflow evaluation integration
`latent.mlflow.wrapper`	Safe MLflow wrapper (no-ops when disabled)

See MLflow Tracking for usage guide.

Data¶

Type	Extension	Engine	Description
`pandas.CSV`	`.csv`	pandas	Comma-separated values
`pandas.Parquet`	`.parquet`	pandas	Apache Parquet format
`pandas.JSON`	`.jsonl`	pandas	JSON Lines (line-delimited)
`polars.CSV`	`.csv`	polars	CSV via Polars
`polars.Parquet`	`.parquet`	polars	Parquet via Polars
`json.JSON`	`.json`	stdlib	Plain JSON
`pickle.Pickle`	`.pkl`	cloudpickle	Pickle serialization
`text.Text`	`.txt`	stdlib	Plain text (file or directory)
`text.Markdown`	`.md`	stdlib	Markdown (file or directory)
`conversation.JSONL`	`.jsonl`	stdlib	JSONL with turn structure
`pandas.Excel` / `polars.Excel`	`.xlsx`	pandas/polars	Single Excel sheet (`sheet` kwarg)
`pandas.ExcelMultiSheet` / `polars.ExcelMultiSheet`	`.xlsx`	pandas/polars	All sheets → `dict[str, DataFrame]`
`pandas.GoogleSheet`	—	google-sheets	Live Google Sheet (public CSV-export or service account)
`agent_studio.Dataset`	`.jsonl`	httpx	Remote Agent Studio dataset (by `slug`/`version`)
`agent_studio.Report`	`.jsonl`	httpx	Output — submits a `StatisticalReport` to Agent Studio

Infrastructure & CLI¶

Module	Description
`latent.infra`	Docker-based service management (PostgreSQL, Prefect, MLflow)
`latent.cli`	CLI entry point (`latent run`, `latent list`, `latent chat`, etc.)
`latent.workspace`	Path resolution with env var overrides
`latent.config`	TOML configuration loading

See CLI Tools and Infrastructure for usage guides.

Events & Observability¶

Module	Description
`latent.events`	Agent event dataclasses (`AgentEvent` + subclasses, `Message`, `ToolCall`/`FunctionCall`) — re-exported by `latent.protocol`
`latent.observability`	Event sinks: `EventSink` protocol, `NoOpSink`, `StructlogSink`, `OpenTelemetrySink`, `WebhookSink`
`latent.pricing`	Token usage and cost tracking

Agent Studio¶

Symbol	Description
`latent.studio_client.StudioClient`	HTTP client for the remote Agent Studio platform (datasets, reports)
`latent.studio_client.DatasetSummary` / `ConversationSummary` / `ConversationListResponse`	Response models
`agent_studio.Dataset` / `agent_studio.Report` (in `latent.datasets`)	Catalog dataset types backed by Agent Studio (see Data)

Utilities¶

Module	Description
`latent.registry`	Task and flow registry for pipeline visualization
`latent.flow_registry`	Flow discovery and registration
`latent.agent_registry`	Agent discovery via `@agent` decorator
`latent.testing`	Testing utilities for unit tests
`latent.exceptions`	Custom exception types