Personal AI, On Personal Devices
Python
"""ABC for agent implementations.
Adapted from IPW's ``BaseAgent`` at ``src/agents/base.py``.
Provides ``BaseAgent`` with concrete helper methods for event emission,
message building, and generation, plus ``ToolUsingAgent`` intermediate
base for agents that accept tools.
"""
from __future__ import annotations
import re
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional
from openjarvis.core.config import load_config
from openjarvis.core.events import EventBus, EventType
from openjarvis.core.types import Conversation, Message, Role, ToolResult
from openjarvis.engine._stubs import InferenceEngine
_ALLOWED_ENGINE_OPTION_KEYS = frozenset({"num_ctx", "num_gpu"})
@dataclass(slots=True)
class AgentContext:
"""Runtime context handed to an agent on each invocation."""
conversation: Conversation = field(default_factory=Conversation)
tools: List[str] = field(default_factory=list)
memory_results: List[Any] = field(default_factory=list)
metadata: Dict[str, Any] = field(default_factory=dict)
@dataclass(slots=True)
class AgentResult:
"""Result returned after an agent completes a run."""
content: str
tool_results: List[ToolResult] = field(default_factory=list)
turns: int = 0
metadata: Dict[str, Any] = field(default_factory=dict)
class BaseAgent(ABC):
"""Base class for all agent implementations.
Subclasses must be registered via
``@AgentRegistry.register("name")`` to become discoverable.
Provides concrete helper methods that eliminate boilerplate in
subclasses:
- :meth:`_emit_turn_start` / :meth:`_emit_turn_end` -- event bus
- :meth:`_build_messages` -- conversation + system prompt assembly
- :meth:`_generate` -- delegates to engine with stored defaults
- :meth:`_max_turns_result` -- standard max-turns-exceeded result
- :meth:`_strip_think_tags` -- remove ``<think>`` blocks
"""
agent_id: str
accepts_tools: bool = False
# Plain conversational agents may opt into the managed runtime's generic
# function-calling loop. Specialized agents keep their own execution
# class even when process-wide MCP tools are available.
supports_managed_tool_fallback: bool = False
required_capabilities: tuple[str, ...] = ()
uses_direct_operations: bool = False
def __init__(
self,
engine: InferenceEngine,
model: str,
*,
bus: Optional[EventBus] = None,
temperature: Optional[float] = None,
max_tokens: Optional[int] = None,
prompt_builder: Optional[Any] = None,
engine_options: Optional[Dict[str, Any]] = None,
capability_policy: Optional[Any] = None,
rate_limiter: Optional[Any] = None,
agent_id: Optional[str] = None,
) -> None:
self._engine = engine
self._model = model
self._bus = bus
self._prompt_builder = prompt_builder
self._engine_options: Dict[str, Any] = dict(engine_options or {})
self._capability_policy = capability_policy
self._rate_limiter = rate_limiter
self._runtime_agent_id = agent_id or getattr(self, "agent_id", "")
# Three-tier resolution: explicit arg > config > class default > hardcoded
if temperature is not None and max_tokens is not None:
self._temperature = temperature
self._max_tokens = max_tokens
else:
try:
cfg = load_config()
self._temperature = (
temperature
if temperature is not None
else cfg.intelligence.temperature
)
self._max_tokens = (
max_tokens
if max_tokens is not None
else cfg.intelligence.max_tokens
)
except Exception:
self._temperature = (
temperature
if temperature is not None
else getattr(self, "_default_temperature", 0.7)
)
self._max_tokens = (
max_tokens
if max_tokens is not None
else getattr(self, "_default_max_tokens", 1024)
)
# ------------------------------------------------------------------
# Concrete helpers
# ------------------------------------------------------------------
def _execution_denied_result(
self,
required_capabilities: Optional[List[str]] = None,
*,
operation: str = "agent_run",
) -> Optional[AgentResult]:
"""Return a denial result when a direct agent operation is forbidden."""
required = list(
required_capabilities
if required_capabilities is not None
else self.required_capabilities
)
if not required:
return None
result = self._authorize_direct_operation(required, operation=operation)
if result.success:
return None
return AgentResult(
content=result.content,
tool_results=[result],
metadata={"error": True, "security_denied": True},
)
def _authorize_direct_operation(
self,
required_capabilities: List[str],
*,
operation: str,
) -> ToolResult:
"""Authorize a non-BaseTool operation using this runtime identity."""
from openjarvis.security.runtime import authorize_secured_operation
return authorize_secured_operation(
operation,
required_capabilities,
bus=self._bus,
capability_policy=self._capability_policy,
rate_limiter=self._rate_limiter,
agent_id=self._runtime_agent_id,
)
def _emit_turn_start(self, input: str) -> None:
"""Publish ``AGENT_TURN_START`` if an event bus is available."""
if self._bus:
self._bus.publish(
EventType.AGENT_TURN_START,
{"agent": self.agent_id, "input": input},
)
def _emit_turn_end(self, **data: Any) -> None:
"""Publish ``AGENT_TURN_END`` if an event bus is available."""
if self._bus:
payload: Dict[str, Any] = {"agent": self.agent_id}
payload.update(data)
self._bus.publish(EventType.AGENT_TURN_END, payload)
def _apply_persona(self, system_prompt: Optional[str]) -> Optional[str]:
"""Append SOUL/MEMORY/USER persona to a self-assembled system prompt.
Agents like ``monitor_operative`` / ``operative`` build their own
system prompt and bypass ``_build_messages`` (and thus the prompt
builder). This lets them honor the same persona files as one-shot
``jarvis ask`` (#376) by *appending* persona to — never replacing —
their specialized instructions. No-op when no ``prompt_builder`` is
wired or no persona files exist.
"""
if self._prompt_builder is None:
return system_prompt
persona = self._prompt_builder.persona_sections()
if not persona:
return system_prompt
return f"{system_prompt}\n\n{persona}" if system_prompt else persona
def _build_messages(
self,
input: str,
context: Optional[AgentContext] = None,
*,
system_prompt: Optional[str] = None,
) -> list[Message]:
"""Assemble the message list for a generate call.
Optionally prepends a system prompt, then appends any context
conversation messages, and finally the user input.
"""
messages: list[Message] = []
context_messages = (
list(context.conversation.messages) if context is not None else []
)
# Check if the context already supplies a system message
_context_has_system = (
context
and context.conversation.messages
and any(m.role == Role.SYSTEM for m in context.conversation.messages)
)
if self._prompt_builder is not None:
effective_system_prompt = self._prompt_builder.build()
elif system_prompt:
effective_system_prompt = system_prompt
elif _context_has_system:
effective_system_prompt = None
else:
# Fall back to the config-level default (grounds local models)
try:
cfg = load_config()
effective_system_prompt = cfg.agent.default_system_prompt or None
except Exception:
effective_system_prompt = None
# Fold ALL in-context system messages (both auto-captured memory
# context and caller-supplied system messages) into one leading system
# message. Do this even when there is no independently-built prompt:
# Qwen-family chat templates reject a system message after the first
# slot or more than one system message. Empty system messages must be
# removed too, otherwise they can leave a second system entry behind.
identity_already_applied = any(
message.role == Role.SYSTEM
and message.metadata.get("openjarvis_identity_prompt")
for message in context_messages
)
system_parts = []
if effective_system_prompt and not identity_already_applied:
system_parts.append(effective_system_prompt)
system_parts.extend(
message.text
for message in context_messages
if message.role == Role.SYSTEM and message.text
)
context_messages = [
message for message in context_messages if message.role != Role.SYSTEM
]
if system_parts:
messages.append(
Message(role=Role.SYSTEM, content="\n\n".join(system_parts))
)
if context_messages:
messages.extend(context_messages)
messages.append(Message(role=Role.USER, content=input))
return messages
def _generate(self, messages: list[Message], **extra_kwargs: Any) -> dict:
"""Call ``engine.generate()`` with stored defaults.
Extra kwargs (e.g. ``tools``) are forwarded to the engine.
Publishes INFERENCE_START/END events on the bus when the engine
does not publish its own (i.e. non-instrumented engines).
"""
if self._bus and not getattr(self._engine, "_publishes_events", False):
engine_id = getattr(self._engine, "engine_id", "")
self._bus.publish(
EventType.INFERENCE_START,
{"model": self._model, "engine": engine_id},
)
# Stored engine options originate in CLI/runtime configuration and are
# intentionally allowlisted. Per-call kwargs originate in the agent
# implementation itself (for example ``tools`` or ``response_format``)
# and must reach the engine adapter unchanged. Filtering the merged
# mapping silently stripped function-calling tools from every agent.
gen_kwargs = {
key: value
for key, value in self._engine_options.items()
if key in _ALLOWED_ENGINE_OPTION_KEYS
}
gen_kwargs.update(extra_kwargs)
result = self._engine.generate(
messages,
model=self._model,
temperature=self._temperature,
max_tokens=self._max_tokens,
**gen_kwargs,
)
if self._bus and not getattr(self._engine, "_publishes_events", False):
usage = result.get("usage", {})
self._bus.publish(
EventType.INFERENCE_END,
{
"model": self._model,
"usage": usage,
"content": result.get("content", ""),
"tool_calls": result.get("tool_calls", []),
"finish_reason": result.get("finish_reason", ""),
},
)
return result
def _max_turns_result(
self,
tool_results: list[ToolResult],
turns: int,
content: str = "",
*,
metadata: Optional[Dict[str, Any]] = None,
) -> AgentResult:
"""Build the standard result for when ``max_turns`` is exceeded."""
self._emit_turn_end(turns=turns, max_turns_exceeded=True)
md: Dict[str, Any] = {"max_turns_exceeded": True}
if metadata:
md.update(metadata)
return AgentResult(
content=content or "Maximum turns reached without a final answer.",
tool_results=tool_results,
turns=turns,
metadata=md,
)
def _check_continuation(
self,
result: dict,
messages: list,
*,
max_continuations: int = 2,
) -> str:
"""Re-prompt on ``finish_reason == "length"`` to get complete output.
Returns the concatenated content after up to *max_continuations*
follow-up generate calls.
"""
content = result.get("content", "")
finish_reason = result.get("finish_reason", "")
for _ in range(max_continuations):
if finish_reason != "length":
break
# Append what we have so far and ask the model to continue
from openjarvis.core.types import Message, Role
messages.append(Message(role=Role.ASSISTANT, content=content))
messages.append(
Message(
role=Role.USER,
content="Continue from where you left off.",
),
)
cont = self._generate(messages)
continuation = cont.get("content", "")
content += continuation
finish_reason = cont.get("finish_reason", "")
return content
@staticmethod
def _strip_think_tags(text: str) -> str:
"""Remove ``<think>...</think>`` blocks from model output.
Handles both ``<think>...</think>`` and the common distilled-model
pattern where the opening ``<think>`` is absent and the response
begins directly with reasoning text followed by ``</think>``.
"""
# Full <think>...</think> blocks
text = re.sub(
r"<think>.*?</think>\s*",
"",
text,
flags=re.DOTALL | re.IGNORECASE,
)
# Leading content before a bare </think> (no opening tag)
text = re.sub(r"^.*?</think>\s*", "", text, flags=re.DOTALL | re.IGNORECASE)
return text.strip()
@abstractmethod
def run(
self,
input: str,
context: Optional[AgentContext] = None,
**kwargs: Any,
) -> AgentResult:
"""Execute the agent on *input* and return an ``AgentResult``."""
class ToolUsingAgent(BaseAgent):
"""Intermediate base for agents that accept and use tools.
Sets ``accepts_tools = True`` for CLI/SDK introspection, and
initialises a :class:`ToolExecutor` from the provided tools.
"""
accepts_tools: bool = True
def __init__(
self,
engine: InferenceEngine,
model: str,
*,
tools: Optional[List["BaseTool"]] = None, # noqa: F821
bus: Optional[EventBus] = None,
max_turns: Optional[int] = None,
temperature: Optional[float] = None,
max_tokens: Optional[int] = None,
loop_guard_config: Optional[Any] = None,
capability_policy: Optional[Any] = None,
agent_id: Optional[str] = None,
rate_limiter: Optional[Any] = None,
interactive: bool = False,
confirm_callback: Optional[Any] = None,
skill_few_shot_examples: Optional[List[str]] = None,
prompt_builder: Optional[Any] = None,
) -> None:
super().__init__(
engine,
model,
bus=bus,
temperature=temperature,
max_tokens=max_tokens,
prompt_builder=prompt_builder,
capability_policy=capability_policy,
rate_limiter=rate_limiter,
agent_id=agent_id,
)
from openjarvis.tools._stubs import ToolExecutor
self._tools = tools or []
# Plan 2B I3: store optimized few-shot examples for agents to inject
# into their own system prompt templates as appropriate.
self._skill_few_shot_examples = list(skill_few_shot_examples or [])
_aid = agent_id or getattr(self, "agent_id", "")
self._executor = ToolExecutor(
self._tools,
bus=bus,
capability_policy=capability_policy,
agent_id=_aid,
interactive=interactive,
confirm_callback=confirm_callback,
rate_limiter=rate_limiter,
)
# Resolve max_turns: explicit arg > config > class default > 10
if max_turns is not None:
self._max_turns = max_turns
else:
try:
cfg = load_config()
self._max_turns = cfg.agent.max_turns
except Exception:
self._max_turns = getattr(self, "_default_max_turns", 10)
# Loop guard
self._loop_guard = None
try:
from openjarvis.agents.loop_guard import LoopGuard, LoopGuardConfig
if loop_guard_config is None:
loop_guard_config = LoopGuardConfig()
elif isinstance(loop_guard_config, dict):
loop_guard_config = LoopGuardConfig(**loop_guard_config)
if loop_guard_config.enabled:
self._loop_guard = LoopGuard(loop_guard_config, bus=bus)
except ImportError:
pass
def _emit_turn_start(self, input: str) -> None:
# A ToolUsingAgent instance may serve many unrelated requests. Start
# each run with fresh taint seeded only from the new user input;
# _build_messages below replaces this with full conversation history
# for agents that receive an AgentContext.
executor = getattr(self, "_executor", None)
if executor is not None:
executor.begin_session([input])
super()._emit_turn_start(input)
def _build_messages(
self,
input: str,
context: Optional[AgentContext] = None,
*,
system_prompt: Optional[str] = None,
) -> list[Message]:
messages = super()._build_messages(
input,
context,
system_prompt=system_prompt,
)
self._begin_tool_session_from_messages(messages)
return messages
def _begin_tool_session_from_messages(self, messages: List[Message]) -> None:
"""Seed executor taint from the complete conversation for this run."""
executor = getattr(self, "_executor", None)
if executor is not None:
executor.begin_session(
[message.text for message in messages if message.text]
)
__all__ = ["AgentContext", "AgentResult", "BaseAgent", "ToolUsingAgent"]