bare-agent 0.0.1__py3-none-any.whl

bare_agent/__init__.py

@@ -0,0 +1,47 @@
+"""bare-agent: a framework-free agent runtime. Own the loop, not the framework."""
+
+from __future__ import annotations
+
+from bare_agent.budget import Budget, BudgetState, BudgetStop
+from bare_agent.config import Settings, get_settings
+from bare_agent.events import AgentEvent, EventSink, emit
+from bare_agent.llm import LLMClient, LLMResponse, TokenSink, ToolCallRequest
+from bare_agent.logging import configure_logging, get_logger
+from bare_agent.loop import AgentLoop, AgentResult, CompletionClient
+from bare_agent.registry import (
+    Approver,
+    Permission,
+    Tool,
+    ToolCall,
+    ToolRegistry,
+    ToolResult,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "AgentEvent",
+    "AgentLoop",
+    "AgentResult",
+    "Approver",
+    "Budget",
+    "BudgetState",
+    "BudgetStop",
+    "CompletionClient",
+    "EventSink",
+    "LLMClient",
+    "LLMResponse",
+    "Permission",
+    "Settings",
+    "TokenSink",
+    "Tool",
+    "ToolCall",
+    "ToolCallRequest",
+    "ToolRegistry",
+    "ToolResult",
+    "__version__",
+    "configure_logging",
+    "emit",
+    "get_logger",
+    "get_settings",
+]

bare_agent/budget.py

@@ -0,0 +1,60 @@
+"""Three-axis budget and hard cost cap for a single agent run."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class BudgetStop(StrEnum):
+    TURNS = "max_turns"
+    TOKENS = "max_tokens"
+    WALLCLOCK = "max_wallclock_s"
+    COST = "max_cost_usd"
+
+
+@dataclass(frozen=True)
+class Budget:
+    max_turns: int
+    max_tokens: int
+    max_wallclock_s: float
+    max_cost_usd: float
+
+    @classmethod
+    def from_settings(cls, settings: object) -> Budget:
+        return cls(
+            max_turns=getattr(settings, "max_turns"),  # noqa: B009
+            max_tokens=getattr(settings, "max_tokens"),  # noqa: B009
+            max_wallclock_s=getattr(settings, "max_wallclock_s"),  # noqa: B009
+            max_cost_usd=getattr(settings, "max_cost_usd"),  # noqa: B009
+        )
+
+
+@dataclass
+class BudgetState:
+    budget: Budget
+    turns: int = 0
+    tokens: int = 0
+    cost_usd: float = 0.0
+    _start: float = field(default_factory=time.monotonic)
+
+    @property
+    def elapsed_s(self) -> float:
+        return time.monotonic() - self._start
+
+    def record_turn(self, *, tokens: int, cost_usd: float) -> None:
+        self.turns += 1
+        self.tokens += tokens
+        self.cost_usd += cost_usd
+
+    def exceeded(self) -> BudgetStop | None:
+        if self.turns >= self.budget.max_turns:
+            return BudgetStop.TURNS
+        if self.tokens >= self.budget.max_tokens:
+            return BudgetStop.TOKENS
+        if self.elapsed_s >= self.budget.max_wallclock_s:
+            return BudgetStop.WALLCLOCK
+        if self.cost_usd >= self.budget.max_cost_usd:
+            return BudgetStop.COST
+        return None

bare_agent/config.py

@@ -0,0 +1,73 @@
+"""Typed runtime configuration via Pydantic Settings."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="BARE_AGENT_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    model: str = Field(
+        default="ollama_chat/qwen3",
+        description=(
+            "LiteLLM model id. Local Ollama by default ($0, no key); any frontier id "
+            "(e.g. anthropic/claude-haiku-4-5) with its provider key exported."
+        ),
+    )
+    ollama_base_url: str = Field(
+        default="http://localhost:11434",
+        description="Ollama server URL, passed as api_base for ollama_chat/ models.",
+    )
+    fallback_models: list[str] = Field(
+        default_factory=list,
+        description='Ordered fallback model ids, e.g. ["anthropic/claude-haiku-4-5"].',
+    )
+    num_retries: int = Field(
+        default=2, ge=0, description="LiteLLM transient-failure retries before falling back."
+    )
+    temperature: float | None = Field(
+        default=None, description="Sampling temperature; None = provider default."
+    )
+    reasoning_effort: str | None = Field(
+        default=None,
+        description=(
+            "Passed to LiteLLM; on Ollama Qwen3.x 'disable' maps to think:false. "
+            "None = provider default."
+        ),
+    )
+    request_timeout_s: float = Field(default=120.0, gt=0, description="Per-LLM-call timeout.")
+
+    max_turns: int = Field(default=8, gt=0, description="Maximum LLM turns per run.")
+    max_tokens: int = Field(default=120_000, gt=0, description="Maximum cumulative tokens per run.")
+    max_wallclock_s: float = Field(default=180.0, gt=0, description="Maximum wall-clock per run.")
+    max_cost_usd: float = Field(default=0.50, gt=0, description="Hard cost cap per run in USD.")
+
+    use_queue: bool = Field(
+        default=False,
+        description="Run agents via a Redis job queue + worker pool (KEDA-scalable) instead of inline.",
+    )
+    redis_url: str = Field(
+        default="redis://localhost:6379/0",
+        description="Redis DSN for the run queue + event pub/sub.",
+    )
+    runs_queue_key: str = Field(
+        default="bare-agent:runs:pending",
+        description="Redis list the API LPUSHes runs to and KEDA scales the worker on.",
+    )
+
+    log_level: str = Field(default="INFO", description="structlog/stdlib level.")
+    log_json: bool = Field(default=False, description="Emit JSON logs.")
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()

bare_agent/events.py

@@ -0,0 +1,21 @@
+"""Optional event stream for surfacing agent progress to a UI."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AgentEvent:
+    kind: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+EventSink = Callable[[AgentEvent], Awaitable[None]]
+
+
+async def emit(sink: EventSink | None, kind: str, /, **data: Any) -> None:
+    if sink is not None:
+        await sink(AgentEvent(kind, data))

bare_agent/llm.py

@@ -0,0 +1,203 @@
+"""LiteLLM gateway wrapper returning normalized, cost-attributed responses."""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+import litellm
+from pydantic import BaseModel
+
+from bare_agent.config import Settings
+from bare_agent.logging import get_logger
+
+log = get_logger(__name__)
+
+_Structured = TypeVar("_Structured", bound=BaseModel)
+
+TokenSink = Callable[[str], Awaitable[None]]
+
+_LOCAL_PREFIXES: tuple[str, ...] = ("ollama/", "ollama_chat/")
+
+
+@dataclass(frozen=True)
+class ToolCallRequest:
+    id: str
+    name: str
+    arguments: str
+
+
+@dataclass(frozen=True)
+class LLMResponse:
+    content: str | None
+    tool_calls: list[ToolCallRequest]
+    prompt_tokens: int
+    completion_tokens: int
+    cost_usd: float
+
+
+class LLMClient:
+    def __init__(
+        self,
+        *,
+        model: str,
+        timeout_s: float,
+        temperature: float | None = None,
+        num_retries: int = 2,
+        fallbacks: list[str] | None = None,
+        reasoning_effort: str | None = None,
+        api_base: str | None = None,
+    ) -> None:
+        self._model: str = model
+        self._timeout: float = timeout_s
+        self._temperature: float | None = temperature
+        self._reasoning_effort: str | None = reasoning_effort
+        self._num_retries: int = num_retries
+        self._fallbacks: list[str] | None = fallbacks or None
+        self._api_base: str | None = api_base
+
+    @classmethod
+    def from_settings(cls, settings: Settings) -> LLMClient:
+        is_local: bool = settings.model.startswith(_LOCAL_PREFIXES)
+        return cls(
+            model=settings.model,
+            timeout_s=settings.request_timeout_s,
+            temperature=settings.temperature,
+            num_retries=settings.num_retries,
+            fallbacks=settings.fallback_models or None,
+            reasoning_effort=settings.reasoning_effort,
+            api_base=settings.ollama_base_url if is_local else None,
+        )
+
+    def _reliability_kwargs(self) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {"timeout": self._timeout, "num_retries": self._num_retries}
+        if self._fallbacks is not None:
+            kwargs["fallbacks"] = self._fallbacks
+        if self._api_base is not None:
+            kwargs["api_base"] = self._api_base
+        return kwargs
+
+    def _sampling_kwargs(self, *, structured: bool = False) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {}
+        if self._temperature is not None:
+            kwargs["temperature"] = self._temperature
+        if self._reasoning_effort is not None and not structured:
+            kwargs["reasoning_effort"] = self._reasoning_effort
+        return kwargs
+
+    def _prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        if "anthropic" not in self._model and "claude" not in self._model:
+            return messages
+        prepared: list[dict[str, Any]] = []
+        marked: bool = False
+        for message in messages:
+            content: Any = message.get("content")
+            if not marked and message.get("role") == "system" and isinstance(content, str):
+                prepared.append(
+                    {
+                        "role": "system",
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": content,
+                                "cache_control": {"type": "ephemeral"},
+                            }
+                        ],
+                    }
+                )
+                marked = True
+            else:
+                prepared.append(message)
+        return prepared
+
+    async def complete(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        *,
+        on_token: TokenSink | None = None,
+    ) -> LLMResponse:
+        messages = self._prepare_messages(messages)
+        if on_token is None:
+            response: Any = await litellm.acompletion(
+                model=self._model,
+                messages=messages,
+                tools=tools,
+                **self._reliability_kwargs(),
+                **self._sampling_kwargs(),
+            )
+        else:
+            response = await self._stream(messages, tools, on_token)
+        return self._normalize(response)
+
+    async def _stream(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None,
+        on_token: TokenSink,
+    ) -> Any:
+        chunks: list[Any] = []
+        stream: Any = await litellm.acompletion(
+            model=self._model,
+            messages=messages,
+            tools=tools,
+            **self._reliability_kwargs(),
+            stream=True,
+            stream_options={"include_usage": True},
+            **self._sampling_kwargs(),
+        )
+        try:
+            async for chunk in stream:
+                chunks.append(chunk)
+                choices: Any = getattr(chunk, "choices", None)
+                if not choices:
+                    continue
+                delta: str | None = getattr(choices[0].delta, "content", None)
+                if delta:
+                    await on_token(delta)
+            return litellm.stream_chunk_builder(chunks, messages=messages)
+        finally:
+            aclose: Any = getattr(stream, "aclose", None)
+            if aclose is not None:
+                with contextlib.suppress(Exception):
+                    await aclose()
+
+    def _normalize(self, response: Any) -> LLMResponse:
+        message: Any = response.choices[0].message
+        tool_calls: list[ToolCallRequest] = [
+            ToolCallRequest(id=call.id, name=call.function.name, arguments=call.function.arguments)
+            for call in (message.tool_calls or [])
+        ]
+        usage: Any = response.usage
+        prompt_tokens: int = int(getattr(usage, "prompt_tokens", 0) or 0)
+        completion_tokens: int = int(getattr(usage, "completion_tokens", 0) or 0)
+
+        try:
+            cost_usd: float = float(litellm.completion_cost(completion_response=response) or 0.0)
+        except Exception as error:
+            log.debug("cost_calc_skipped", model=self._model, error=str(error))
+            cost_usd = 0.0
+
+        return LLMResponse(
+            content=message.content,
+            tool_calls=tool_calls,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            cost_usd=cost_usd,
+        )
+
+    async def complete_structured(
+        self, messages: list[dict[str, Any]], schema: type[_Structured]
+    ) -> _Structured:
+        messages = self._prepare_messages(messages)
+        response: Any = await litellm.acompletion(
+            model=self._model,
+            messages=messages,
+            response_format=schema,
+            **self._reliability_kwargs(),
+            **self._sampling_kwargs(structured=True),
+        )
+        content: str = response.choices[0].message.content or "{}"
+        return schema.model_validate_json(content)

bare_agent/logging.py

@@ -0,0 +1,49 @@
+"""Structured logging via structlog: console for dev, JSON for prod."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+import orjson
+import structlog
+
+_is_configured: bool = False
+
+
+def _orjson_serializer(obj: Any, default: Any = None, **_: Any) -> str:
+    return orjson.dumps(obj, default=default).decode()
+
+
+def configure_logging(*, level: str = "INFO", json: bool = False) -> None:
+    global _is_configured
+    if _is_configured:
+        return
+
+    level_number: int = logging.getLevelNamesMapping().get(level.upper(), logging.INFO)
+    renderer: Any = (
+        structlog.processors.JSONRenderer(serializer=_orjson_serializer)
+        if json
+        else structlog.dev.ConsoleRenderer(colors=sys.stderr.isatty())
+    )
+
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.format_exc_info,
+            renderer,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(level_number),
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+        cache_logger_on_first_use=True,
+    )
+    _is_configured = True
+
+
+def get_logger(name: str | None = None) -> Any:
+    if not _is_configured:
+        configure_logging()
+    return structlog.get_logger(name)

bare_agent/loop.py

@@ -0,0 +1,200 @@
+"""An LLM in a tool-use loop: a stateless reducer over an explicit message list."""
+
+from __future__ import annotations
+
+from collections import Counter
+from contextlib import AsyncExitStack
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+import orjson
+from pydantic import BaseModel
+
+from bare_agent.budget import Budget, BudgetState, BudgetStop
+from bare_agent.events import EventSink, emit
+from bare_agent.llm import LLMResponse, TokenSink
+from bare_agent.logging import get_logger
+from bare_agent.registry import Approver, ToolCall, ToolRegistry, ToolResult
+
+log = get_logger(__name__)
+
+_CYCLE_LIMIT: int = 3
+
+
+class CompletionClient(Protocol):
+    async def complete(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        *,
+        on_token: TokenSink | None = None,
+    ) -> LLMResponse: ...
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    answer: str
+    stop_reason: str
+    turns: int
+    tokens: int
+    cost_usd: float
+    transcript: list[dict[str, Any]] = field(default_factory=list)
+
+
+def _result_to_text(result: ToolResult) -> str:
+    if not result.ok:
+        return orjson.dumps({"error": result.error}).decode()
+    content: Any = result.content
+    if isinstance(content, BaseModel):
+        return content.model_dump_json()
+    if isinstance(content, str):
+        return content
+    return orjson.dumps(content, default=str).decode()
+
+
+def _wrap_untrusted(result: ToolResult) -> str:
+    text: str = _result_to_text(result)
+    if not result.ok:
+        return text
+    return f"<untrusted_tool_output>\n{text}\n</untrusted_tool_output>"
+
+
+def _parse_arguments(raw: str) -> dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        loaded: Any = orjson.loads(raw)
+    except orjson.JSONDecodeError:
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def _call_signature(name: str, args: dict[str, Any]) -> str:
+    return orjson.dumps({"n": name, "a": args}, option=orjson.OPT_SORT_KEYS).decode()
+
+
+class AgentLoop:
+    def __init__(
+        self,
+        *,
+        registry: ToolRegistry,
+        llm: CompletionClient,
+        budget: Budget,
+        system_prompt: str,
+        approver: Approver | None = None,
+    ) -> None:
+        self._registry: ToolRegistry = registry
+        self._llm: CompletionClient = llm
+        self._budget: Budget = budget
+        self._system_prompt: str = system_prompt
+        self._approver: Approver | None = approver
+
+    async def run(
+        self,
+        user_input: str,
+        *,
+        on_event: EventSink | None = None,
+        stream_tokens: bool = False,
+    ) -> AgentResult:
+        state: BudgetState = BudgetState(self._budget)
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": self._system_prompt},
+            {"role": "user", "content": user_input},
+        ]
+        tools: list[dict[str, Any]] | None = self._registry.schema() or None
+        answer: str = ""
+        stop_reason: str = "completed"
+        seen_calls: Counter[str] = Counter()
+
+        token_sink: TokenSink | None = None
+        if stream_tokens and on_event is not None:
+
+            async def token_sink(delta: str) -> None:
+                await emit(on_event, "token", text=delta)
+
+        async with AsyncExitStack() as stack:
+            stack.callback(lambda: log.debug("agent_loop_teardown", turns=state.turns))
+
+            while True:
+                stop: BudgetStop | None = state.exceeded()
+                if stop is not None:
+                    stop_reason = stop.value
+                    answer = answer or f"[stopped: {stop.value} budget reached]"
+                    break
+
+                response: LLMResponse = await self._llm.complete(
+                    messages, tools=tools, on_token=token_sink
+                )
+                state.record_turn(
+                    tokens=response.prompt_tokens + response.completion_tokens,
+                    cost_usd=response.cost_usd,
+                )
+                log.info(
+                    "turn",
+                    n=state.turns,
+                    tokens=state.tokens,
+                    cost_usd=round(state.cost_usd, 4),
+                    tool_calls=len(response.tool_calls),
+                )
+                await emit(
+                    on_event,
+                    "turn",
+                    n=state.turns,
+                    tool_calls=len(response.tool_calls),
+                    cost_usd=round(state.cost_usd, 4),
+                )
+
+                if not response.tool_calls:
+                    answer = response.content or ""
+                    stop_reason = "completed"
+                    break
+
+                messages.append(
+                    {
+                        "role": "assistant",
+                        "content": response.content,
+                        "tool_calls": [
+                            {
+                                "id": call.id,
+                                "type": "function",
+                                "function": {"name": call.name, "arguments": call.arguments},
+                            }
+                            for call in response.tool_calls
+                        ],
+                    }
+                )
+
+                cycling: bool = False
+                for call in response.tool_calls:
+                    parsed: dict[str, Any] = _parse_arguments(call.arguments)
+                    signature: str = _call_signature(call.name, parsed)
+                    seen_calls[signature] += 1
+                    result: ToolResult = await self._registry.dispatch(
+                        ToolCall(name=call.name, arguments=parsed),
+                        approver=self._approver,
+                    )
+                    await emit(on_event, "tool_call", name=call.name, ok=result.ok)
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": call.id,
+                            "content": _wrap_untrusted(result),
+                        }
+                    )
+                    if seen_calls[signature] >= _CYCLE_LIMIT:
+                        cycling = True
+
+                if cycling:
+                    stop_reason = "cycle"
+                    answer = answer or "[stopped: repeated the same tool call — likely a loop]"
+                    log.warning("agent_cycle", turns=state.turns)
+                    break
+
+        return AgentResult(
+            answer=answer,
+            stop_reason=stop_reason,
+            turns=state.turns,
+            tokens=state.tokens,
+            cost_usd=round(state.cost_usd, 6),
+            transcript=messages,
+        )

bare_agent/registry.py

@@ -0,0 +1,131 @@
+"""Self-registering tool registry with permission gating and async dispatch."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, Protocol, get_type_hints
+
+from pydantic import BaseModel, ValidationError
+
+
+class Permission(StrEnum):
+    ALLOW = "allow"
+    ASK = "ask"
+    DENY = "deny"
+
+
+class ToolFunction(Protocol):
+    __name__: str
+
+    async def __call__(self, args: Any, /) -> Any: ...
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    name: str
+    ok: bool
+    content: Any = None
+    error: str | None = None
+
+
+Approver = Callable[[ToolCall], Awaitable[bool]]
+
+
+@dataclass(frozen=True)
+class Tool:
+    name: str
+    description: str
+    args_model: type[BaseModel]
+    func: ToolFunction
+    permission: Permission
+
+    def json_schema(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.args_model.model_json_schema(),
+            },
+        }
+
+
+def _extract_args_model(func: ToolFunction) -> type[BaseModel]:
+    parameters: list[inspect.Parameter] = [
+        parameter
+        for parameter in inspect.signature(func).parameters.values()
+        if parameter.name != "self"
+    ]
+    if len(parameters) != 1:
+        raise ValueError(f"tool {func.__name__!r} must take exactly one Pydantic-model argument")
+    annotation: Any = get_type_hints(func).get(parameters[0].name)
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+    raise ValueError(f"tool {func.__name__!r} argument must be annotated with a BaseModel subclass")
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def tool(
+        self, *, permission: Permission = Permission.ALLOW
+    ) -> Callable[[ToolFunction], ToolFunction]:
+        def decorator(func: ToolFunction) -> ToolFunction:
+            description: str | None = inspect.getdoc(func)
+            if not description:
+                raise ValueError(
+                    f"tool {func.__name__!r} needs a docstring; it becomes the LLM description"
+                )
+            self._tools[func.__name__] = Tool(
+                name=func.__name__,
+                description=description,
+                args_model=_extract_args_model(func),
+                func=func,
+                permission=permission,
+            )
+            return func
+
+        return decorator
+
+    def names(self) -> list[str]:
+        return list(self._tools)
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def schema(self) -> list[dict[str, Any]]:
+        return [tool.json_schema() for tool in self._tools.values()]
+
+    async def dispatch(self, call: ToolCall, *, approver: Approver | None = None) -> ToolResult:
+        tool: Tool | None = self._tools.get(call.name)
+        if tool is None:
+            return ToolResult(call.name, ok=False, error=f"unknown tool: {call.name!r}")
+
+        if tool.permission is Permission.DENY:
+            return ToolResult(call.name, ok=False, error="denied by policy")
+        if tool.permission is Permission.ASK:
+            is_approved: bool = await approver(call) if approver is not None else False
+            if not is_approved:
+                return ToolResult(call.name, ok=False, error="denied (no approval granted)")
+
+        try:
+            args: BaseModel = tool.args_model.model_validate(call.arguments)
+        except ValidationError as error:
+            return ToolResult(call.name, ok=False, error=f"invalid arguments: {error}")
+
+        try:
+            content: Any = await tool.func(args)
+        except Exception as error:
+            return ToolResult(call.name, ok=False, error=f"{type(error).__name__}: {error}")
+
+        return ToolResult(call.name, ok=True, content=content)

bare_agent-0.0.1.dist-info/METADATA

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: bare-agent
+Version: 0.0.1
+Summary: A framework-free agent runtime you can read, run, and leave. Own the loop, not the framework. Runs local on Ollama at $0 — or any frontier model.
+Project-URL: Homepage, https://github.com/subratamondal1/bare-agent
+Project-URL: Repository, https://github.com/subratamondal1/bare-agent
+Author: Subrata Mondal
+License: MIT
+License-File: LICENSE
+Keywords: agents,framework-free,litellm,llm,local-first,ollama,tool-calling
+Requires-Python: >=3.12
+Requires-Dist: litellm>=1.55
+Requires-Dist: orjson>=3.10
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: pydantic>=2.10
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: structlog>=24.4
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115; extra == 'api'
+Requires-Dist: httpx>=0.28; extra == 'api'
+Requires-Dist: redis>=5; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.32; extra == 'api'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/subratamondal1/bare-agent/main/docs/assets/logo.png" width="96" alt="Bare Agent" />
+</p>
+
+<h1 align="center">Bare Agent</h1>
+
+<p align="center">
+  <strong>Own the loop, not the framework.</strong>
+</p>
+
+<p align="center">
+  A framework-free agent runtime you can read, run, and leave — a small library you<br/>
+  import and call, plus a visual studio that ejects to plain Python with zero dependency on us.
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue?style=flat" alt="Python 3.12+">
+  <img src="https://img.shields.io/badge/tests-29%20passing-brightgreen?style=flat" alt="Tests: 29 passing">
+  <img src="https://img.shields.io/badge/local--first-Ollama-orange?style=flat" alt="Local-first">
+  <img src="https://img.shields.io/badge/studio-Next.js%2016-black?style=flat" alt="Studio: Next.js 16">
+</p>
+
+<p align="center">
+  <a href="https://github.com/subratamondal1/bare-agent/actions/workflows/ci.yml"><img src="https://github.com/subratamondal1/bare-agent/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/subratamondal1/bare-agent/stargazers"><img src="https://img.shields.io/github/stars/subratamondal1/bare-agent?style=flat&color=yellow" alt="Stars"></a>
+  <a href="https://github.com/subratamondal1/bare-agent/commits/main"><img src="https://img.shields.io/github/last-commit/subratamondal1/bare-agent?style=flat" alt="Last commit"></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#quickstart">Quickstart</a> •
+  <a href="#the-studio">Studio</a> •
+  <a href="#how-it-works">How it works</a> •
+  <a href="#eject">Eject</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#development">Development</a>
+</p>
+
+---
+
+Most agent frameworks own your `main()`, hide control flow behind metaclasses and DAG executors,
+and obscure the actual prompts. `bare-agent` is the opposite: a small library — the agent loop, a
+tool registry, a 3-axis budget, and a LiteLLM gateway, ~600 readable lines — that you **import and
+call**. You own the loop. Every prompt is in plain sight. You can always **eject to plain Python**
+and run it with **zero `bare_agent` dependency**.
+
+On top of the library sits an optional **visual studio**: wire agents into a chain on a canvas,
+attach tools, **Run** and watch tokens stream live, then eject the whole flow to a self-contained
+`agent.py`. **Local-first** — it runs at zero cost on Ollama; OpenAI, Anthropic, and Gemini are
+optional drop-ins through the same loop. Built on Python 3.12 · LiteLLM · FastAPI · Next.js 16 —
+with **no agent framework** (no LangChain/LangGraph): the loop, the budget, and the failure
+handling are owned directly.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/subratamondal1/bare-agent/main/docs/assets/bare-agent-demo.gif" width="100%" alt="Bare Agent studio: chain a Solver and an Explainer agent on a canvas, attach the calculator, Run and watch each agent's turns, tool calls, and tokens stream live with real per-call cost, then Eject the whole flow to a self-contained Python script." />
+</p>
+
+<p align="center">
+  <em>The studio, end to end: chain a <strong>Solver</strong> and an <strong>Explainer</strong>, attach the calculator, <strong>Run</strong> and watch each agent stream its turns, tool calls, and tokens live — with real per-call cost attribution (here on <code>gpt-5.4-mini</code>, ~$0.0006 for the whole chain) — then <strong>Eject to Python</strong>, a self-contained <code>agent.py</code> with zero <code>bare_agent</code> dependency. The same loop runs local-first on Ollama at $0.</em>
+</p>
+
+## Features
+
+| Capability | Detail |
+|---|---|
+| **Framework-free agent loop** | A hand-written tool-use loop over LiteLLM with a 3-axis budget (turns / tokens / wall-clock) + hard cost cap, a retry/fallback ladder, and a self-registering, permission-gated tool registry. The loop is a stateless reducer over an explicit `messages: list[dict]`. |
+| **Local-first, $0 — or BYO frontier key** | Every call goes through LiteLLM, so the model id picks the provider. `ollama_chat/qwen3` runs free and offline; `anthropic/…`, `openai/…`, `gemini/…` are drop-ins. No lock-in. |
+| **Multi-agent chains** | Wire agents agent→agent; the runtime topologically orders them and feeds each answer into the next. Inline runs, queued runs, and ejected code all execute the same chain. |
+| **Visual studio** | A React Flow canvas (Next.js 16 / React 19) to build chains, attach tools, and watch turns / tool calls / tokens stream live over SSE — one readable section per agent. |
+| **Eject to plain Python** | Compile any graph to a standalone `agent.py` (litellm + pydantic only) — tool sources inlined, **zero `bare_agent` import**. Machine-checked to compile. The graph is a convenience, never a cage. |
+| **HITL / permissions** | An `Approver` gates tool calls allow / ask / deny; successful tool output is wrapped `<untrusted_tool_output>` for prompt-injection containment. |
+| **Horizontal scale** | An optional Redis-list job queue + worker pool; Kubernetes + **KEDA scale workers 0→N→0** on queue depth — the same shape as [Argus](https://github.com/subratamondal1/argus)'s searcher fan-out. |
+| **Composition, not configuration** | Seams are Python `Protocol`s — swap the LLM, the approver, or the event sink by passing a different object. No god-object to subclass. |
+
+## Quickstart
+
+```bash
+uv add bare-agent          # or: pip install bare-agent
+```
+
+A complete agent in ~30 lines — the docstring becomes the LLM's tool description:
+
+```python
+import asyncio
+from pydantic import BaseModel, Field
+from bare_agent import AgentLoop, Budget, LLMClient, ToolRegistry, get_settings
+
+registry = ToolRegistry()
+
+class AddArgs(BaseModel):
+    a: int = Field(description="first addend")
+    b: int = Field(description="second addend")
+
+@registry.tool()
+async def add(args: AddArgs) -> int:
+    """Add two integers and return their sum."""
+    return args.a + args.b
+
+async def main() -> None:
+    settings = get_settings()          # local Ollama by default; set BARE_AGENT_MODEL for frontier
+    agent = AgentLoop(
+        registry=registry,
+        llm=LLMClient.from_settings(settings),
+        budget=Budget.from_settings(settings),
+        system_prompt="You are a precise assistant. Use tools for arithmetic.",
+    )
+    result = await agent.run("What is 17 + 25, then add 100 to that?")
+    print(result.answer)               # -> "142"
+    print(result.stop_reason, result.turns, f"${result.cost_usd}")  # -> completed 3 $0.0
+
+asyncio.run(main())
+```
+
+Run it locally for free:
+
+```bash
+ollama pull qwen3        # one-time (qwen3:30b-a3b-thinking on a 32GB Mac)
+make demo                # or: uv run python examples/quickstart.py
+```
+
+## The studio
+
+```bash
+make web      # FastAPI on :8000 + Next.js studio on :3000 → http://localhost:3000/studio
+```
+
+Open `http://localhost:3000/studio`: **Add** agents and wire them into a chain, attach catalog
+tools, pick a model (local qwen3 at $0 or your frontier key), and **Run** — each agent streams its
+turns, tool calls, and tokens live over SSE in its own section. The backend is standalone: `make
+api` runs the control plane alone, and the library works with no UI at all.
+
+## How it works
+
+```
+user input
+   │
+   ▼
+┌──────────────┐   answer feeds   ┌──────────────┐
+│   Agent 1    │ ───────────────► │   Agent 2    │ ──────────►  final answer
+│  + tools     │   the next       │  + tools     │
+└──────────────┘                  └──────────────┘
+   each agent = ONE hand-written loop:
+   explicit messages list · 3-axis budget + cost cap · permission-gated tool dispatch
+
+   run it:   inline over SSE      ·  or  queue → worker pool → KEDA scales 0→N→0
+   keep it:  Eject ──► agent.py   (litellm + pydantic only — ZERO bare_agent dependency)
+```
+
+The loop is a **stateless reducer** over an explicit `messages: list[dict]`. That one decision pays
+three ways, all for free:
+
+- **Durability** — the list is serializable, so checkpoint it and resume after a crash.
+- **Eject-to-code** — the list *is* the program; there was never a framework underneath to lift out.
+- **Testability** — feed a canned `messages` list (or a fake `CompletionClient`), assert.
+
+No metaclass magic, no hidden DAG executor, no god-object to subclass, no state trapped in a
+session. Extensibility is composition: `AgentLoop(llm=..., approver=..., registry=...)`.
+
+### The 8 primitives (each usable on its own — not a god-object)
+
+| # | Primitive | Where |
+|---|---|---|
+| ① | Tool registry — `@registry.tool()` → JSON-schema → permission-gated dispatch | `registry.py` |
+| ② | Prompt assembly — the explicit, serializable `messages: list[dict]` | `loop.py` |
+| ③ | Agent loop — `AsyncExitStack` + 3-axis budget + termination + cycle-stop | `loop.py` |
+| ④ | Retry / fallback over LiteLLM (local Ollama **or** any frontier model) | `llm.py` |
+| ⑤ | State / memory — checkpoint the `messages` list (durability for free) | `loop.py` |
+| ⑥ | HITL / permissions — allow / ask / deny, an `Approver` on `ask` | `registry.py` |
+| ⑦ | Observability — `structlog` + an optional `EventSink` (SSE-ready) | `events.py` |
+| ⑧ | Eval gate — golden replay (roadmap) | — |
+
+## Eject
+
+Any flow — single agent or a chain — compiles to a standalone script that imports only `litellm`
+and `pydantic`. Tool sources are inlined verbatim; there is **no `bare_agent` import**:
+
+```bash
+uv run --with litellm --with pydantic agent.py "your question"
+```
+
+In the studio, **Eject to Python** shows the generated code and downloads it. The generated file is
+machine-checked to compile. You can read it, diff it, vendor it, and run it after you stop using
+bare-agent entirely — that is the point.
+
+## Configuration
+
+Settings are read by [Pydantic Settings](src/bare_agent/config.py) from the environment
+(`BARE_AGENT_` prefix) or `.env` (`cp .env.example .env`). The defaults are fully local and free.
+Common overrides:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `BARE_AGENT_MODEL` | `ollama_chat/qwen3` | LiteLLM model id. Local Ollama by default; `anthropic/…`, `openai/…`, `gemini/…` for hosted. |
+| `BARE_AGENT_OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama server, passed as `api_base` for `ollama_chat/` models. |
+| `BARE_AGENT_FALLBACK_MODELS` | `[]` | Ordered fallback model ids (JSON list) for the retry ladder. |
+| `BARE_AGENT_MAX_TURNS` / `…_TOKENS` / `…_WALLCLOCK_S` / `…_COST_USD` | `8` / `120000` / `180` / `0.50` | The 3-axis budget + hard cost cap; the loop stops on the first to trip. |
+| `BARE_AGENT_USE_QUEUE` | `false` | Route runs through the Redis queue + worker pool (KEDA-autoscalable) instead of inline. |
+| `BARE_AGENT_REDIS_URL` | `redis://localhost:6379/0` | Redis DSN for the run queue + event pub/sub (queue mode). |
+
+For a hosted model, set `BARE_AGENT_MODEL=anthropic/…` and export that provider's key
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`) — LiteLLM reads it from the environment.
+
+## Development
+
+```bash
+make ci          # lock-check + format-check + lint (ruff) + compile + typecheck (ty) + tests (pytest)
+make test        # the 29-test suite — hermetic (the LLM and Redis are faked; no daemon needed)
+make web         # backend + studio together for local hacking
+make up / down   # the Docker stack (api + studio; Ollama stays on the host)
+make queue-up    # the Docker stack WITH the KEDA-shaped worker plane (+ redis + worker)
+make help        # all targets
+```
+
+Kubernetes manifests live in [`k8s/`](k8s/) — an inline deploy (api + studio) and the KEDA worker
+plane (redis + worker). The studio has its own toolchain ([`apps/studio/AGENTS.md`](apps/studio/AGENTS.md));
+the canonical agent rules for the whole repo are in [`AGENTS.md`](AGENTS.md).
+
+<!-- Uncomment once the repo has stars (renders an empty chart at 0):
+## Star history
+
+<p align="center">
+  <a href="https://star-history.com/#subratamondal1/bare-agent&Date">
+    <img src="https://api.star-history.com/svg?repos=subratamondal1/bare-agent&type=Date" width="600" alt="Star history">
+  </a>
+</p>
+-->
+
+## License
+
+MIT © 2026 Subrata Mondal — see [LICENSE](LICENSE). Built as the clean, reusable extraction of
+[Argus](https://github.com/subratamondal1/argus)'s agent runtime.

bare_agent-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+bare_agent/__init__.py,sha256=rcQ-zsxFXVuoQxBmO1bNrlZRiRB6S8XGFfqnnFEyMEc,1095
+bare_agent/budget.py,sha256=uc8NCE1tH6l3uiAlOd6p1u_AUGj9U8OF8DIQtswGo5c,1696
+bare_agent/config.py,sha256=dkJfva3dR5SGpDAvgmkYlOPletSZJ2XSIK10jJF7dAo,2689
+bare_agent/events.py,sha256=ZWV3j_Y6_P8zKjq5dInJLTXpaBqOo-XB1SIARHiovSQ,527
+bare_agent/llm.py,sha256=dOWP2V5NEM0qw1a2ba4Dg9DSAd3NZvCiYw9GholWy8M,7083
+bare_agent/logging.py,sha256=G8ymSKdWc6-VTavr7prhqXXk7JkyRnKPTkreuxTEoe8,1415
+bare_agent/loop.py,sha256=i1mku-xJM0B13kFaoBpQ-uPvCpwPxwpUQmWRvxBlfo0,6745
+bare_agent/registry.py,sha256=fkKw0ablqZjnowtKIYB2N6Mk3-HZ7kRYfKJVnJmxnns,4092
+bare_agent-0.0.1.dist-info/METADATA,sha256=Xhv6CLt7f4bTgXL7pIOqycAVKHRqzwiVWMc9ApPoBT4,13666
+bare_agent-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+bare_agent-0.0.1.dist-info/licenses/LICENSE,sha256=v9lKPOS9UqhAyTzPdgHCMV8g4FlMdSD2FY26w5I98jE,1071
+bare_agent-0.0.1.dist-info/RECORD,,

bare_agent-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

bare_agent-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Subrata Mondal
+
+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.