Metadata-Version: 2.4
Name: bog-agents
Version: 0.8.1
Summary: Bog Agents — a still-water agent framework. Patient by default, opinionated where it matters, batteries included. Build agents on top of any major LLM provider (Anthropic, OpenAI, Bedrock, Google, Mistral, Groq, DeepSeek) or run local with Ollama. 80+ middlewares, real subagents, file-system + shell + sandbox backends, MCP tooling, a typed config surface. Built on LangGraph; pass through in harmony.
Author-email: bogware <support@bogware.com>
Maintainer-email: bogware <support@bogware.com>
License: MIT
Project-URL: Homepage, https://github.com/bogware/bog-agents
Project-URL: Repository, https://github.com/bogware/bog-agents
Project-URL: Issues, https://github.com/bogware/bog-agents/issues
Keywords: agents,ai,llm,langgraph,langchain,bog-agents,sub-agents,agentic,multi-provider,ollama
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: anyio<5.0.0,>=4.0.0
Requires-Dist: langchain-core<2.0.0,>=1.2.28
Requires-Dist: langchain<2.0.0,>=1.2.11
Requires-Dist: langchain-anthropic<2.0.0,>=1.3.4
Requires-Dist: langchain-google-genai<5.0.0,>=4.2.0
Requires-Dist: wcmatch<7.0,>=6.0
Requires-Dist: cryptography>=46.0.7
Requires-Dist: pyasn1>=0.6.3
Requires-Dist: requests>=2.33.0
Requires-Dist: pygments>=2.20.0
Provides-Extra: serve
Requires-Dist: starlette>=0.41.0; extra == "serve"
Requires-Dist: uvicorn>=0.34.0; extra == "serve"
Requires-Dist: sse-starlette>=2.0.0; extra == "serve"

# Bog Agents

> *Patient as still water. Opinionated where it matters. Pass through in harmony.*

The Python SDK underneath [`bog-agents-cli`](https://pypi.org/project/bog-agents-cli/) and
[`bog-agents-daemon`](https://pypi.org/project/bog-agents-daemon/) — and an
SDK in its own right when you want to build agents that aren't a CLI.

One `create_agent()` call gets you a compiled LangGraph agent with file tools, a shell,
git, sub-agents, plan mode, auto-quality checks, retry-with-backoff against transient
provider failures, and 80-something composable middlewares. Pluggable backends. Any
tool-calling LLM. The defaults are deliberate — you ship something that works on day
one without writing scaffolding.

[![PyPI](https://img.shields.io/pypi/v/bog-agents)](https://pypi.org/project/bog-agents/)
[![Python](https://img.shields.io/pypi/pyversions/bog-agents)](https://pypi.org/project/bog-agents/)
[![License](https://img.shields.io/pypi/l/bog-agents)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/pepy/dt/bog-agents)](https://pypistats.org/packages/bog-agents)

---

## Philosophy

Most agent frameworks make you assemble the kit. We don't. Bog Agents starts you
with a working agent and lets you peel away or bolt on layers as you understand
what you actually need.

- **Patient by default.** Failures retry with bounded backoff. Hung commands time out.
  Provider hiccups don't kill the run.
- **Opinionated where it matters.** Secure-by-default backends, a memory-only secrets
  vault, structured logging at every chokepoint, panic dumps on uncaught exceptions.
- **No ceremony.** `create_agent()` returns a compiled `CompiledStateGraph` you can
  invoke. Plug it into your app. Done.
- **Composable.** 80+ middlewares snap on or off. Subagents nest. Backends swap. The
  framework gets out of your way.

The bog is calm, deep, and unhurried. So is the agent.

---

## Install

```bash
pip install bog-agents
```

Provider extras as needed:

```bash
pip install "bog-agents[anthropic]"      # Claude
pip install "bog-agents[openai]"         # GPT
pip install "bog-agents[bedrock]"        # AWS Bedrock
pip install "bog-agents[google-genai]"   # Gemini
pip install "bog-agents[ollama]"         # local models
```

Or all of them: `pip install "bog-agents[all-providers]"`.

---

## 30-second Quick Start

```python
from bog_agents import create_agent

agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt="You are a careful, concise software engineer.",
)

result = await agent.ainvoke({
    "messages": [{"role": "user", "content": "List Python files in this repo."}]
})

print(result["messages"][-1].content)
```

That gets you: filesystem tools, shell execution, sub-agents, plan-mode, summarization
middleware, prompt caching for Anthropic models, and the standard tool-call patcher.
No additional setup.

### With more knobs

```python
from bog_agents import create_agent, FeatureConfig
from bog_agents.middleware import (
    GitToolsMiddleware,
    MemoryMiddleware,
    ProviderRetryMiddleware,
    SkillsMiddleware,
)

agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    config=FeatureConfig(
        enable_audit_trail=True,
        enable_cost_tracking=True,
        budget_usd=5.0,
    ),
    middleware=[
        ProviderRetryMiddleware(max_attempts=3),
        GitToolsMiddleware(),
        MemoryMiddleware(sources=["./AGENTS.md"]),
        SkillsMiddleware(sources=["./skills"]),
    ],
)
```

---

## What's in the box

### Backends

Pluggable filesystems and shells. Pick one or compose them.

| Backend | Use when |
|---|---|
| `StateBackend` (default) | Agent reads / writes happen in graph state. Great for sandboxed tests. |
| `FilesystemBackend` | Real filesystem. Path traversal blocked by `virtual_mode=True` (the default since 0.8.0). |
| `LocalShellBackend` | Filesystem + shell execution on the host. UTF-8 stdout decoding, configurable timeouts, `stdin=/dev/null` so interactive prompts can't hang the agent. |
| `CompositeBackend` | Route different path prefixes to different backends. |
| `SandboxBackend` | Modal / Daytona / RunLoop / LangSmith remote sandboxes. |

### Middlewares (selected)

- **`ProviderRetryMiddleware`** — bounded exponential backoff with jitter on transient
  provider errors (5xx, timeouts, connection resets). Never retries tool calls.
- **`MemoryMiddleware`** — load `AGENTS.md` files into the system prompt. 64 KiB cap;
  `</agent_memory>` close-tags neutralized to prevent prompt-injection forgery.
- **`SkillsMiddleware`** — bundle reusable agent skills with metadata.
- **`GitToolsMiddleware`** — git status / log / diff / blame; opt-in commit / push.
- **`SubAgentMiddleware`** — recursive task decomposition with typed subagent specs.
- **`PlanModeMiddleware`** — structured plan-then-execute flow.
- **`SummarizationMiddleware`** — token-aware history compression.
- **`AnthropicPromptCachingMiddleware`** — automatic prompt-cache breakpoints.
- **`HumanInTheLoopMiddleware`** — pause-and-confirm for risky tool calls.
- **`AuditTrailMiddleware`** — structured records of every agent decision.
- **`RBACMiddleware`** / **`DLPMiddleware`** — access control + data-loss prevention.

Plus 60+ more for cost tracking, citations, hooks, MCP tools, agent teams, parallel
worktrees, hot-reload skills, regulatory alerts, and more. Browse them under
`bog_agents.middleware`.

### Providers

| Provider | Extra | Notes |
|---|---|---|
| Anthropic | `anthropic` | Default. Claude 4.6 / 4.7 with prompt caching. |
| OpenAI | `openai` | Responses API by default. |
| AWS Bedrock | `bedrock` | Claude / Llama / Titan via `bedrock:` prefix. |
| Google | `google-genai` | Gemini family. |
| Mistral | `mistralai` | |
| Groq | `groq` | |
| DeepSeek | `deepseek` | |
| Fireworks | `fireworks` | |
| Baseten | `baseten` | |
| xAI | `xai` | |
| Ollama | `ollama` | Local models. |

Pass `model="provider:model-id"` and `create_agent` does the rest.

---

## Async first, sync if you want it

```python
# Async — recommended
result = await agent.ainvoke({"messages": [...]})

# Sync — works fine too
result = agent.invoke({"messages": [...]})
```

Streaming is supported via the standard LangGraph stream APIs.

---

## What's new in 0.8.0

- **`ProviderRetryMiddleware`** — bounded retries on transient provider failures.
- **`virtual_mode=True` is now the default** for `FilesystemBackend` (and
  `LocalShellBackend`). Path traversal blocked unless explicitly opted out.
- **Subprocess `stdin=/dev/null`** in `LocalShellBackend.execute()` — interactive
  commands like Windows `date` get an immediate EOF instead of hanging.
- **Typed subagent validation** at `create_agent()` — typo'd `name` /
  `description` / `system_prompt` fails fast instead of surfacing as a
  `KeyError` later.
- **`FileOperationError` Literal** extended with `parent_not_found`.
- **`MemoryMiddleware`** caps each AGENTS.md source at 64 KiB and neutralizes
  `</agent_memory>` close-tags (prompt-injection defense).

See [`CHANGELOG.md`](https://github.com/bogware/bog-agents/blob/main/CHANGELOG.md)
for the full 0.8.0 entry.

---

## When to use this vs. the CLI

- **Use the SDK** when you're embedding an agent in a Python application,
  building your own UI, writing tests, or composing agents into a larger
  system.
- **Use [`bog-agents-cli`](https://pypi.org/project/bog-agents-cli/)** when
  you want a coding agent in your terminal *right now* with no Python wiring.
- **Use [`bog-agents-daemon`](https://pypi.org/project/bog-agents-daemon/)**
  when you want agents that wake themselves on cron / file changes / webhooks
  / git pushes.

---

## Documentation

- Architecture overview: [`CLAUDE.md`](https://github.com/bogware/bog-agents/blob/main/CLAUDE.md)
- Middleware index: read the docstrings under `bog_agents.middleware`
- Sample agents: `bog_agents/bundled_agents/`
- Repo: <https://github.com/bogware/bog-agents>
- Issues: <https://github.com/bogware/bog-agents/issues>

---

## License

MIT. See [LICENSE](https://github.com/bogware/bog-agents/blob/main/LICENSE).

*Pass through in harmony.*
