agent-scout-core 0.1.0__tar.gz

agent_scout_core-0.1.0/.gitignore

@@ -0,0 +1,81 @@
+# ===========================
+# Python
+# ===========================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+.venv/
+venv/
+.uv/
+.python-version
+
+# ===========================
+# Node.js / Next.js
+# ===========================
+node_modules/
+.next/
+out/
+.turbo/
+*.tsbuildinfo
+
+# ===========================
+# IDE / Editors
+# ===========================
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# ===========================
+# Environment / Secrets
+# ===========================
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# ===========================
+# Database
+# ===========================
+*.db
+*.sqlite
+*.sqlite3
+
+# ===========================
+# Logs
+# ===========================
+*.log
+logs/
+
+# ===========================
+# Testing / Coverage
+# ===========================
+.coverage
+htmlcov/
+.pytest_cache/
+coverage/
+.nyc_output/
+
+# ===========================
+# OS
+# ===========================
+.DS_Store
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# ===========================
+# Build artifacts
+# ===========================
+*.pyc
+*.pyo

agent_scout_core-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: agent-scout-core
+Version: 0.1.0
+Summary: Core engine for AgentScout — a multi-purpose AI assistant agent
+Project-URL: Homepage, https://github.com/ErnestHysa/agent-scout
+Project-URL: Repository, https://github.com/ErnestHysa/agent-scout
+Project-URL: Issues, https://github.com/ErnestHysa/agent-scout/issues
+Author: Ernest Hysa
+License-Expression: AGPL-3.0-or-later
+Keywords: agent,ai,assistant,llm,scout
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: apscheduler>=3.10
+Requires-Dist: duckduckgo-search>=7
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.28
+Requires-Dist: litellm>=1.55
+Requires-Dist: playwright>=1.49
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: pydantic>=2.10
+Requires-Dist: rich>=13
+Requires-Dist: uvicorn[standard]>=0.34
+Requires-Dist: websockets>=14
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6; extra == 'dev'
+Requires-Dist: pytest-mock>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-scout-core
+
+Core engine for AgentScout — a multi-purpose AI assistant agent.
+
+This package contains the ReAct reasoning loop, task management, LLM provider layer, plugin system, and all core logic.

agent_scout_core-0.1.0/README.md

@@ -0,0 +1,5 @@
+# agent-scout-core
+
+Core engine for AgentScout — a multi-purpose AI assistant agent.
+
+This package contains the ReAct reasoning loop, task management, LLM provider layer, plugin system, and all core logic.

agent_scout_core-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "agent-scout-core"
+version = "0.1.0"
+description = "Core engine for AgentScout — a multi-purpose AI assistant agent"
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.12"
+authors = [{ name = "Ernest Hysa" }]
+keywords = ["ai", "agent", "assistant", "scout", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "litellm>=1.55",
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.34",
+    "websockets>=14",
+    "aiosqlite>=0.20",
+    "pydantic>=2.10",
+    "pydantic-settings>=2.7",
+    "apscheduler>=3.10",
+    "playwright>=1.49",
+    "duckduckgo-search>=7",
+    "httpx>=0.28",
+    "rich>=13",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=6",
+    "pytest-mock>=3",
+    "ruff>=0.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/ErnestHysa/agent-scout"
+Repository = "https://github.com/ErnestHysa/agent-scout"
+Issues = "https://github.com/ErnestHysa/agent-scout/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_scout"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM"]
+
+[tool.coverage.run]
+source = ["agent_scout"]
+
+[tool.coverage.report]
+fail_under = 0
+show_missing = true

agent_scout_core-0.1.0/src/agent_scout/__init__.py

@@ -0,0 +1,3 @@
+"""AgentScout Core — A multi-purpose AI assistant agent engine."""
+
+__version__ = "0.1.0"

agent_scout_core-0.1.0/src/agent_scout/agent.py

@@ -0,0 +1,183 @@
+"""Main Agent class — orchestrates the ReAct loop and task lifecycle."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+from agent_scout.db.models import AutonomyLevel, Task, TaskStatus
+from agent_scout.events import Event, EventBus, EventType
+from agent_scout.react_loop import (
+    ActionType,
+    LLMProvider,
+    ReActConfig,
+    ReActLoop,
+    ToolExecutor,
+    UserInteraction,
+)
+
+
+class Agent:
+    """The main AgentScout agent.
+
+    Accepts natural language tasks, manages the ReAct loop lifecycle,
+    handles autonomy levels, and emits structured events for live UI updates.
+    """
+
+    def __init__(
+        self,
+        llm: LLMProvider,
+        tools: ToolExecutor,
+        event_bus: EventBus,
+        user: UserInteraction | None = None,
+        autonomy: AutonomyLevel = AutonomyLevel.FULL,
+        max_iterations: int = 25,
+    ) -> None:
+        self._llm = llm
+        self._tools = tools
+        self._bus = event_bus
+        self._user = user
+        self._autonomy = autonomy
+        self._max_iterations = max_iterations
+        self._active_loops: dict[str, ReActLoop] = {}
+        self._lock = asyncio.Lock()
+
+    @property
+    def autonomy(self) -> AutonomyLevel:
+        return self._autonomy
+
+    @autonomy.setter
+    def autonomy(self, level: AutonomyLevel) -> None:
+        self._autonomy = level
+
+    async def run_task(self, task: Task) -> Task:
+        """Execute a task through the ReAct loop.
+
+        Updates the task status through its lifecycle and returns
+        the completed/failed task.
+        """
+        task.status = TaskStatus.PLANNING
+        task.updated_at = time.time()
+        await self._bus.emit(
+            Event(
+                event_type=EventType.TASK_STATE_CHANGE,
+                data={"status": task.status.value, "description": task.description},
+                task_id=task.id,
+            )
+        )
+
+        await self._bus.emit(
+            Event(
+                event_type=EventType.AGENT_STARTED,
+                data={
+                    "task_id": task.id,
+                    "description": task.description,
+                    "autonomy": self._autonomy.value,
+                },
+                task_id=task.id,
+            )
+        )
+
+        # Determine effective user interaction based on autonomy
+        effective_user = self._get_effective_user(task)
+
+        config = ReActConfig(
+            max_iterations=self._max_iterations,
+            enable_reflection=True,
+        )
+
+        loop = ReActLoop(
+            llm=self._llm,
+            tools=self._tools,
+            event_bus=self._bus,
+            user=effective_user,
+            config=config,
+        )
+
+        async with self._lock:
+            self._active_loops[task.id] = loop
+
+        try:
+            task.status = TaskStatus.EXECUTING
+            task.updated_at = time.time()
+            await self._bus.emit(
+                Event(
+                    event_type=EventType.TASK_STATE_CHANGE,
+                    data={"status": task.status.value},
+                    task_id=task.id,
+                )
+            )
+
+            steps = await loop.run(task.description, task_id=task.id)
+
+            # Determine outcome from final step
+            if steps and steps[-1].action.action_type == ActionType.FINISH:
+                task.status = TaskStatus.COMPLETED
+                task.result = steps[-1].action.result or {"message": steps[-1].action.message}
+            else:
+                task.status = TaskStatus.FAILED
+                task.error = "Max iterations reached without completion"
+
+        except Exception as e:
+            task.status = TaskStatus.FAILED
+            task.error = str(e)
+            await self._bus.emit(
+                Event(
+                    event_type=EventType.ERROR,
+                    data={"error": str(e)},
+                    task_id=task.id,
+                )
+            )
+
+        finally:
+            async with self._lock:
+                self._active_loops.pop(task.id, None)
+
+            task.updated_at = time.time()
+            event_type = (
+                EventType.TASK_COMPLETED
+                if task.status == TaskStatus.COMPLETED
+                else EventType.TASK_FAILED
+            )
+            await self._bus.emit(
+                Event(
+                    event_type=event_type,
+                    data={
+                        "status": task.status.value,
+                        "result": task.result,
+                        "error": task.error,
+                    },
+                    task_id=task.id,
+                )
+            )
+
+            await self._bus.emit(
+                Event(
+                    event_type=EventType.AGENT_STOPPED,
+                    data={"task_id": task.id},
+                    task_id=task.id,
+                )
+            )
+
+        return task
+
+    def _get_effective_user(self, task: Task) -> UserInteraction | None:
+        """Determine the user interaction handler based on autonomy level."""
+        effective_autonomy = task.autonomy if task.autonomy else self._autonomy
+
+        if effective_autonomy == AutonomyLevel.FULL:
+            # In full autonomy, agent doesn't ask user (unless task explicitly requires it)
+            return None
+        # Semi and step_by_step both allow user interaction
+        return self._user
+
+    async def stop_task(self, task_id: str) -> None:
+        """Stop a running task."""
+        async with self._lock:
+            loop = self._active_loops.get(task_id)
+        if loop:
+            loop.stop()
+
+    @property
+    def active_task_ids(self) -> list[str]:
+        return list(self._active_loops.keys())

agent_scout_core-0.1.0/src/agent_scout/approval.py

@@ -0,0 +1,246 @@
+"""Action approval system for tasks requiring user confirmation."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from agent_scout.events import Event, EventBus, EventType
+
+
+class ApprovalStatus(StrEnum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    MODIFIED = "modified"
+    EXPIRED = "expired"
+
+
+@dataclass
+class ApprovalRequest:
+    """A request for user approval of an agent action."""
+
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    task_id: str = ""
+    action_type: str = ""  # e.g. "purchase", "book", "send_email"
+    description: str = ""
+    estimated_cost: float = 0.0
+    details: dict[str, Any] = field(default_factory=dict)
+    status: ApprovalStatus = ApprovalStatus.PENDING
+    response_message: str = ""
+    modifications: dict[str, Any] = field(default_factory=dict)
+    created_at: float = field(default_factory=time.time)
+    resolved_at: float = 0.0
+    timeout_seconds: float = 300.0  # 5 minutes default
+
+
+@dataclass
+class AuditEntry:
+    """Audit log entry for an approval decision."""
+
+    request_id: str
+    task_id: str
+    action_type: str
+    status: ApprovalStatus
+    timestamp: float = field(default_factory=time.time)
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+class ApprovalManager:
+    """Manages action approval requests and audit logging.
+
+    When the agent wants to perform a real-world action (booking,
+    purchasing, etc.), it creates an approval request. The user
+    can approve, reject, or modify the request.
+    """
+
+    def __init__(self, event_bus: EventBus | None = None) -> None:
+        self._bus = event_bus
+        self._pending: dict[str, ApprovalRequest] = {}
+        self._audit_log: list[AuditEntry] = []
+
+    async def request_approval(
+        self,
+        task_id: str,
+        action_type: str,
+        description: str,
+        estimated_cost: float = 0.0,
+        details: dict[str, Any] | None = None,
+        timeout_seconds: float = 300.0,
+    ) -> ApprovalRequest:
+        """Create a new approval request and emit event."""
+        request = ApprovalRequest(
+            task_id=task_id,
+            action_type=action_type,
+            description=description,
+            estimated_cost=estimated_cost,
+            details=details or {},
+            timeout_seconds=timeout_seconds,
+        )
+
+        self._pending[request.id] = request
+
+        if self._bus:
+            await self._bus.emit(
+                Event(
+                    event_type=EventType.USER_APPROVAL_REQUESTED,
+                    data={
+                        "request_id": request.id,
+                        "action_type": action_type,
+                        "description": description,
+                        "estimated_cost": estimated_cost,
+                        "details": details or {},
+                    },
+                    task_id=task_id,
+                )
+            )
+
+        return request
+
+    async def approve(
+        self,
+        request_id: str,
+        message: str = "",
+    ) -> ApprovalRequest | None:
+        """Approve a pending request."""
+        request = self._pending.get(request_id)
+        if not request or request.status != ApprovalStatus.PENDING:
+            return None
+
+        request.status = ApprovalStatus.APPROVED
+        request.response_message = message
+        request.resolved_at = time.time()
+
+        self._log_audit(request)
+        del self._pending[request_id]
+
+        if self._bus:
+            await self._bus.emit(
+                Event(
+                    event_type=EventType.USER_APPROVAL_RECEIVED,
+                    data={
+                        "request_id": request_id,
+                        "status": ApprovalStatus.APPROVED.value,
+                        "message": message,
+                    },
+                    task_id=request.task_id,
+                )
+            )
+
+        return request
+
+    async def reject(
+        self,
+        request_id: str,
+        message: str = "",
+    ) -> ApprovalRequest | None:
+        """Reject a pending request."""
+        request = self._pending.get(request_id)
+        if not request or request.status != ApprovalStatus.PENDING:
+            return None
+
+        request.status = ApprovalStatus.REJECTED
+        request.response_message = message
+        request.resolved_at = time.time()
+
+        self._log_audit(request)
+        del self._pending[request_id]
+
+        if self._bus:
+            await self._bus.emit(
+                Event(
+                    event_type=EventType.USER_APPROVAL_RECEIVED,
+                    data={
+                        "request_id": request_id,
+                        "status": ApprovalStatus.REJECTED.value,
+                        "message": message,
+                    },
+                    task_id=request.task_id,
+                )
+            )
+
+        return request
+
+    async def modify(
+        self,
+        request_id: str,
+        modifications: dict[str, Any],
+        message: str = "",
+    ) -> ApprovalRequest | None:
+        """Approve with modifications."""
+        request = self._pending.get(request_id)
+        if not request or request.status != ApprovalStatus.PENDING:
+            return None
+
+        request.status = ApprovalStatus.MODIFIED
+        request.modifications = modifications
+        request.response_message = message
+        request.resolved_at = time.time()
+
+        self._log_audit(request)
+        del self._pending[request_id]
+
+        if self._bus:
+            await self._bus.emit(
+                Event(
+                    event_type=EventType.USER_APPROVAL_RECEIVED,
+                    data={
+                        "request_id": request_id,
+                        "status": ApprovalStatus.MODIFIED.value,
+                        "modifications": modifications,
+                        "message": message,
+                    },
+                    task_id=request.task_id,
+                )
+            )
+
+        return request
+
+    def check_expired(self) -> list[ApprovalRequest]:
+        """Check for and expire timed-out requests."""
+        now = time.time()
+        expired: list[ApprovalRequest] = []
+
+        for req_id, request in list(self._pending.items()):
+            if now - request.created_at > request.timeout_seconds:
+                request.status = ApprovalStatus.EXPIRED
+                request.resolved_at = now
+                self._log_audit(request)
+                del self._pending[req_id]
+                expired.append(request)
+
+        return expired
+
+    def get_pending(self) -> list[ApprovalRequest]:
+        """Get all pending approval requests."""
+        return list(self._pending.values())
+
+    def get_audit_log(
+        self,
+        task_id: str | None = None,
+        limit: int = 50,
+    ) -> list[AuditEntry]:
+        """Get audit log entries, optionally filtered by task."""
+        entries = self._audit_log
+        if task_id:
+            entries = [e for e in entries if e.task_id == task_id]
+        return entries[-limit:]
+
+    def _log_audit(self, request: ApprovalRequest) -> None:
+        """Add an entry to the audit log."""
+        entry = AuditEntry(
+            request_id=request.id,
+            task_id=request.task_id,
+            action_type=request.action_type,
+            status=request.status,
+            details={
+                "description": request.description,
+                "estimated_cost": request.estimated_cost,
+                "response": request.response_message,
+                "modifications": request.modifications,
+            },
+        )
+        self._audit_log.append(entry)