efficient-agent-protocol 0.1.0__tar.gz

efficient_agent_protocol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GenieWeenie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

efficient_agent_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: efficient-agent-protocol
+Version: 0.1.0
+Summary: High-performance multi-agent framework for stateful batched execution.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic==2.6.1
+Requires-Dist: requests==2.32.4
+Requires-Dist: beautifulsoup4==4.12.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: pre-commit>=3.7.0; extra == "dev"
+Provides-Extra: storage
+Requires-Dist: redis>=5.0.0; extra == "storage"
+Requires-Dist: psycopg[binary]>=3.1.0; extra == "storage"
+Dynamic: license-file
+
+# Efficient Agent Protocol (EAP)
+
+[![CI](https://github.com/GenieWeenie/efficient-agent-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/GenieWeenie/efficient-agent-protocol/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+
+> Status: Experimental (pre-1.0). APIs and schema may change.
+> See `STABILITY.md` and `ROADMAP.md` for guarantees and planned milestones.
+> Latest stable release: `v0.1.4`
+
+Efficient Agent Protocol is a local-first framework for multi-step tool workflows.
+It stores large outputs as pointer-backed state (`ptr_*`) and runs dependency-aware DAG steps in parallel.
+
+## Who This Is For
+
+- Python developers building local-first agent/tool orchestration
+- Teams that need pointer-backed state and execution trace visibility
+
+Not ideal yet for:
+- strict long-term API compatibility requirements before `v1.0`
+- non-technical users expecting zero-configuration onboarding
+
+## What You Get
+
+- Pointer-based state to keep prompts small
+- Parallel DAG execution with retries and validation
+- Built-in chat UI (Streamlit) with trace + data inspection
+- Conversation memory (full/window/summary)
+- Pluggable pointer storage backends (SQLite, Redis, PostgreSQL)
+
+## Quickstart (GitHub-first)
+
+Requirements:
+- Python 3.9+
+
+1. Install
+
+```bash
+git clone https://github.com/GenieWeenie/efficient-agent-protocol.git
+cd efficient-agent-protocol
+pip install -e .
+```
+
+2. Configure
+
+```bash
+cp .env.example .env
+```
+
+Minimum variables:
+
+```bash
+EAP_BASE_URL=http://localhost:1234
+EAP_MODEL=nemotron-orchestrator-8b
+EAP_API_KEY=not-needed
+```
+
+3. Smoke test
+
+```bash
+python -m examples.01_minimal
+```
+
+4. Run dashboard
+
+```bash
+pip install streamlit pandas
+streamlit run app.py
+```
+
+5. Use it
+
+- Open `http://localhost:8501`
+- In **Agent Chat**, ask for a task
+- Check **Data Inspector** for pointer payloads
+- Check **Execution Trace** for step timing/retries/errors
+
+## Programmatic Example
+
+```python
+from eap.protocol import StateManager
+from eap.environment import AsyncLocalExecutor, ToolRegistry
+from eap.environment.tools import read_local_file, READ_FILE_SCHEMA
+from eap.agent import AgentClient
+
+state_manager = StateManager()
+registry = ToolRegistry()
+registry.register("read_local_file", read_local_file, READ_FILE_SCHEMA)
+executor = AsyncLocalExecutor(state_manager, registry)
+
+architect = AgentClient(
+    base_url="http://localhost:1234",
+    model_name="nemotron-orchestrator-8b",
+    provider_name="local",
+)
+
+manifest = registry.get_agent_manifest()
+macro = architect.generate_macro("Read README.md and summarize setup steps", manifest)
+# asyncio.run(executor.execute_macro(macro))
+```
+
+## Common Commands
+
+```bash
+python3 -m pytest -q
+pre-commit run --all-files
+python3 scripts/migrate_state_db.py --db-path agent_state.db --dry-run
+python3 scripts/export_metrics.py --db-path agent_state.db --output metrics/latest.json
+python3 -m build
+```
+
+## Docs
+
+- `STABILITY.md`
+- `ROADMAP.md`
+- `docs/v1_contract.md`
+- `docs/release_notes_template.md`
+- `docs/benchmarks.md`
+- `docs/release.md`
+- `docs/v1_stabilization_checklist.md`
+- `docs/migrations.md`
+- `docs/observability.md`
+- `docs/maintainer_runbook.md`
+- `SECURITY.md`
+- `CONTRIBUTING.md`
+- GitHub roadmap board: https://github.com/users/GenieWeenie/projects/1
+- `docs/configuration.md`
+- `docs/architecture.md`
+- `docs/tools.md`
+- `docs/workflow_schema.md`
+- `docs/storage_lifecycle.md`
+- `docs/storage_backends.md`
+- `docs/sdk_contract.md`
+- `docs/distributed_execution.md`
+- `docs/troubleshooting.md`
+- `docs/eap_proof_sheet.md`

efficient_agent_protocol-0.1.0/README.md

@@ -0,0 +1,135 @@
+# Efficient Agent Protocol (EAP)
+
+[![CI](https://github.com/GenieWeenie/efficient-agent-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/GenieWeenie/efficient-agent-protocol/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+
+> Status: Experimental (pre-1.0). APIs and schema may change.
+> See `STABILITY.md` and `ROADMAP.md` for guarantees and planned milestones.
+> Latest stable release: `v0.1.4`
+
+Efficient Agent Protocol is a local-first framework for multi-step tool workflows.
+It stores large outputs as pointer-backed state (`ptr_*`) and runs dependency-aware DAG steps in parallel.
+
+## Who This Is For
+
+- Python developers building local-first agent/tool orchestration
+- Teams that need pointer-backed state and execution trace visibility
+
+Not ideal yet for:
+- strict long-term API compatibility requirements before `v1.0`
+- non-technical users expecting zero-configuration onboarding
+
+## What You Get
+
+- Pointer-based state to keep prompts small
+- Parallel DAG execution with retries and validation
+- Built-in chat UI (Streamlit) with trace + data inspection
+- Conversation memory (full/window/summary)
+- Pluggable pointer storage backends (SQLite, Redis, PostgreSQL)
+
+## Quickstart (GitHub-first)
+
+Requirements:
+- Python 3.9+
+
+1. Install
+
+```bash
+git clone https://github.com/GenieWeenie/efficient-agent-protocol.git
+cd efficient-agent-protocol
+pip install -e .
+```
+
+2. Configure
+
+```bash
+cp .env.example .env
+```
+
+Minimum variables:
+
+```bash
+EAP_BASE_URL=http://localhost:1234
+EAP_MODEL=nemotron-orchestrator-8b
+EAP_API_KEY=not-needed
+```
+
+3. Smoke test
+
+```bash
+python -m examples.01_minimal
+```
+
+4. Run dashboard
+
+```bash
+pip install streamlit pandas
+streamlit run app.py
+```
+
+5. Use it
+
+- Open `http://localhost:8501`
+- In **Agent Chat**, ask for a task
+- Check **Data Inspector** for pointer payloads
+- Check **Execution Trace** for step timing/retries/errors
+
+## Programmatic Example
+
+```python
+from eap.protocol import StateManager
+from eap.environment import AsyncLocalExecutor, ToolRegistry
+from eap.environment.tools import read_local_file, READ_FILE_SCHEMA
+from eap.agent import AgentClient
+
+state_manager = StateManager()
+registry = ToolRegistry()
+registry.register("read_local_file", read_local_file, READ_FILE_SCHEMA)
+executor = AsyncLocalExecutor(state_manager, registry)
+
+architect = AgentClient(
+    base_url="http://localhost:1234",
+    model_name="nemotron-orchestrator-8b",
+    provider_name="local",
+)
+
+manifest = registry.get_agent_manifest()
+macro = architect.generate_macro("Read README.md and summarize setup steps", manifest)
+# asyncio.run(executor.execute_macro(macro))
+```
+
+## Common Commands
+
+```bash
+python3 -m pytest -q
+pre-commit run --all-files
+python3 scripts/migrate_state_db.py --db-path agent_state.db --dry-run
+python3 scripts/export_metrics.py --db-path agent_state.db --output metrics/latest.json
+python3 -m build
+```
+
+## Docs
+
+- `STABILITY.md`
+- `ROADMAP.md`
+- `docs/v1_contract.md`
+- `docs/release_notes_template.md`
+- `docs/benchmarks.md`
+- `docs/release.md`
+- `docs/v1_stabilization_checklist.md`
+- `docs/migrations.md`
+- `docs/observability.md`
+- `docs/maintainer_runbook.md`
+- `SECURITY.md`
+- `CONTRIBUTING.md`
+- GitHub roadmap board: https://github.com/users/GenieWeenie/projects/1
+- `docs/configuration.md`
+- `docs/architecture.md`
+- `docs/tools.md`
+- `docs/workflow_schema.md`
+- `docs/storage_lifecycle.md`
+- `docs/storage_backends.md`
+- `docs/sdk_contract.md`
+- `docs/distributed_execution.md`
+- `docs/troubleshooting.md`
+- `docs/eap_proof_sheet.md`

efficient_agent_protocol-0.1.0/agent/__init__.py

@@ -0,0 +1,20 @@
+# agent/__init__.py
+from .compiler import MacroCompiler, WorkflowGraphCompiler
+from .agent_client import AgentClient
+from .providers import CompletionRequest, CompletionResponse, LLMProvider, ProviderMessage
+from .providers import AnthropicProvider, GoogleProvider, OpenAIProvider
+from .providers import create_provider
+
+__all__ = [
+    "MacroCompiler",
+    "WorkflowGraphCompiler",
+    "AgentClient",
+    "ProviderMessage",
+    "CompletionRequest",
+    "CompletionResponse",
+    "LLMProvider",
+    "OpenAIProvider",
+    "AnthropicProvider",
+    "GoogleProvider",
+    "create_provider",
+]

efficient_agent_protocol-0.1.0/agent/agent_client.py

@@ -0,0 +1,131 @@
+# agent/agent_client.py
+import json
+from typing import Callable, Dict, Any, Optional
+from .compiler import MacroCompiler
+from .providers import CompletionRequest, LLMProvider, ProviderMessage, create_provider
+from protocol.models import BatchedMacroRequest
+
+
+class AgentClient:
+    def __init__(
+        self,
+        base_url: str,
+        model_name: str,
+        api_key: str = "not-needed",
+        system_prompt: str = "",
+        temperature: float = 0.0,
+        timeout_seconds: int = 60,
+        provider_name: str = "local",
+        fallback_provider_name: Optional[str] = None,
+        provider: Optional[LLMProvider] = None,
+    ):
+        self.endpoint = f"{base_url.rstrip('/')}/v1/chat/completions"
+        self.base_url = base_url.rstrip("/")
+        self.model_name = model_name
+        self.api_key = api_key
+        self.system_prompt = system_prompt
+        self.temperature = temperature
+        self.timeout_seconds = timeout_seconds
+        self.provider_name = provider_name
+        self.fallback_provider_name = fallback_provider_name
+        self.provider = provider or create_provider(
+            provider_name=provider_name,
+            base_url=self.base_url,
+            api_key=api_key,
+            timeout_seconds=timeout_seconds,
+            fallback_provider_name=fallback_provider_name,
+        )
+        self.compiler = MacroCompiler()
+
+    def _headers(self) -> Dict[str, str]:
+        if hasattr(self.provider, "_headers"):
+            return self.provider._headers()  # type: ignore[attr-defined]
+        if self.api_key and self.api_key != "not-needed":
+            return {"Authorization": f"Bearer {self.api_key}"}
+        return {}
+
+    def chat(self, user_input: str) -> str:
+        """Simple text-to-text chat for non-macro tasks like auditing."""
+        request = CompletionRequest(
+            model=self.model_name,
+            messages=[
+                ProviderMessage(role="system", content=self.system_prompt),
+                ProviderMessage(role="user", content=user_input),
+            ],
+            temperature=self.temperature,
+        )
+        response = self.provider.complete(request)
+        return response.text
+
+    def stream_chat(
+        self,
+        user_input: str,
+        on_token: Optional[Callable[[str], None]] = None,
+        fallback_to_non_stream: bool = True,
+    ) -> str:
+        """Stream chat tokens and return the final assembled content.
+
+        If streaming fails and `fallback_to_non_stream` is true, falls back to a
+        standard completion request and emits the remaining content.
+        """
+        request = CompletionRequest(
+            model=self.model_name,
+            messages=[
+                ProviderMessage(role="system", content=self.system_prompt),
+                ProviderMessage(role="user", content=user_input),
+            ],
+            temperature=self.temperature,
+        )
+        chunks = []
+        try:
+            for token in self.provider.stream(request):
+                if not token:
+                    continue
+                chunks.append(token)
+                if on_token:
+                    on_token(token)
+        except Exception:
+            if not fallback_to_non_stream:
+                raise
+            fallback_text = self.provider.complete(request).text
+            streamed_text = "".join(chunks)
+            if streamed_text and fallback_text.startswith(streamed_text):
+                remaining = fallback_text[len(streamed_text) :]
+            else:
+                remaining = fallback_text if not streamed_text else fallback_text
+            if remaining:
+                chunks.append(remaining)
+                if on_token:
+                    on_token(remaining)
+        return "".join(chunks)
+
+    def generate_macro(
+        self,
+        user_input: str,
+        hashed_manifest: Dict[str, Any],
+        error_feedback: str = None,
+        memory_context: str = "",
+    ) -> BatchedMacroRequest:
+        manifest_str = json.dumps(hashed_manifest, indent=2)
+        protocol_instructions = (
+            "### ENVIRONMENT MANIFEST ###\n"
+            f"{manifest_str}\n\n"
+            "### SYSTEM RULES ###\n"
+            "1. Output ONLY a JSON object. No conversational text.\n"
+            "2. Use the exact key names: 'steps', 'step_id', 'tool_name', 'arguments'.\n"
+            "3. Use the hashed IDs for 'tool_name'.\n"
+        )
+        memory_block = f"\n\n### MEMORY CONTEXT ###\n{memory_context}" if memory_context else ""
+        error_block = f"\n\n### FIX PREVIOUS ERROR ###\n{error_feedback}" if error_feedback else ""
+        
+        request = CompletionRequest(
+            model=self.model_name,
+            messages=[
+                ProviderMessage(role="system", content=f"{self.system_prompt}\n\n{protocol_instructions}"),
+                ProviderMessage(role="user", content=f"{user_input}{memory_block}{error_block}"),
+            ],
+            temperature=self.temperature,
+        )
+        response = self.provider.complete_with_tools(request)
+        raw_text = response.text
+        return self.compiler.compile(raw_text)

efficient_agent_protocol-0.1.0/agent/compiler.py

@@ -0,0 +1,123 @@
+# agent/compiler.py
+import json
+from typing import Any, Dict, Optional, Union
+from protocol.models import (
+    BatchedMacroRequest,
+    ExecutionLimits,
+    PersistedWorkflowGraph,
+    RetryPolicy,
+)
+
+
+def _extract_first_json_object(raw_payload: str, error_message: str) -> Dict[str, Any]:
+    """Extract the first top-level JSON object embedded in arbitrary text."""
+    decoder = json.JSONDecoder()
+    start_index = raw_payload.find("{")
+    while start_index != -1:
+        try:
+            parsed, _ = decoder.raw_decode(raw_payload, start_index)
+        except json.JSONDecodeError:
+            start_index = raw_payload.find("{", start_index + 1)
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+        start_index = raw_payload.find("{", start_index + 1)
+    raise ValueError(error_message)
+
+class MacroCompiler:
+    """
+    An advanced compiler that sanitizes and 'auto-heals' common LLM 
+    JSON hallucinations before validation.
+    """
+    @staticmethod
+    def compile(raw_llm_output: Union[str, Dict[str, Any]]) -> BatchedMacroRequest:
+        try:
+            # 1. Extract JSON from potential markdown or conversational noise
+            if isinstance(raw_llm_output, str):
+                parsed_data = _extract_first_json_object(
+                    raw_llm_output,
+                    error_message="No JSON object found in output.",
+                )
+            else:
+                parsed_data = raw_llm_output
+
+            # 2. AUTO-HEALING: Fix common hallucinations for smaller models
+            if "steps" in parsed_data:
+                for step in parsed_data["steps"]:
+                    # Fix 'tool' -> 'tool_name'
+                    if "tool" in step and "tool_name" not in step:
+                        step["tool_name"] = step.pop("tool")
+                    
+                    # Ensure step_id exists
+                    if "step_id" not in step:
+                        step["step_id"] = f"auto_step_{hash(str(step)) % 1000}"
+
+            # 3. Final Pydantic validation
+            return BatchedMacroRequest(**parsed_data)
+            
+        except Exception as e:
+            raise ValueError(f"Compiler Error: {str(e)}")
+
+
+class WorkflowGraphCompiler:
+    """Compile persisted workflow graph payloads into executable macro requests."""
+
+    @staticmethod
+    def _extract_json_object(raw_payload: str) -> Dict[str, Any]:
+        return _extract_first_json_object(
+            raw_payload,
+            error_message="No JSON object found in workflow graph payload.",
+        )
+
+    @staticmethod
+    def _coerce_graph_payload(
+        raw_graph: Union[str, Dict[str, Any], PersistedWorkflowGraph],
+    ) -> PersistedWorkflowGraph:
+        if isinstance(raw_graph, PersistedWorkflowGraph):
+            return raw_graph
+        if isinstance(raw_graph, str):
+            parsed = WorkflowGraphCompiler._extract_json_object(raw_graph)
+            return PersistedWorkflowGraph(**parsed)
+        if isinstance(raw_graph, dict):
+            return PersistedWorkflowGraph(**raw_graph)
+        raise ValueError("Unsupported workflow graph payload type.")
+
+    @staticmethod
+    def compile_graph(
+        raw_graph: Union[str, Dict[str, Any], PersistedWorkflowGraph],
+    ) -> PersistedWorkflowGraph:
+        try:
+            return WorkflowGraphCompiler._coerce_graph_payload(raw_graph)
+        except Exception as exc:
+            raise ValueError(f"Workflow graph validation failed: {exc}") from exc
+
+    @staticmethod
+    def compile_to_macro(
+        raw_graph: Union[str, Dict[str, Any], PersistedWorkflowGraph],
+        return_final_state_only: bool = True,
+        retry_policy: Optional[Union[RetryPolicy, Dict[str, Any]]] = None,
+        execution_limits: Optional[Union[ExecutionLimits, Dict[str, Any]]] = None,
+    ) -> BatchedMacroRequest:
+        graph = WorkflowGraphCompiler.compile_graph(raw_graph)
+        try:
+            retry_policy_model: Optional[RetryPolicy] = None
+            if retry_policy is not None:
+                retry_policy_model = (
+                    retry_policy if isinstance(retry_policy, RetryPolicy) else RetryPolicy(**retry_policy)
+                )
+
+            execution_limits_model: Optional[ExecutionLimits] = None
+            if execution_limits is not None:
+                execution_limits_model = (
+                    execution_limits
+                    if isinstance(execution_limits, ExecutionLimits)
+                    else ExecutionLimits(**execution_limits)
+                )
+
+            return graph.to_batched_macro_request(
+                return_final_state_only=return_final_state_only,
+                retry_policy=retry_policy_model,
+                execution_limits=execution_limits_model,
+            )
+        except Exception as exc:
+            raise ValueError(f"Workflow graph compile failed: {exc}") from exc

efficient_agent_protocol-0.1.0/agent/providers/__init__.py

@@ -0,0 +1,16 @@
+from .base import CompletionRequest, CompletionResponse, LLMProvider, ProviderMessage
+from .anthropic_provider import AnthropicProvider
+from .factory import create_provider
+from .google_provider import GoogleProvider
+from .openai_provider import OpenAIProvider
+
+__all__ = [
+    "ProviderMessage",
+    "CompletionRequest",
+    "CompletionResponse",
+    "LLMProvider",
+    "OpenAIProvider",
+    "AnthropicProvider",
+    "GoogleProvider",
+    "create_provider",
+]

efficient_agent_protocol-0.1.0/agent/providers/anthropic_provider.py

@@ -0,0 +1,73 @@
+from typing import Dict, List
+
+import requests
+
+from .base import CompletionRequest, CompletionResponse, LLMProvider
+
+
+class AnthropicProvider(LLMProvider):
+    """Adapter for Anthropic `/v1/messages` APIs."""
+
+    def __init__(self, endpoint: str, api_key: str, timeout_seconds: int):
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.timeout_seconds = timeout_seconds
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "x-api-key": self.api_key,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        }
+
+    def _to_payload(self, request: CompletionRequest) -> Dict[str, object]:
+        system_chunks: List[str] = []
+        messages = []
+        for msg in request.messages:
+            if msg.role == "system":
+                system_chunks.append(msg.content)
+            else:
+                role = "assistant" if msg.role == "assistant" else "user"
+                messages.append({"role": role, "content": msg.content})
+
+        payload: Dict[str, object] = {
+            "model": request.model,
+            "messages": messages,
+            "temperature": request.temperature,
+            "max_tokens": int(request.metadata.get("max_tokens", 1024)),
+        }
+        if system_chunks:
+            payload["system"] = "\n\n".join(system_chunks)
+        if request.tools:
+            payload["tools"] = request.tools
+        return payload
+
+    def _extract_text(self, raw_json: Dict[str, object]) -> str:
+        content = raw_json.get("content", [])
+        if isinstance(content, list):
+            text_parts = []
+            for item in content:
+                if isinstance(item, dict) and item.get("type") == "text":
+                    text_parts.append(str(item.get("text", "")))
+            return "".join(text_parts)
+        return ""
+
+    def _request(self, request: CompletionRequest) -> CompletionResponse:
+        response = requests.post(
+            self.endpoint,
+            json=self._to_payload(request),
+            headers=self._headers(),
+            timeout=self.timeout_seconds,
+        )
+        response.raise_for_status()
+        raw_json = response.json()
+        return CompletionResponse(text=self._extract_text(raw_json), raw_response=raw_json)
+
+    def complete(self, request: CompletionRequest) -> CompletionResponse:
+        return self._request(request)
+
+    def complete_with_tools(self, request: CompletionRequest) -> CompletionResponse:
+        return self._request(request)
+
+    def stream(self, request: CompletionRequest):
+        raise NotImplementedError("Streaming not implemented for AnthropicProvider yet.")