aid-runtime-python 0.1.39__py3-none-any.whl

aid_runtime/__init__.py

@@ -0,0 +1,500 @@
+"""AID runtime for Python: the execution half of a generated application.
+
+The AID framework generates an application from an IR that declares *what* the
+app does. This package is what the generated code calls at runtime: pin a model,
+run a prompt, call a tool, trace it, stay inside a budget, and prove that quality
+did not regress.
+
+Design boundaries worth stating up front, because they are deliberate:
+
+* **Control flow is plain async Python.** There is no graph or orchestration
+  engine here. A generated app is ordinary code that is easy to read and to test.
+* **Pydantic AI is used only for structured output.** No other responsibility is
+  delegated to it.
+* **Streaming is SSE, and served end to end.** A model and its adapter that
+  advertise ``Capability.STREAMING`` are served by
+  :meth:`~aid_runtime.gateway.ModelGateway.stream`, which yields Server-Sent Event
+  ``data`` frames with the first delta before completion. Anything not advertising
+  the capability raises :class:`~aid_runtime.errors.CapabilityMismatchError`
+  instead of pretending to stream.
+* **One HTTP provider adapter and one fake.** Breadth of vendor coverage is a
+  Phase 2 concern; a narrow, correct seam is worth more now than a wide shallow one.
+"""
+
+from __future__ import annotations
+
+from aid_runtime.agents import (
+    AgentCheckpoint,
+    AgentDefinition,
+    AgentRuntime,
+    FileMemoryStore,
+    HumanApproval,
+    HumanDecision,
+    InProcessMemoryStore,
+    MemoryDefinition,
+    MemoryStore,
+    PendingApproval,
+    Principal,
+    RunResult,
+    RunStatus,
+    RuntimeSpec,
+    StepKind,
+    StepRecord,
+    ThreadMemory,
+    ToolSpec,
+)
+from aid_runtime.cache import CompletionCache, cache_key_for
+from aid_runtime.concurrency import ConcurrencyLimiter
+from aid_runtime.control import (
+    DEPTH_KEY,
+    INDEX_KEY,
+    ITEM_KEY,
+    LIMITER_KEY,
+    MAX_STEP_DEPTH,
+    PRINCIPAL_KEY,
+    REDUCED_KEY,
+    RESERVED_KEYS,
+    branch,
+    map_step,
+    parallel,
+    reduce_step,
+)
+from aid_runtime.cost import (
+    Budget,
+    CostLedger,
+    LedgerEntry,
+    SpendSummary,
+    estimate_cost_usd,
+    estimate_prompt_cost_usd,
+)
+from aid_runtime.errors import (
+    AgentBudgetDegradedError,
+    AgentHandoffUnsupportedError,
+    AgentTransferCycleError,
+    AidRuntimeError,
+    BudgetExceededError,
+    CapabilityMismatchError,
+    ConfigurationError,
+    DeepAgentsEngineError,
+    DeepAgentsMaxStepsError,
+    DeepAgentsUnavailableError,
+    DeepAgentsVersionMismatchError,
+    EvalError,
+    FeatureDeferredError,
+    GateConfigurationError,
+    GuardrailBlockedError,
+    PipelineError,
+    PolicyEvaluationError,
+    PromptNotFoundError,
+    PromptRenderError,
+    ProviderError,
+    ProviderResponseError,
+    StructuredOutputError,
+    ToolArgumentError,
+    ToolExecutionError,
+    ToolNotFoundError,
+    ToolPermissionError,
+    UnknownModelAliasError,
+)
+from aid_runtime.evals import (
+    BaselineGate,
+    CaseOutcome,
+    Dataset,
+    DatasetRun,
+    EvalBaseline,
+    EvalCase,
+    EvalRun,
+    ExactMatch,
+    GateResult,
+    GatewayRunner,
+    JsonSchemaValid,
+    JudgeVerdict,
+    LlmJudge,
+    Metric,
+    MetricBaseline,
+    MetricGateResult,
+    MetricResult,
+    MetricRun,
+    NormalizedContains,
+    Runner,
+    Threshold,
+    default_metrics,
+    evaluate_once,
+    gate_from_config,
+    gateway_judge,
+    metric_names,
+    normalize,
+    run_evaluation,
+    z_critical,
+)
+from aid_runtime.gateway import ModelGateway, estimate_usage
+from aid_runtime.pipeline import (
+    STEPS_KEY,
+    Pipeline,
+    PipelineContext,
+    Step,
+    StepResult,
+    StopPipeline,
+)
+from aid_runtime.prompts import Example, PromptRegistry, PromptTemplate, RenderedPrompt
+from aid_runtime.providers import (
+    DEFAULT_BASE_URL,
+    FakeProvider,
+    OpenAICompatibleProvider,
+    Provider,
+    ScriptedTurn,
+)
+from aid_runtime.retrieval import (
+    DEFAULT_CANDIDATE_FACTOR,
+    Chunk,
+    Chunker,
+    ChunkingSpec,
+    ChunkingStrategy,
+    Citation,
+    CitationGrounding,
+    CodeChunker,
+    Connector,
+    DistanceMetric,
+    Embedder,
+    EmbeddingBatch,
+    EmbeddingCostProfile,
+    EmbeddingSpec,
+    FakeDeterministicEmbedder,
+    FileConnector,
+    FixedChunker,
+    IndexSpec,
+    IngestReport,
+    InMemoryVectorStore,
+    LexicalReranker,
+    MeanReciprocalRank,
+    OpenAICompatibleEmbedder,
+    PgVectorStore,
+    PinnedEmbedding,
+    RankedId,
+    RecallAtK,
+    RecursiveChunker,
+    RefreshMode,
+    RefreshSpec,
+    Reranker,
+    RerankSpec,
+    RetrievalCase,
+    RetrievalGate,
+    RetrievalMetric,
+    RetrievalMetricSpec,
+    RetrievalResult,
+    RetrievedItem,
+    Retriever,
+    RetrieverBinding,
+    RetrieverSpec,
+    ScoredChunk,
+    SearchHit,
+    SourceDocument,
+    SourceKind,
+    SourceSpec,
+    StoreKind,
+    StoreRecord,
+    VectorStore,
+    VectorStoreSpec,
+    assemble_context,
+    binding_from_spec,
+    bm25_scores,
+    chunk_document,
+    chunk_id_for,
+    chunker_for,
+    cite,
+    create_store,
+    embedder_for,
+    estimate_tokens,
+    fuse,
+    lexical_ranking,
+    lexical_score,
+    open_connector,
+    pinned_embedding,
+    reranker_for,
+    resolve_uri,
+    retrieval_metrics,
+    rrf_score,
+    similarity,
+    tokenize,
+)
+from aid_runtime.steps import (
+    EMITTED_KEY,
+    RetrieverSeam,
+    emit_step,
+    generate_step,
+    resolve_source,
+    retrieve_step,
+    tool_step,
+)
+from aid_runtime.structured import (
+    build_agent,
+    format_problems,
+    parse_structured,
+    repair_prompt,
+    run_structured,
+)
+from aid_runtime.tools import Tool, ToolExecutor
+from aid_runtime.tracing import (
+    ATTRIBUTES,
+    GEN_AI_OPERATION_CHAT,
+    agent_span,
+    aid_attributes,
+    get_tracer,
+    llm_span,
+    record_attributes,
+    record_cost,
+    record_exception,
+    record_hitl,
+    record_usage,
+)
+from aid_runtime.types import (
+    Capability,
+    CompletionRequest,
+    CompletionResponse,
+    CostProfile,
+    FinishReason,
+    GenerationResult,
+    Message,
+    ModelCacheConfig,
+    ModelSpec,
+    PinnedModel,
+    Role,
+    SemanticCacheConfig,
+    StreamChunk,
+    TokenUsage,
+    ToolCall,
+    ToolDefinition,
+    ToolResult,
+)
+
+#: Kept in sync with ``pyproject.toml`` by a test, so the two cannot drift.
+__version__ = "0.1.39"
+
+__all__ = [
+    "ATTRIBUTES",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_CANDIDATE_FACTOR",
+    "DEPTH_KEY",
+    "EMITTED_KEY",
+    "GEN_AI_OPERATION_CHAT",
+    "INDEX_KEY",
+    "ITEM_KEY",
+    "LIMITER_KEY",
+    "MAX_STEP_DEPTH",
+    "PRINCIPAL_KEY",
+    "REDUCED_KEY",
+    "RESERVED_KEYS",
+    "STEPS_KEY",
+    "AgentBudgetDegradedError",
+    "AgentCheckpoint",
+    "AgentDefinition",
+    "AgentHandoffUnsupportedError",
+    "AgentRuntime",
+    "AgentTransferCycleError",
+    "AidRuntimeError",
+    "BaselineGate",
+    "Budget",
+    "BudgetExceededError",
+    "Capability",
+    "CapabilityMismatchError",
+    "CaseOutcome",
+    "Chunk",
+    "Chunker",
+    "ChunkingSpec",
+    "ChunkingStrategy",
+    "Citation",
+    "CitationGrounding",
+    "CodeChunker",
+    "CompletionCache",
+    "CompletionRequest",
+    "CompletionResponse",
+    "ConcurrencyLimiter",
+    "ConfigurationError",
+    "Connector",
+    "CostLedger",
+    "CostProfile",
+    "Dataset",
+    "DatasetRun",
+    "DeepAgentsEngineError",
+    "DeepAgentsMaxStepsError",
+    "DeepAgentsUnavailableError",
+    "DeepAgentsVersionMismatchError",
+    "DistanceMetric",
+    "Embedder",
+    "EmbeddingBatch",
+    "EmbeddingCostProfile",
+    "EmbeddingSpec",
+    "EvalBaseline",
+    "EvalCase",
+    "EvalError",
+    "EvalRun",
+    "ExactMatch",
+    "Example",
+    "FakeDeterministicEmbedder",
+    "FakeProvider",
+    "FeatureDeferredError",
+    "FileConnector",
+    "FileMemoryStore",
+    "FinishReason",
+    "FixedChunker",
+    "GateConfigurationError",
+    "GateResult",
+    "GatewayRunner",
+    "GenerationResult",
+    "GuardrailBlockedError",
+    "HumanApproval",
+    "HumanDecision",
+    "InMemoryVectorStore",
+    "InProcessMemoryStore",
+    "IndexSpec",
+    "IngestReport",
+    "JsonSchemaValid",
+    "JudgeVerdict",
+    "LedgerEntry",
+    "LexicalReranker",
+    "LlmJudge",
+    "MeanReciprocalRank",
+    "MemoryDefinition",
+    "MemoryStore",
+    "Message",
+    "Metric",
+    "MetricBaseline",
+    "MetricGateResult",
+    "MetricResult",
+    "MetricRun",
+    "ModelCacheConfig",
+    "ModelGateway",
+    "ModelSpec",
+    "NormalizedContains",
+    "OpenAICompatibleEmbedder",
+    "OpenAICompatibleProvider",
+    "PendingApproval",
+    "PgVectorStore",
+    "PinnedEmbedding",
+    "PinnedModel",
+    "Pipeline",
+    "PipelineContext",
+    "PipelineError",
+    "PolicyEvaluationError",
+    "Principal",
+    "PromptNotFoundError",
+    "PromptRegistry",
+    "PromptRenderError",
+    "PromptTemplate",
+    "Provider",
+    "ProviderError",
+    "ProviderResponseError",
+    "RankedId",
+    "RecallAtK",
+    "RecursiveChunker",
+    "RefreshMode",
+    "RefreshSpec",
+    "RenderedPrompt",
+    "RerankSpec",
+    "Reranker",
+    "RetrievalCase",
+    "RetrievalGate",
+    "RetrievalMetric",
+    "RetrievalMetricSpec",
+    "RetrievalResult",
+    "RetrievedItem",
+    "Retriever",
+    "RetrieverBinding",
+    "RetrieverSeam",
+    "RetrieverSpec",
+    "Role",
+    "RunResult",
+    "RunStatus",
+    "Runner",
+    "RuntimeSpec",
+    "ScoredChunk",
+    "ScriptedTurn",
+    "SearchHit",
+    "SemanticCacheConfig",
+    "SourceDocument",
+    "SourceKind",
+    "SourceSpec",
+    "SpendSummary",
+    "Step",
+    "StepKind",
+    "StepRecord",
+    "StepResult",
+    "StopPipeline",
+    "StoreKind",
+    "StoreRecord",
+    "StreamChunk",
+    "StructuredOutputError",
+    "ThreadMemory",
+    "Threshold",
+    "TokenUsage",
+    "Tool",
+    "ToolArgumentError",
+    "ToolCall",
+    "ToolDefinition",
+    "ToolExecutionError",
+    "ToolExecutor",
+    "ToolNotFoundError",
+    "ToolPermissionError",
+    "ToolResult",
+    "ToolSpec",
+    "UnknownModelAliasError",
+    "VectorStore",
+    "VectorStoreSpec",
+    "__version__",
+    "agent_span",
+    "aid_attributes",
+    "assemble_context",
+    "binding_from_spec",
+    "bm25_scores",
+    "branch",
+    "build_agent",
+    "cache_key_for",
+    "chunk_document",
+    "chunk_id_for",
+    "chunker_for",
+    "cite",
+    "create_store",
+    "default_metrics",
+    "embedder_for",
+    "emit_step",
+    "estimate_cost_usd",
+    "estimate_prompt_cost_usd",
+    "estimate_tokens",
+    "estimate_usage",
+    "evaluate_once",
+    "format_problems",
+    "fuse",
+    "gate_from_config",
+    "gateway_judge",
+    "generate_step",
+    "get_tracer",
+    "lexical_ranking",
+    "lexical_score",
+    "llm_span",
+    "map_step",
+    "metric_names",
+    "normalize",
+    "open_connector",
+    "parallel",
+    "parse_structured",
+    "pinned_embedding",
+    "record_attributes",
+    "record_cost",
+    "record_exception",
+    "record_hitl",
+    "record_usage",
+    "reduce_step",
+    "repair_prompt",
+    "reranker_for",
+    "resolve_source",
+    "resolve_uri",
+    "retrieval_metrics",
+    "retrieve_step",
+    "rrf_score",
+    "run_evaluation",
+    "run_structured",
+    "similarity",
+    "tokenize",
+    "tool_step",
+    "z_critical",
+]

aid_runtime/agents/__init__.py

@@ -0,0 +1,94 @@
+"""The native agent runtime: a loop, control transfer and delegation, budgets, HITL.
+
+The entry point is :class:`AgentRuntime`. Build it with
+:meth:`AgentRuntime.from_ir` from an emitted IR document and call
+:meth:`AgentRuntime.run`; a run that stops for a person returns a
+:class:`RunResult` whose ``checkpoint`` is what :meth:`AgentRuntime.resume` needs.
+
+Naming, because the IR's two control edges are easy to conflate:
+
+* ``handoffs`` -> :meth:`AgentRuntime._transfer`. Control **moves**; the target
+  produces the final answer and the caller does not resume.
+* ``delegates`` -> :meth:`AgentRuntime._delegate`. Control is **lent**; the
+  delegate returns one observation and the caller produces the final answer.
+"""
+
+from __future__ import annotations
+
+from aid_runtime.agents.guardrails import (
+    DETECTORS,
+    GUARDRAIL_ACTIONS,
+    GUARDRAIL_STAGES,
+    Detection,
+    GuardrailEngine,
+    GuardrailEscalation,
+    GuardrailRecord,
+    GuardrailVerdict,
+    detect,
+)
+from aid_runtime.agents.ir import (
+    AgentDefinition,
+    GuardrailDefinition,
+    HumanApproval,
+    MemoryDefinition,
+    RuntimeSpec,
+    ToolSpec,
+)
+from aid_runtime.agents.loop import AgentRuntime
+from aid_runtime.agents.memory import (
+    IMPLEMENTED_MEMORY_KINDS,
+    MEMORY_SCOPES,
+    FileMemoryStore,
+    InProcessMemoryStore,
+    MemoryStore,
+    ThreadMemory,
+    check_memory_supported,
+    render_context,
+)
+from aid_runtime.agents.policy import Principal, evaluate_policy, policy_source
+from aid_runtime.agents.state import (
+    AgentCheckpoint,
+    HumanDecision,
+    PendingApproval,
+    RunResult,
+    RunStatus,
+    StepKind,
+    StepRecord,
+)
+
+__all__ = [
+    "DETECTORS",
+    "GUARDRAIL_ACTIONS",
+    "GUARDRAIL_STAGES",
+    "IMPLEMENTED_MEMORY_KINDS",
+    "MEMORY_SCOPES",
+    "AgentCheckpoint",
+    "AgentDefinition",
+    "AgentRuntime",
+    "Detection",
+    "FileMemoryStore",
+    "GuardrailDefinition",
+    "GuardrailEngine",
+    "GuardrailEscalation",
+    "GuardrailRecord",
+    "GuardrailVerdict",
+    "HumanApproval",
+    "HumanDecision",
+    "InProcessMemoryStore",
+    "MemoryDefinition",
+    "MemoryStore",
+    "PendingApproval",
+    "Principal",
+    "RunResult",
+    "RunStatus",
+    "RuntimeSpec",
+    "StepKind",
+    "StepRecord",
+    "ThreadMemory",
+    "ToolSpec",
+    "check_memory_supported",
+    "detect",
+    "evaluate_policy",
+    "policy_source",
+    "render_context",
+]