Metadata-Version: 2.4
Name: st-agent-chat
Version: 1.0.0
Summary: Drop-in agentic AI chat component for Streamlit — 12 tools, extended thinking, computer use, session persistence, subagents, and multi-provider LLM support.
Author: RhythrosaLabs
License: MIT
Project-URL: Homepage, https://github.com/RhythrosaLabs/st-agent-chat
Project-URL: Repository, https://github.com/RhythrosaLabs/st-agent-chat
Project-URL: Issues, https://github.com/RhythrosaLabs/st-agent-chat/issues
Keywords: streamlit,component,agent,chat,ai,llm,tools,agentic
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit>=1.28.0
Requires-Dist: anthropic>=0.39.0
Requires-Dist: openai>=1.50.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: nbformat>=5.9.0
Dynamic: license-file

# st-agent-chat

**A fully-powered agentic AI chat component for Streamlit — 12 tools, extended thinking, computer use, session persistence, subagents, and multi-provider LLM support.**

Add a production-grade AI agent to any Streamlit app in one line of code. The component is completely self-contained — no sidebar, no page takeover. Drop it into any column, tab, or container. The agent can run shell commands, read/write/edit files, execute Python, search the web, grep codebases, and more.

[![PyPI](https://img.shields.io/pypi/v/st-agent-chat?color=blue)](https://pypi.org/project/st-agent-chat/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![Streamlit](https://img.shields.io/badge/streamlit-%E2%89%A51.28-red?logo=streamlit)](https://streamlit.io)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## Install

```bash
pip install st-agent-chat
```

## Quick Start

```python
import streamlit as st
from st_agent_chat import agent_chat

st.set_page_config(page_title="My AI App", layout="wide")
agent_chat(workspace=".")
```

That's it. You get a compact header bar, a Settings popover for provider/model selection, thinking and computer use toggles, session management, and an AI agent that can execute 12 tools on your machine.

## Set Up an API Key

```bash
# Pick one (or several — the agent uses the first available)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
REPLICATE_API_TOKEN=r8_...
OPENROUTER_API_KEY=sk-or-...
```

Provider fallback order: Anthropic → OpenAI → Replicate → OpenRouter.

---

## Tools (12 Real Executable Tools)

| Tool | What it does |
|------|-------------|
| **bash** | Run any shell command (120s timeout) |
| **file_read** | Read file contents, optionally by line range (100KB max) |
| **file_write** | Create or overwrite files (auto-creates directories) |
| **file_edit** | Search-and-replace edit (exact match, must be unique) |
| **python_exec** | Execute Python code and return stdout/stderr |
| **web_fetch** | Fetch a URL; extracts readable text from HTML pages |
| **web_search** | Search the web via DuckDuckGo and return results |
| **list_directory** | List files and folders in a directory |
| **grep_search** | Search file contents with regex patterns across the workspace |
| **glob_search** | Find files by glob pattern (e.g. `**/*.py`) |
| **multi_file_edit** | Apply multiple file edits atomically with validation |
| **notebook_edit** | Edit Jupyter notebook cells (add, replace, delete) |

All file operations are **sandboxed** to the workspace root. The agent chains tools automatically — ask it to "find all TODO comments and create a summary file" and it will grep, read the matches, and write the summary, all in one turn.

## Key Features

### Extended Thinking

Enable Claude's extended thinking for complex reasoning tasks:

```python
agent_chat(
    workspace=".",
    extended_thinking=True,
    thinking_budget=20000,  # tokens for internal reasoning
)
```

Thinking content is displayed in collapsible cards in the UI. Toggle it live via Settings.

### Computer Use

Enable Claude's computer use tools (screenshot, mouse, keyboard):

```python
agent_chat(workspace=".", computer_use=True)
```

### Session Persistence

Save and restore agent sessions to disk:

```python
from st_agent_chat import AgentEngine, save_session, load_session, list_sessions

engine = AgentEngine(workspace=".")
engine.submit("Build a Flask app")
engine.save()  # saves to .agent_sessions/{session_id}.json

# Later...
sessions = list_sessions(".")
engine.load(sessions[0]["session_id"])
```

The UI has built-in Save/Load buttons in Settings.

### Subagents

Spawn isolated sub-tasks with restricted tools and custom prompts:

```python
from st_agent_chat import AgentEngine, SubagentConfig

engine = AgentEngine(workspace=".", provider="anthropic")

# Exploration subagent — read-only tools only
result = engine.run_subagent(
    "Find all database queries in this codebase",
    config=SubagentConfig(
        name="explorer",
        allowed_tools=["file_read", "grep_search", "glob_search", "list_directory"],
        max_turns=5,
    ),
)
print(result.output)
```

## Supported LLM Providers

| Provider | Models | Env Variable |
|----------|--------|-------------|
| **Anthropic** | claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5 | `ANTHROPIC_API_KEY` |
| **OpenAI** | gpt-5.4, gpt-5.4-mini, gpt-5.4-nano | `OPENAI_API_KEY` |
| **Replicate** | llama-4-maverick, llama-4-scout, llama-3.3-70b | `REPLICATE_API_TOKEN` |
| **OpenRouter** | qwen-3.6-plus (free), nemotron-3-super (free), gemma-4-26b | `OPENROUTER_API_KEY` |

Switch providers live from Settings — no restart needed.

---

## API Reference

### `agent_chat()`

```python
from st_agent_chat import agent_chat

agent_chat(
    workspace="/path/to/project",   # Root for file operations (default: ".")
    provider="anthropic",           # LLM provider (default: auto-detect)
    model="claude-sonnet-4-6",      # Model ID (default: provider's default)
    api_key="",                     # API key (default: read from env)
    max_turns=25,                   # Max tool-call rounds per message
    max_tokens=8192,                # Max tokens per LLM response
    temperature=0.7,                # LLM temperature
    system_prompt="",               # Custom system prompt (default: built-in)
    extended_thinking=False,        # Enable Claude extended thinking
    thinking_budget=10000,          # Max thinking tokens
    computer_use=False,             # Enable Claude computer use tools
    show_config=True,               # Show inline Settings popover
    show_cost=True,                 # Show token usage per response
    key="my_chat",                  # Streamlit widget key
)
```

### `AgentEngine`

```python
from st_agent_chat import AgentEngine

engine = AgentEngine(
    workspace=".",
    provider="anthropic",
    extended_thinking=True,
    thinking_budget=20000,
)

result = engine.submit("List all Python files and count their lines of code")
print(result.output)
print(result.thinking)  # internal reasoning (if extended_thinking=True)
print(f"Tokens: {result.usage.input_tokens} in / {result.usage.output_tokens} out / {result.usage.thinking_tokens} thinking")
print(f"Tool calls: {len(result.tool_calls)}")
```

### `SubagentConfig`

```python
from st_agent_chat import SubagentConfig

config = SubagentConfig(
    name="reviewer",
    system_prompt="You are a code reviewer. Focus on security issues.",
    allowed_tools=["file_read", "grep_search", "glob_search"],
    max_turns=10,
)
```

### `execute_tool()`

```python
from st_agent_chat import execute_tool

result = execute_tool("bash", {"command": "git log --oneline -5"})
result = execute_tool("grep_search", {"pattern": "TODO|FIXME", "path": "src/"})
result = execute_tool("glob_search", {"pattern": "**/*.py"})
result = execute_tool("web_search", {"query": "python flask tutorial"})
```

---

## Examples

### Extended thinking + subagents

```python
from st_agent_chat import AgentEngine, SubagentConfig

engine = AgentEngine(
    workspace=".",
    provider="anthropic",
    model="claude-sonnet-4-6",
    extended_thinking=True,
    thinking_budget=30000,
)

# Main task with deep reasoning
result = engine.submit("Analyze this codebase's architecture and suggest improvements")

# Spawn a subagent to implement one suggestion
impl_result = engine.run_subagent(
    "Refactor the database module to use connection pooling",
    config=SubagentConfig(
        name="implementer",
        max_turns=15,
    ),
)
```

### Embed alongside other Streamlit content

```python
import streamlit as st
from st_agent_chat import agent_chat

st.set_page_config(layout="wide")

col1, col2 = st.columns([2, 1])
with col1:
    st.metric("Users", "1,234")
    st.line_chart({"data": [1, 5, 2, 6, 3, 7]})
with col2:
    agent_chat(workspace=".", key="assistant")
```

---

## Architecture

```
st_agent_chat/
├── component.py    # Streamlit UI — chat, settings, thinking display, sessions
├── engine.py       # AgentEngine — tool loop, streaming, sessions, subagents
├── llm.py          # Multi-provider LLM client (thinking, computer use)
├── tools.py        # 12 executable tools with workspace sandboxing
└── __init__.py     # Public API exports
```

## Security

- **Workspace sandboxing**: All file operations confined to workspace root
- **Shell timeout**: `bash` commands have a 120-second timeout
- **No credential leakage**: API keys read from environment, never stored in state
- **User-initiated only**: Agent only acts on explicit user messages

> **Note**: This component executes real commands on your machine. Use in trusted environments.

## Development

```bash
git clone https://github.com/RhythrosaLabs/st-agent-chat.git
cd st-agent-chat
pip install -e ".[dev]"
streamlit run demo.py
```

## License

MIT — see [LICENSE](LICENSE).
