Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,49 @@

All notable changes to the E2A framework documents and reference code.

## v1.6.1 — Vendor-neutral handling for managed providers (design note MP-04)

What a managed deployment needs from E2A, selected by configuration, capabilities and the
`features` map — never by a provider name. A test now enforces it (`tests/test_neutrality.py`):
`e2a` imports no vendor SDK and compares nothing with a vendor name. Vendor handling stays in
the provider layer (e2a-managed-providers); e2a-adapters gets the matching boundary test (no
model-provider SDK). Additive: no signature changes, and with the new keys at their defaults a
v1.6.0 deployment behaves as before (one exception, the secret scan, is under **Changed**).

### Added
- **Model routes (P8):** `model_routes = [{on: [error kinds | "refusal"], to: model_id, llm_service, max_attempts}]`.
- A `FAILED` call whose `error_kind` (new on the payload) matches, or a `REFUSED` one, is answered once by the route's model or bound service; the result carries `fallback_from` and leaves no failed key.
- A route never routes again. A service that declares `refusal_fallback_server` (new capability) falls back on its own side, so E2A takes no refusal route for it.
- In a profile, `"@<seam>"` names a bound object (`"@delegated_runtime"`); `Bindings.config()` resolves it.
- **Features and structured output (P9):** a bound service declares `features` (or `_features_for(config)`): `structured_output: none` refuses a response schema (`StructuredOutputUnsupported`); `sampling: unsupported` drops temperature; `reasoning: none` drops `reasoning_effort` (each logged `param_dropped`).
- `reasoning_effort` is one vocabulary: `minimal | low | medium | high | max`.
- **Every structured result is checked** against the schema it was asked for (`e2a.schema_check`, no new dependency): `structured_output_valid`, `schema_errors`. `structured_output_strict` turns a mismatch into `FAILED` (`StructuredOutputInvalid`).
- **Telemetry and cost (P12):** each result is described once (tenant, correlation, agent, workflow step, status, refusal, fallback, GenAI model and token attributes) through the hook `_record_telemetry`.
- The default sets them on the active OpenTelemetry span when the API is installed, and passes them to a bound `observability_engine.record_inference` (new on `BaseObservability`: `e2a.llm.inference_total`, `e2a.llm.tokens`, `e2a.llm.cost_usd` through the metric hooks).
- `model_price_table` adds `cost_usd`. Agents name themselves to the service.
- **Adaptive admission and the quota authority (P7 b, N10):** a provider throttle lowers the pod's admission share (`admission_throttle_decay`, down to `admission_throttle_floor`) and it recovers over `admission_recovery_seconds`, so callers get E2A's typed `AdmissionTimeout` instead of more 429s.
- `quota_authority: gateway` skips E2A's token bucket when a gateway enforces quota (concurrency permits stay).
- **Scopes (P3):** `scopes = {"tenant:<id>": {...}, "agent:<name>": {...}}` overlays config per call: tenant first, then agent. `scoped_config()` is applied by `BaseAgent.run` and `BaseWorkflow.execute`.
- An agent scope may bind its own `llm_service`, which replaces the prototype's `DelegatedAgent`.
- Unregistered keys and keys that identify the request (`tenant_id`, `idempotency_*`, ...) are refused.
- **`DelegatedRuntime` (P15, `e2a.delegated`):** the base for managed agent runtimes, bound as one agent's model step.
- Read tools only (`MaterialToolRefused`); host-side tool calls go through the tool's own `execute()` for the request's tenant.
- Sessions are bounded by `delegated_max_turns` (`DelegatedTurnLimit`).
- **`BaseReranker` port (P17):** `BaseRAGPipeline.reranker`. `_rerank` is no longer abstract: its default uses the reranker, else keeps index order, cut to `rerank_top_n`.
- Embedding models and vector indexes may declare `dimensions`; `check_dimensions` refuses a mismatch (in `RAGPipeline` and `Bindings.verify()`).
- Profiles take `recommends`: a missing recommended capability is a warning (`Bindings.warnings`), not a failure.
- **Classifier guardrails (P21):** `ManagedGuardrailStage` (ingress) and `ManagedGuardrailEgressStage`, with `GuardrailVerdict`. A subclass implements `_screen`.
- E2A owns the rules: the fields screened are `guardrail_fields`; a block is `FirewallRefusal`; an unavailable classifier fails closed unless `guardrail_fail_open`.
- **Pipeline checks (P24):** `BasePipeline` verifies the deployment's bindings first (`bindings=`), and builds `artifact_matrix` when it is set.
- **MCP (P19):** `MCPToolService(server_url, credential_provider)` gives one instance per server, each with its own identity. `BaseToolService._auth_headers` is the hook. `BaseMCPServer.export_tool_manifest(fmt='mcp' | 'declarations')` is the same list as `tools/list`.
- **Keys:** `model_routes`, `structured_output_strict`, `reasoning_effort`, `model_price_table`, `quota_authority`, `admission_throttle_decay`, `admission_throttle_floor`, `admission_recovery_seconds`, `guardrail_fields`, `guardrail_fail_open`, `delegated_max_turns`, `artifact_matrix`, `secret_scan_paths`, `scopes`.

### Changed
- **`BasePipeline` runs a built-in secret scan** before the project's own scans, over `secret_scan_paths` (default `src`).
- It matches only high-confidence credential shapes: cloud access keys, model-provider and GitHub tokens, private keys.
- A line can opt out with `e2a: allow-secret`, and `secret_scan_paths: []` turns the scan off.
- **`register_config_key`:** two casts are the same meaning when they read the default's environment spelling alike. A provider package's earlier registration of a key E2A now owns (`guardrail_fields`) keeps importing.

## v1.6.0 — Contracts for managed providers (design note MP-02)

The vendor-neutral contracts lifted from the managed-providers prototype (assessment MP-00).
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ It focuses on the boundary where probabilistic reasoning meets deterministic ent

## Install

pip install "e2a-framework @ git+https://github.com/subhamviky/e2a-framework.git@v1.6.0"
pip install "e2a-framework @ git+https://github.com/subhamviky/e2a-framework.git@v1.6.1"

Poetry: `e2a-framework = { git = "https://github.com/subhamviky/e2a-framework.git", tag = "v1.6.0" }`.
Poetry: `e2a-framework = { git = "https://github.com/subhamviky/e2a-framework.git", tag = "v1.6.1" }`.
The framework is the `e2a` package (`from e2a import BaseAgent, BaseWorkflow, Steps, Step`); the release
gate is `from e2a.release import ProjectReleaseGate`; the `e2a_base` module re-exports the same names. Since v1.3 hooks use the v1.2 signature (`state, ctx, …`).

**Production adapters (e2a-adapters, since v1.4.0):** DynamoDB (v1.4.0), Firestore and Cosmos DB (v1.5.0)
implementations of the idempotency, transactional, lease and checkpoint ports in [`adapters/`](adapters/README.md),
a separate distribution at this tag (`pip install "e2a-adapters[aws,gcp,azure] @ git+https://github.com/subhamviky/e2a-framework.git@v1.6.0#subdirectory=adapters"`;
a separate distribution at this tag (`pip install "e2a-adapters[aws,gcp,azure] @ git+https://github.com/subhamviky/e2a-framework.git@v1.6.1#subdirectory=adapters"`;
pick the extras you need).
Every adapter passes the port contract kit, `e2a.port_contract`.

Expand All @@ -32,6 +32,7 @@ registry: a service's CI builds it from the tag (`mvn -f java/pom.xml install -D

| e2a-framework | a2c-framework | capability-oriented-dsa |
|---|---|---|
| `v1.6.1` (vendor-neutral handling for managed providers: model routes, structured-output checks, scopes, telemetry and cost, adaptive admission, delegated runtimes, reranker port, classifier guardrails, pipeline and MCP checks; the neutrality test) | `v1.3.0` | `v0.2.x`, `v0.3.x` |
| `v1.6.0` (contracts for managed providers: canonical types, typed refusals, bindings and profiles, capabilities, credentials, `check_llm_service`) | `v1.3.0` | `v0.2.x`, `v0.3.x` |
| `v1.5.1` (model-call retries, provider metadata kept, rerank query; e2a-adapters and e2a-java `1.5.1`) | `v1.3.0` | `v0.2.x`, `v0.3.x` |
| `v1.5.0` (e2a-adapters `1.5.0`: Firestore and Cosmos DB; e2a-java `1.5.0`) | `v1.3.0` (runs on `v1.5.0` unchanged) | `v0.2.x`, `v0.3.x` |
Expand Down
2 changes: 1 addition & 1 deletion adapters/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "e2a-adapters"
version = "1.6.0"
version = "1.6.1"
description = "Production adapters for the E2A foundation ports: DynamoDB, Firestore, Cosmos DB"
readme = "README.md"
license = "Apache-2.0"
Expand Down
34 changes: 34 additions & 0 deletions adapters/tests/test_boundary.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
"""v1.6.1 (design note MP-04 / MP-03 section 0): e2a-adapters holds cloud infrastructure
(databases; brokers, secrets and identity from 1.7.0) and never a model provider. AI vendor
handling lives in the provider layer (e2a-managed-providers)."""
import ast
from pathlib import Path

import e2a_adapters

PACKAGE = Path(e2a_adapters.__file__).parent
AI_MODULES = ('anthropic', 'openai', 'vertexai', 'llama_stack_client', 'cohere', 'mistralai', 'langchain',
'llama_index', 'litellm', 'ollama')
AI_SUBMODULES = ('google.genai', 'google.generativeai', 'google.cloud.aiplatform', 'azure.ai',
'azure.search', 'azure.identity.aio._internal.ai')
AI_SERVICE_CLIENTS = ('bedrock', 'bedrock-runtime', 'bedrock-agent', 'bedrock-agent-runtime', 'sagemaker-runtime')


def test_no_model_provider_sdk_in_adapters():
modules = sorted(PACKAGE.rglob('*.py'))
assert modules, PACKAGE
found = []
for path in modules:
tree = ast.parse(path.read_text())
for node in ast.walk(tree):
names = []
if isinstance(node, ast.Import):
names = [a.name for a in node.names]
elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
names = [node.module]
for name in names:
if name.split('.')[0] in AI_MODULES or name.startswith(AI_SUBMODULES):
found.append(f'{path.name}:{node.lineno}: import {name}')
if isinstance(node, ast.Constant) and node.value in AI_SERVICE_CLIENTS:
found.append(f'{path.name}:{node.lineno}: AI service client {node.value!r}')
assert not found, 'model-provider code in e2a-adapters:\n' + '\n'.join(found)
2 changes: 1 addition & 1 deletion java/e2a-core/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<parent>
<groupId>com.subhamviky.e2a</groupId>
<artifactId>e2a-java</artifactId>
<version>1.6.0</version>
<version>1.6.1</version>
</parent>
<artifactId>e2a-core</artifactId>
<name>e2a-core</name>
Expand Down
2 changes: 1 addition & 1 deletion java/e2a-cqrs/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<parent>
<groupId>com.subhamviky.e2a</groupId>
<artifactId>e2a-java</artifactId>
<version>1.6.0</version>
<version>1.6.1</version>
</parent>
<artifactId>e2a-cqrs</artifactId>
<name>e2a-cqrs</name>
Expand Down
2 changes: 1 addition & 1 deletion java/e2a-spring-jpa/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<parent>
<groupId>com.subhamviky.e2a</groupId>
<artifactId>e2a-java</artifactId>
<version>1.6.0</version>
<version>1.6.1</version>
</parent>
<artifactId>e2a-spring-jpa</artifactId>
<name>e2a-spring-jpa</name>
Expand Down
2 changes: 1 addition & 1 deletion java/e2a-test/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<parent>
<groupId>com.subhamviky.e2a</groupId>
<artifactId>e2a-java</artifactId>
<version>1.6.0</version>
<version>1.6.1</version>
</parent>
<artifactId>e2a-test</artifactId>
<name>e2a-test</name>
Expand Down
2 changes: 1 addition & 1 deletion java/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<!-- e2a-java: the E2A runtime for Java (design note D-01). Released with E2A's tag, at E2A's version. -->
<groupId>com.subhamviky.e2a</groupId>
<artifactId>e2a-java</artifactId>
<version>1.6.0</version>
<version>1.6.1</version>
<packaging>pom</packaging>
<name>e2a-java</name>
<description>E2A runtime contracts for Java: the v1.2 agent lifecycle, declared workflows, governance stages,
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "e2a-framework"
version = "1.6.0"
version = "1.6.1"
description = "E2A - Enterprise-to-Agentic runtime contracts (reference implementation)"
readme = "README.md"
license = "Apache-2.0"
Expand Down
15 changes: 9 additions & 6 deletions reference/e2a/__init__.py
Original file line number Diff line number Diff line change
@@ -1,28 +1,31 @@
"""E2A: Enterprise-to-Agentic runtime contracts.

Modules: core, config, resilience, observability, governance, validation, llm, agents, workflows, rag, tools, ports, pipeline, infra; context, stages, conformance (v1.2); release (v1.2.2: ProjectReleaseGate, import it from e2a.release); port_contract (v1.4.0: the behavioural suite every port adapter passes, import it from e2a.port_contract); llm_types, capabilities, bindings (v1.6.0: canonical model types, capabilities, profiles and bindings).
Modules: core, config, resilience, observability, governance, validation, llm, agents, workflows, rag, tools, ports, pipeline, infra; context, stages, conformance (v1.2); release (v1.2.2: ProjectReleaseGate, import it from e2a.release); port_contract (v1.4.0: the behavioural suite every port adapter passes, import it from e2a.port_contract); llm_types, capabilities, bindings (v1.6.0: canonical model types, capabilities, profiles and bindings); delegated, schema_check (v1.6.1: the delegated-runtime base, the structured-output check).
"""
from .core import ErrorClass, classify_error, ModelRefusal, DehydrationInterrupt, NFRViolationError, ConcurrencyConflict, AdmissionTimeout, DeadlineExceeded, CircuitOpenError, BulkheadFullError, PhysicalOutcome, outcome_of, Deadline, ClaimStatus, ClaimResult, CommitResult, LeaseHandle, E2A_METRICS
from .config import ConfigKey, E2A_CONFIG, register_config_key, resolve_config, unknown_config_keys, config_reference_markdown, env_example
from .config import ConfigKey, E2A_CONFIG, register_config_key, resolve_config, unknown_config_keys, scoped_config, config_reference_markdown, env_example
from .resilience import run_sync, RetryBudget, CircuitBreaker, Bulkhead, ResiliencePolicy, validate_capacity
from .observability import BaseObservability
from .governance import BaseGovernanceFramework
from .validation import ValidationResult, BaseValidationService, OrderOpsValidationService
from .llm import DLP_MARKER, BaseLLMAgentService
from .llm import DLP_MARKER, REASONING_EFFORTS, BaseLLMAgentService, StructuredOutputInvalid, StructuredOutputUnsupported
from .agents import BaseAgent, LLMOnlyAgent
from .workflows import BaseWorkflow, ResumeRefused, Route, Step, Steps
from .rag import BaseRAGPipeline, BaseIndexingPipeline, BaseEmbeddingModel, BaseVectorIndex, RAGPipeline
from .rag import BaseRAGPipeline, BaseIndexingPipeline, BaseEmbeddingModel, BaseVectorIndex, BaseReranker, RAGPipeline, check_dimensions
from .tools import BaseToolService, RestToolService, MCPToolService, BaseMCPServer
from .ports import BaseCredentialProvider, TokenCredentialProvider, BasePromptRegistry, BaseTransactionalStore, BaseCacheStore, BaseIdempotencyStore, BaseCheckpointStore, BaseDistributedLock, BaseWebhookDispatcher, BaseSchemaTransformer, BaseMemoryManager, BaseOutboxSweeper, BaseReconciliationService
from .pipeline import BasePipeline
from .llm_types import Message, ModelResult, StopReason, ToolCall, ToolDeclaration, Usage
from .capabilities import CapabilityError, capabilities_of, register_capability
from .bindings import Bindings, Profile, bindings_from_profile, register_provider_package
from .delegated import DelegatedRuntime, DelegatedTurnLimit, MaterialToolRefused
from .schema_check import schema_errors
from .infra import BaseInfraProvisioner, GCPInfraProvisioner
from .context import FailedKeys, MessageLog, ModifyAccess, ReadAccess, RequestContext, ToolDenied
from .stages import (ApprovalRequired, ApprovalStage, CapacityRefusal, CapacityStage, EgressStage,
FirewallRefusal, FirewallStage, GovernanceRefusal, IngressStage, InflightLimiter,
FirewallRefusal, FirewallStage, GovernanceRefusal, GuardrailVerdict, IngressStage,
InflightLimiter, ManagedGuardrailEgressStage, ManagedGuardrailStage,
RedactionStage, SandboxRefusal, SandboxStage, TokenBudgetRefusal, TokenBudgetStage,
ToolRefusal, compile_redactions, redact_text)

__version__ = "1.6.0"
__version__ = "1.6.1"
1 change: 1 addition & 0 deletions reference/e2a/_propagation.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ async def _infer_async(self, messages, config=None, **kwargs) -> Dict[str, Any]:
"""Awaitable bridge for async callers (orchestrators, tests)."""
svc = self._resolve_llm_service(config, **kwargs)
kwargs.pop('llm_service', None)
kwargs.setdefault('agent_name', getattr(self, 'agent_name', type(self).__name__)) # v1.6.1: telemetry
result = await svc.process_inference(messages, config, **kwargs)
if result.get('status') == 'FAILED':
raise RuntimeError(f"LLM inference failed: {result.get('error')}")
Expand Down
5 changes: 3 additions & 2 deletions reference/e2a/agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
from .context import FailedKeys, MessageLog, ModifyAccess, ReadAccess, RequestContext
from ._contract import call_hook, declares_ctx, refuse_v11_hooks
from .stages import GovernanceRefusal
from .config import resolve_config
from .config import resolve_config, scoped_config
from ._propagation import _PropagationMixin
from .governance import BaseGovernanceFramework
# ==================================================
Expand Down Expand Up @@ -62,7 +62,8 @@ def run(self, state: Dict[str, Any], config: Dict[str, Any] = None,
-> build -> infer -> evaluate/fallback -> act (only after an accepted evaluation,
and not after the deadline) -> confirm -> redaction. A v1.1 agent (hooks without
`ctx`) runs exactly as in v1.1."""
config = config or {}
config = scoped_config(config, getattr(self, 'agent_name', type(self).__name__),
(ctx.tenant_id if ctx is not None else None) or tenant_id or state.get('tenant_id'))
given = {'tenant_id': tenant_id, 'correlation_id': correlation_id, 'idempotency_key': idempotency_key}
if ctx is None:
ctx = RequestContext.begin(
Expand Down
Loading
Loading