Upload initial Aegis project

.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environments
+.venv/
+venv/
+.env
+.env.*
+
+# Build
+build/
+dist/
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store
+
+# Runtime artifacts
+logs/
+runs/
+artifacts/
+*.log
+
+__pycache__/
+*.py[cod]

.mypy_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by mypy
+*

.mypy_cache/CACHEDIR.TAG

@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag automatically created by mypy.
+# For information about cache directory tags see https://bford.info/cachedir/

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,58 @@
+[
+  "tests/unit/test_cli_run.py::test_main_supports_help_and_execution[argv0-0]",
+  "tests/unit/test_cli_run.py::test_main_supports_help_and_execution[argv1-0]",
+  "tests/unit/test_cli_run.py::test_run_command_evaluator_failure",
+  "tests/unit/test_cli_run.py::test_run_command_json_output_failure",
+  "tests/unit/test_cli_run.py::test_run_command_json_output_success",
+  "tests/unit/test_cli_run.py::test_run_command_max_steps_forwarded",
+  "tests/unit/test_cli_run.py::test_run_command_rejects_empty_task",
+  "tests/unit/test_cli_run.py::test_run_command_runtime_exception",
+  "tests/unit/test_cli_run.py::test_run_command_success_with_text_output",
+  "tests/unit/test_cli_run.py::test_run_command_unknown_agent",
+  "tests/unit/test_cli_run.py::test_run_command_unknown_workflow",
+  "tests/unit/test_cli_run.py::test_run_command_verbose_failure_has_no_stack_trace_for_known_error",
+  "tests/unit/test_conductor.py::test_conductor_executes_registered_agent",
+  "tests/unit/test_conductor.py::test_conductor_rejects_mismatched_result_name",
+  "tests/unit/test_conductor.py::test_conductor_rejects_missing_agent",
+  "tests/unit/test_evaluator.py::test_evaluator_fails_unsuccessful_result",
+  "tests/unit/test_evaluator.py::test_evaluator_passes_valid_result",
+  "tests/unit/test_evaluator.py::test_evaluator_rejects_invalid_result",
+  "tests/unit/test_evaluator.py::test_evaluator_rejects_missing_result",
+  "tests/unit/test_memory.py::test_memory_store_adds_and_gets_entry",
+  "tests/unit/test_memory.py::test_memory_store_clear_removes_all_entries",
+  "tests/unit/test_memory.py::test_memory_store_deletes_entry",
+  "tests/unit/test_memory.py::test_memory_store_initializes_with_entries",
+  "tests/unit/test_memory.py::test_memory_store_normalizes_keys",
+  "tests/unit/test_memory.py::test_memory_store_raises_for_missing_key",
+  "tests/unit/test_memory.py::test_memory_store_rejects_delete_for_missing_key",
+  "tests/unit/test_memory.py::test_memory_store_rejects_duplicate_key",
+  "tests/unit/test_memory.py::test_memory_store_rejects_empty_key_lookup",
+  "tests/unit/test_memory.py::test_memory_store_set_replaces_existing_entry",
+  "tests/unit/test_models.py::test_agent_context_contains_task",
+  "tests/unit/test_models.py::test_agent_result_success",
+  "tests/unit/test_models.py::test_task_defaults_to_pending",
+  "tests/unit/test_planner.py::test_planner_output_is_bounded",
+  "tests/unit/test_planner.py::test_planner_returns_structured_plan",
+  "tests/unit/test_planner.py::test_planner_steps_have_sequential_ids",
+  "tests/unit/test_policies.py::test_agent_policy_combines_response_and_execution_rules",
+  "tests/unit/test_policies.py::test_execution_policy_defaults_to_restricted_permissions",
+  "tests/unit/test_policies.py::test_invalid_policy_limit_is_rejected",
+  "tests/unit/test_policies.py::test_response_policy_defaults",
+  "tests/unit/test_registry.py::test_registry_raises_when_agent_is_missing",
+  "tests/unit/test_registry.py::test_registry_registers_and_resolves_agent",
+  "tests/unit/test_registry.py::test_registry_rejects_duplicate_agent_names",
+  "tests/unit/test_registry.py::test_registry_returns_sorted_names",
+  "tests/unit/test_tool_registry.py::test_registry_accepts_initial_tools",
+  "tests/unit/test_tool_registry.py::test_registry_normalizes_tool_names",
+  "tests/unit/test_tool_registry.py::test_registry_raises_when_tool_is_missing",
+  "tests/unit/test_tool_registry.py::test_registry_registers_and_resolves_tool",
+  "tests/unit/test_tool_registry.py::test_registry_rejects_duplicate_tool_names",
+  "tests/unit/test_tool_registry.py::test_registry_rejects_empty_tool_name",
+  "tests/unit/test_tool_registry.py::test_registry_returns_sorted_names",
+  "tests/unit/test_tool_runner.py::test_tool_runner_executes_registered_tool",
+  "tests/unit/test_tool_runner.py::test_tool_runner_preserves_arguments",
+  "tests/unit/test_workflow.py::test_workflow_evaluates_failed_execution",
+  "tests/unit/test_workflow.py::test_workflow_runs_plan_execution_and_evaluation",
+  "tests/unit/test_workflow.py::test_workflow_stops_when_planner_fails",
+  "tests/unit/test_workflow.py::test_workflow_stores_all_results_in_memory"
+]

.ruff_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by ruff.
+*

.ruff_cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

README.md

@@ -0,0 +1,101 @@
+# Aegis
+
+Aegis is a modular Python framework for composing agent workflows, registries, memory, tool execution, and evaluation. The repository now ships a runnable CLI that executes tasks through the built-in orchestration layer.
+
+## What it does now
+
+- Registers agents and tools through typed registries
+- Executes workflows through a conductor and workflow engine
+- Stores run-scoped results in an in-memory memory store
+- Evaluates run output with a deterministic evaluator
+- Exposes a user-facing CLI: `aegis run`
+
+## Installation
+
+```bash
+cd /Users/giancarlovizhnay/aegis
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+aegis run --help
+aegis run "Run the default Aegis workflow"
+```
+
+## CLI usage
+
+Default text output:
+
+```bash
+aegis run "Review this repository"
+```
+
+Run a specific agent:
+
+```bash
+aegis run --agent default-task "Review this repository"
+```
+
+Run a named workflow:
+
+```bash
+aegis run --workflow review "Review this repository"
+```
+
+JSON output:
+
+```bash
+aegis run --output json "Review this repository"
+```
+
+Limit execution steps:
+
+```bash
+aegis run --max-steps 10 "Review this repository"
+```
+
+## Available options
+
+- `--agent <name>`: run a specific registered agent
+- `--workflow <name>`: run a named workflow
+- `--output text|json`: choose human-readable or structured output
+- `--max-steps <n>`: pass a step limit into the runtime context
+- `--verbose`: show debug details for unexpected failures only
+
+## Example output
+
+```text
+Run ID: run_...
+Status: completed
+Agent: default-task
+Workflow: default
+Result:
+{
+  "summary": "Received task: Review this repository"
+}
+```
+
+## Exit codes
+
+- `0`: success
+- `1`: unexpected internal error
+- `2`: invalid CLI input
+- `3`: configuration or registry error
+- `4`: policy violation
+- `5`: execution failure
+- `6`: evaluation failure
+
+## Current limitations
+
+- Persistence is still in-memory and resets on restart.
+- The default workflow is intentionally small and deterministic.
+- No external model provider is wired in yet.
+- No HTTP API is exposed yet.
+- Tool integrations are still skeletal.
+
+## End-to-end example
+
+```bash
+aegis run --workflow review --output json "Review this repository"
+```
+
+This returns a structured JSON report with the run ID, selected workflow, execution result, evaluation payload, and any error information.

pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aegis-agent"
+version = "0.1.0"
+description = "A modular, reliable AI agent engineering framework."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Giancarlo Vizhnay" }
+]
+dependencies = [
+  "pydantic>=2.10,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.14",
+  "pytest>=8.3",
+  "pytest-cov>=6.0",
+  "pytest-asyncio>=0.25",
+  "ruff>=0.9",
+]
+
+[project.scripts]
+aegis = "aegis.cli.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aegis"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q --strict-markers --disable-warnings"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+packages = ["aegis"]

src/aegis/__init__.py

@@ -0,0 +1,11 @@
+from aegis.core import Agent, AgentContext, AgentResult, Task, TaskStatus
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "AgentContext",
+    "AgentResult",
+    "Task",
+    "TaskStatus",
+]

src/aegis/agents/__init__.py

@@ -0,0 +1,10 @@
+from aegis.agents.evaluator import EvaluationReport, EvaluatorAgent
+from aegis.agents.planner import ExecutionPlan, PlannerAgent, PlanStep
+
+__all__ = [
+    "EvaluationReport",
+    "EvaluatorAgent",
+    "ExecutionPlan",
+    "PlanStep",
+    "PlannerAgent",
+]

src/aegis/agents/evaluator.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from aegis.core import Agent, AgentContext, AgentResult
+
+
+class EvaluationReport(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    passed: bool
+    score: int = Field(ge=0, le=100)
+    issues: tuple[str, ...] = ()
+    evaluated_agent: str = Field(min_length=1)
+
+
+class EvaluatorAgent(Agent):
+    name = "evaluator"
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        raw_result: Any = context.inputs.get("result")
+
+        if raw_result is None:
+            return AgentResult(
+                agent_name=self.name,
+                success=False,
+                errors=["Missing required input: result"],
+            )
+
+        try:
+            result = AgentResult.model_validate(raw_result)
+        except ValueError as exc:
+            return AgentResult(
+                agent_name=self.name,
+                success=False,
+                errors=[f"Invalid agent result: {exc}"],
+            )
+
+        issues: list[str] = []
+
+        if not result.success:
+            issues.append("Agent execution reported failure.")
+
+        if not result.output:
+            issues.append("Agent result contains no output.")
+
+        if result.errors:
+            issues.append("Agent result contains errors.")
+
+        score = max(0, 100 - (25 * len(issues)))
+        passed = not issues
+
+        report = EvaluationReport(
+            passed=passed,
+            score=score,
+            issues=tuple(issues),
+            evaluated_agent=result.agent_name,
+        )
+
+        return AgentResult(
+            agent_name=self.name,
+            success=True,
+            output=report.model_dump(),
+        )

src/aegis/agents/planner.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from aegis.core import Agent, AgentContext, AgentResult
+
+
+class PlanStep(BaseModel):
+    id: int = Field(ge=1)
+    action: str = Field(min_length=1)
+    expected_output: str = Field(min_length=1)
+
+
+class ExecutionPlan(BaseModel):
+    task_name: str = Field(min_length=1)
+    steps: tuple[PlanStep, ...] = Field(min_length=1)
+
+
+class PlannerAgent(Agent):
+    name = "planner"
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        task = context.task
+
+        plan = ExecutionPlan(
+            task_name=task.name,
+            steps=(
+                PlanStep(
+                    id=1,
+                    action="Analyze the task requirements.",
+                    expected_output="A clear statement of scope and constraints.",
+                ),
+                PlanStep(
+                    id=2,
+                    action="Select the required tools and agents.",
+                    expected_output="A bounded execution strategy.",
+                ),
+                PlanStep(
+                    id=3,
+                    action="Execute and validate the work.",
+                    expected_output="A verified result or explicit failure state.",
+                ),
+            ),
+        )
+
+        return AgentResult(
+            agent_name=self.name,
+            success=True,
+            output=plan.model_dump(),
+        )

src/aegis/cli/__init__.py

@@ -0,0 +1,3 @@
+from aegis.cli.app import main
+
+__all__ = ["main"]

src/aegis/cli/app.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from aegis.cli.commands.run import add_arguments, run_command
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="aegis", description="Aegis CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    run_parser = subparsers.add_parser("run", help="Run a task through Aegis")
+    add_arguments(run_parser)
+    run_parser.set_defaults(command_handler=run_command)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+
+    try:
+        args = parser.parse_args(list(argv) if argv is not None else None)
+    except SystemExit as exc:
+        return int(exc.code) if isinstance(exc.code, int) else 1
+
+    command_handler = getattr(args, "command_handler", None)
+    if command_handler is None:
+        parser.print_help()
+        return 0
+
+    return int(command_handler(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/aegis/cli/commands/run.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import traceback
+from typing import Any
+from uuid import uuid4
+
+from aegis.cli.output import format_run_json, format_run_text
+from aegis.runtime import (
+    AegisRunError,
+    AegisRuntime,
+    EvaluationFailureError,
+    ExecutionFailureError,
+    InternalFailureError,
+    InvalidConfigurationError,
+    InvalidTaskError,
+    PolicyViolationError,
+    RunOutcome,
+    UnknownAgentError,
+    UnknownWorkflowError,
+)
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "task",
+        help="Task to run through Aegis.",
+    )
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument(
+        "--agent",
+        help="Run a specific registered agent.",
+    )
+    group.add_argument(
+        "--workflow",
+        help="Run a named workflow.",
+    )
+    parser.add_argument(
+        "--output",
+        choices=("text", "json"),
+        default="text",
+        help="Output format.",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=_positive_int,
+        default=None,
+        help="Maximum execution steps for the run.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show debug details for unexpected failures.",
+    )
+
+
+def run_command(args: argparse.Namespace, runtime: Any | None = None) -> int:
+    runner: Any = runtime or AegisRuntime()
+    run_uuid = uuid4()
+    run_id = f"run_{run_uuid.hex}"
+    requested_agent = _normalize_optional(str(args.agent)) if getattr(args, "agent", None) else None
+    requested_workflow = (
+        _normalize_optional(str(args.workflow)) if getattr(args, "workflow", None) else None
+    )
+    max_steps = int(args.max_steps) if getattr(args, "max_steps", None) is not None else None
+
+    try:
+        outcome = runner.run(
+            task=str(args.task),
+            agent_name=requested_agent,
+            workflow_name=requested_workflow,
+            max_steps=max_steps,
+            run_id=run_uuid,
+        )
+    except (
+        InvalidTaskError,
+        InvalidConfigurationError,
+        UnknownAgentError,
+        UnknownWorkflowError,
+    ) as exc:
+        return _emit_failure(
+            run_id=run_id,
+            status="failed",
+            agent=requested_agent,
+            workflow=requested_workflow,
+            message=str(exc),
+            exit_code=exc.exit_code,
+            output_format=args.output,
+            verbose=args.verbose,
+        )
+    except PolicyViolationError as exc:
+        return _emit_failure(
+            run_id=run_id,
+            status="failed",
+            agent=requested_agent,
+            workflow=requested_workflow,
+            message=str(exc),
+            exit_code=exc.exit_code,
+            output_format=args.output,
+            verbose=args.verbose,
+        )
+    except (ExecutionFailureError, EvaluationFailureError) as exc:
+        return _emit_failure(
+            run_id=run_id,
+            status="failed",
+            agent=requested_agent,
+            workflow=requested_workflow,
+            message=str(exc),
+            exit_code=exc.exit_code,
+            output_format=args.output,
+            verbose=args.verbose,
+        )
+    except AegisRunError as exc:
+        return _emit_failure(
+            run_id=run_id,
+            status="failed",
+            agent=requested_agent,
+            workflow=requested_workflow,
+            message=str(exc),
+            exit_code=exc.exit_code,
+            output_format=args.output,
+            verbose=args.verbose,
+        )
+    except Exception as exc:  # pragma: no cover - defensive boundary
+        error = InternalFailureError("Unexpected internal error.")
+        return _emit_failure(
+            run_id=run_id,
+            status="failed",
+            agent=requested_agent,
+            workflow=requested_workflow,
+            message=str(error),
+            exit_code=error.exit_code,
+            output_format=args.output,
+            verbose=args.verbose,
+            exc=exc,
+        )
+
+    if args.output == "json":
+        print(format_run_json(outcome))
+    else:
+        print(format_run_text(outcome))
+
+    return 0
+
+
+
+
+def _emit_failure(
+    *,
+    run_id: str,
+    status: str,
+    agent: str | None,
+    workflow: str | None,
+    message: str,
+    exit_code: int,
+    output_format: str,
+    verbose: bool,
+    exc: BaseException | None = None,
+) -> int:
+    outcome = RunOutcome(
+        run_id=run_id,
+        status=status,
+        agent=agent,
+        workflow=workflow,
+        result=None,
+        evaluation=None,
+        error=message,
+    )
+
+    if output_format == "json":
+        print(format_run_json(outcome))
+    else:
+        _emit_error(message, verbose, exc)
+
+    return exit_code
+
+
+def _emit_error(message: str, verbose: bool, exc: BaseException | None = None) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+    if verbose and exc is not None:
+        traceback.print_exception(exc, file=sys.stderr)
+
+
+def _normalize_optional(value: str) -> str:
+    return value.strip()
+
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return parsed

src/aegis/cli/output.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from aegis.runtime.runner import RunOutcome
+
+
+def format_run_text(outcome: RunOutcome) -> str:
+    lines: list[str] = [
+        f"Run ID: {outcome.run_id}",
+        f"Status: {outcome.status}",
+    ]
+
+    if outcome.agent is not None:
+        lines.append(f"Agent: {outcome.agent}")
+
+    if outcome.workflow is not None:
+        lines.append(f"Workflow: {outcome.workflow}")
+
+    if outcome.result is not None:
+        lines.append("Result:")
+        lines.append(_format_payload(outcome.result))
+    else:
+        lines.append("Result:")
+        lines.append("<none>")
+
+    if outcome.evaluation is not None:
+        lines.append("Evaluation:")
+        lines.append(_format_payload(outcome.evaluation))
+
+    if outcome.error is not None:
+        lines.append("Error:")
+        lines.append(outcome.error)
+
+    return "\n".join(lines)
+
+
+def format_run_json(outcome: RunOutcome) -> str:
+    return json.dumps(outcome.model_dump(mode="json"), indent=2, sort_keys=True)
+
+
+def _format_payload(payload: Mapping[str, Any]) -> str:
+    return json.dumps(payload, indent=2, sort_keys=True)

src/aegis/core/__init__.py

@@ -0,0 +1,41 @@
+from aegis.core.conductor import Conductor
+from aegis.core.contracts import Agent, ModelProvider, Tool
+from aegis.core.memory import (
+    DuplicateMemoryKeyError,
+    MemoryEntry,
+    MemoryKeyNotFoundError,
+    MemoryStore,
+    MemoryStoreError,
+)
+from aegis.core.models import AgentContext, AgentResult, Task, TaskStatus
+from aegis.core.registry import (
+    AgentNotFoundError,
+    AgentRegistry,
+    AgentRegistryError,
+    DuplicateAgentError,
+)
+from aegis.core.tool_runner import ToolRunner
+from aegis.core.workflow import WorkflowEngine, WorkflowResult
+
+__all__ = [
+    "Agent",
+    "AgentContext",
+    "AgentNotFoundError",
+    "AgentRegistry",
+    "AgentRegistryError",
+    "AgentResult",
+    "Conductor",
+    "DuplicateAgentError",
+    "DuplicateMemoryKeyError",
+    "MemoryEntry",
+    "MemoryKeyNotFoundError",
+    "MemoryStore",
+    "MemoryStoreError",
+    "ModelProvider",
+    "Task",
+    "TaskStatus",
+    "Tool",
+    "ToolRunner",
+    "WorkflowEngine",
+    "WorkflowResult",
+]

src/aegis/core/conductor.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from aegis.core.models import AgentContext, AgentResult
+from aegis.core.registry import AgentRegistry
+
+
+class Conductor:
+    def __init__(self, registry: AgentRegistry) -> None:
+        self._registry = registry
+
+    async def execute(
+        self,
+        agent_name: str,
+        context: AgentContext,
+    ) -> AgentResult:
+        agent = self._registry.get(agent_name)
+        result = await agent.run(context)
+
+        if result.agent_name != agent.name:
+            raise ValueError("Agent result name does not match the registered agent name.")
+
+        return result

src/aegis/core/contracts.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Protocol, runtime_checkable
+
+from aegis.core.models import AgentContext, AgentResult
+
+
+class Agent(ABC):
+    name: str
+
+    @abstractmethod
+    async def run(self, context: AgentContext) -> AgentResult:
+        """Execute the agent against the supplied context."""
+        raise NotImplementedError
+
+
+@runtime_checkable
+class ModelProvider(Protocol):
+    async def generate(self, prompt: str) -> str:
+        """Generate model output for a prompt."""
+        ...
+
+
+@runtime_checkable
+class Tool(Protocol):
+    name: str
+
+    async def execute(self, **kwargs: object) -> object:
+        """Execute the tool with validated arguments."""
+        ...

src/aegis/core/memory.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MemoryStoreError(Exception):
+    """Base error for memory store operations."""
+
+
+class DuplicateMemoryKeyError(MemoryStoreError):
+    """Raised when adding a key that already exists."""
+
+
+class MemoryKeyNotFoundError(MemoryStoreError):
+    """Raised when a requested key does not exist."""
+
+
+class MemoryEntry(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    key: str = Field(min_length=1)
+    value: Any
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class MemoryStore:
+    def __init__(self, entries: Iterable[MemoryEntry] = ()) -> None:
+        self._entries: dict[str, MemoryEntry] = {}
+
+        for entry in entries:
+            self.add(entry)
+
+    def add(self, entry: MemoryEntry) -> None:
+        key = self._normalize_key(entry.key)
+
+        if key in self._entries:
+            raise DuplicateMemoryKeyError(f"Memory key already exists: {key}")
+
+        normalized_entry = entry.model_copy(update={"key": key})
+        self._entries[key] = normalized_entry
+
+    def set(self, entry: MemoryEntry) -> None:
+        key = self._normalize_key(entry.key)
+        normalized_entry = entry.model_copy(update={"key": key})
+        self._entries[key] = normalized_entry
+
+    def get(self, key: str) -> MemoryEntry:
+        normalized_key = self._normalize_key(key)
+
+        try:
+            return self._entries[normalized_key]
+        except KeyError as exc:
+            raise MemoryKeyNotFoundError(f"Memory key not found: {normalized_key}") from exc
+
+    def delete(self, key: str) -> None:
+        normalized_key = self._normalize_key(key)
+
+        if normalized_key not in self._entries:
+            raise MemoryKeyNotFoundError(f"Memory key not found: {normalized_key}")
+
+        del self._entries[normalized_key]
+
+    def contains(self, key: str) -> bool:
+        return self._normalize_key(key) in self._entries
+
+    def keys(self) -> tuple[str, ...]:
+        return tuple(sorted(self._entries))
+
+    def clear(self) -> None:
+        self._entries.clear()
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    @staticmethod
+    def _normalize_key(key: str) -> str:
+        normalized = key.strip()
+
+        if not normalized:
+            raise ValueError("Memory key must not be empty.")
+
+        return normalized

src/aegis/core/models.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TaskStatus(StrEnum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+
+
+class Task(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    name: str = Field(min_length=1, max_length=120)
+    description: str = Field(min_length=1)
+    status: TaskStatus = TaskStatus.PENDING
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentContext(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    run_id: UUID = Field(default_factory=uuid4)
+    task: Task
+    inputs: dict[str, Any] = Field(default_factory=dict)
+    state: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    agent_name: str = Field(min_length=1)
+    success: bool
+    output: dict[str, Any] = Field(default_factory=dict)
+    errors: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)

src/aegis/core/policies.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApprovalMode(StrEnum):
+    NEVER = "never"
+    HIGH_RISK_ONLY = "high_risk_only"
+    ALWAYS = "always"
+
+
+class ResponsePolicy(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    max_input_chars: int = Field(default=20_000, ge=1)
+    max_output_tokens: int = Field(default=600, ge=1)
+
+    answer_first: bool = True
+    include_reasoning: bool = False
+    include_sources: bool = True
+    include_warnings: bool = True
+    allow_repetition: bool = False
+
+
+class ExecutionPolicy(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    max_steps: int = Field(default=8, ge=1)
+    timeout_seconds: float = Field(default=60.0, gt=0)
+    retry_limit: int = Field(default=1, ge=0)
+    max_tool_calls: int = Field(default=6, ge=0)
+    max_parallel_tasks: int = Field(default=3, ge=1)
+
+    approval_mode: ApprovalMode = ApprovalMode.HIGH_RISK_ONLY
+    allow_network: bool = False
+    allow_file_writes: bool = False
+    allow_shell: bool = False
+
+
+class AgentPolicy(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    response: ResponsePolicy = Field(default_factory=ResponsePolicy)
+    execution: ExecutionPolicy = Field(default_factory=ExecutionPolicy)

src/aegis/core/registry.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from aegis.core.contracts import Agent
+
+
+class AgentRegistryError(Exception):
+    """Base registry error."""
+
+
+class DuplicateAgentError(AgentRegistryError):
+    """Raised when an agent name is already registered."""
+
+
+class AgentNotFoundError(AgentRegistryError):
+    """Raised when an agent cannot be found."""
+
+
+class AgentRegistry:
+    def __init__(self, agents: Iterable[Agent] | None = None) -> None:
+        self._agents: dict[str, Agent] = {}
+
+        if agents is not None:
+            for agent in agents:
+                self.register(agent)
+
+    def register(self, agent: Agent) -> None:
+        name = agent.name.strip()
+
+        if not name:
+            raise ValueError("Agent name cannot be empty.")
+
+        if name in self._agents:
+            raise DuplicateAgentError(f"Agent already registered: {name}")
+
+        self._agents[name] = agent
+
+    def get(self, name: str) -> Agent:
+        normalized_name = name.strip()
+
+        try:
+            return self._agents[normalized_name]
+        except KeyError as exc:
+            raise AgentNotFoundError(f"Agent not found: {normalized_name}") from exc
+
+    def contains(self, name: str) -> bool:
+        return name.strip() in self._agents
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(self._agents))
+
+    def __len__(self) -> int:
+        return len(self._agents)

src/aegis/core/tool_registry.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from aegis.core.contracts import Tool
+
+
+class ToolRegistryError(Exception):
+    """Base tool registry error."""
+
+
+class DuplicateToolError(ToolRegistryError):
+    """Raised when a tool name is already registered."""
+
+
+class ToolNotFoundError(ToolRegistryError):
+    """Raised when a tool cannot be found."""
+
+
+class ToolRegistry:
+    def __init__(self, tools: Iterable[Tool] | None = None) -> None:
+        self._tools: dict[str, Tool] = {}
+
+        if tools is not None:
+            for tool in tools:
+                self.register(tool)
+
+    def register(self, tool: Tool) -> None:
+        name = tool.name.strip()
+
+        if not name:
+            raise ValueError("Tool name cannot be empty.")
+
+        if name in self._tools:
+            raise DuplicateToolError(f"Tool already registered: {name}")
+
+        self._tools[name] = tool
+
+    def get(self, name: str) -> Tool:
+        normalized_name = name.strip()
+
+        try:
+            return self._tools[normalized_name]
+        except KeyError as exc:
+            raise ToolNotFoundError(f"Tool not found: {normalized_name}") from exc
+
+    def contains(self, name: str) -> bool:
+        return name.strip() in self._tools
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(self._tools))
+
+    def __len__(self) -> int:
+        return len(self._tools)

src/aegis/core/tool_runner.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from aegis.core.tool_registry import ToolRegistry
+
+
+class ToolRunner:
+    def __init__(self, registry: ToolRegistry) -> None:
+        self._registry = registry
+
+    async def execute(
+        self,
+        tool_name: str,
+        **kwargs: object,
+    ) -> object:
+        tool = self._registry.get(tool_name)
+        return await tool.execute(**kwargs)

src/aegis/core/workflow.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from aegis.core.conductor import Conductor
+from aegis.core.memory import MemoryEntry, MemoryStore
+from aegis.core.models import AgentContext, AgentResult
+
+
+class WorkflowResult(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    plan: AgentResult
+    execution: AgentResult
+    evaluation: AgentResult
+    memory_keys: tuple[str, ...] = Field(default_factory=tuple)
+
+
+class WorkflowEngine:
+    def __init__(
+        self,
+        conductor: Conductor,
+        memory: MemoryStore,
+    ) -> None:
+        self._conductor = conductor
+        self._memory = memory
+
+    async def run(
+        self,
+        context: AgentContext,
+        target_agent: str,
+    ) -> WorkflowResult:
+        plan_result = await self._conductor.execute("planner", context)
+        self._store_result(context, "plan", plan_result)
+
+        if not plan_result.success:
+            raise RuntimeError("Planner failed to produce a valid plan.")
+
+        execution_result = await self._conductor.execute(
+            target_agent,
+            context,
+        )
+        self._store_result(context, "execution", execution_result)
+
+        evaluation_context = context.model_copy(
+            deep=True,
+            update={
+                "inputs": {
+                    **context.inputs,
+                    "result": execution_result.model_dump(),
+                }
+            },
+        )
+
+        evaluation_result = await self._conductor.execute(
+            "evaluator",
+            evaluation_context,
+        )
+        self._store_result(context, "evaluation", evaluation_result)
+
+        return WorkflowResult(
+            plan=plan_result,
+            execution=execution_result,
+            evaluation=evaluation_result,
+            memory_keys=self._workflow_memory_keys(context),
+        )
+
+    def _store_result(
+        self,
+        context: AgentContext,
+        stage: str,
+        result: AgentResult,
+    ) -> None:
+        key = self._memory_key(context, stage)
+
+        self._memory.set(
+            MemoryEntry(
+                key=key,
+                value=result.model_dump(),
+                metadata={
+                    "run_id": str(context.run_id),
+                    "stage": stage,
+                    "agent_name": result.agent_name,
+                },
+            )
+        )
+
+    def _workflow_memory_keys(
+        self,
+        context: AgentContext,
+    ) -> tuple[str, ...]:
+        prefix = f"workflow.{context.run_id}."
+
+        return tuple(key for key in self._memory.keys() if key.startswith(prefix))  # noqa: SIM118
+
+    @staticmethod
+    def _memory_key(
+        context: AgentContext,
+        stage: str,
+    ) -> str:
+        return f"workflow.{context.run_id}.{stage}"

src/aegis/runtime/__init__.py

@@ -0,0 +1,27 @@
+from aegis.runtime.errors import (
+    AegisRunError,
+    EvaluationFailureError,
+    ExecutionFailureError,
+    InternalFailureError,
+    InvalidConfigurationError,
+    InvalidTaskError,
+    PolicyViolationError,
+    UnknownAgentError,
+    UnknownWorkflowError,
+)
+from aegis.runtime.runner import AegisRuntime, RunOutcome, WorkflowDefinition
+
+__all__ = [
+    "AegisRunError",
+    "AegisRuntime",
+    "EvaluationFailureError",
+    "ExecutionFailureError",
+    "InternalFailureError",
+    "InvalidConfigurationError",
+    "InvalidTaskError",
+    "PolicyViolationError",
+    "RunOutcome",
+    "UnknownAgentError",
+    "UnknownWorkflowError",
+    "WorkflowDefinition",
+]

src/aegis/runtime/errors.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+
+class AegisRunError(Exception):
+    exit_code = 1
+
+
+class InvalidTaskError(AegisRunError):
+    exit_code = 2
+
+
+class InvalidConfigurationError(AegisRunError):
+    exit_code = 3
+
+
+class UnknownAgentError(InvalidConfigurationError):
+    pass
+
+
+class UnknownWorkflowError(InvalidConfigurationError):
+    pass
+
+
+class PolicyViolationError(AegisRunError):
+    exit_code = 4
+
+
+class ExecutionFailureError(AegisRunError):
+    exit_code = 5
+
+
+class EvaluationFailureError(AegisRunError):
+    exit_code = 6
+
+
+class InternalFailureError(AegisRunError):
+    exit_code = 1