Metadata-Version: 2.4
Name: bobstack
Version: 1.0.0
Summary: Developer stack and Python client for the Bob Agent Client Protocol (ACP)
Author-email: Ashin T V <ashintv3@gmail.com>
License: Apache-2.0
Keywords: bob,bobstack,acp,agent-client-protocol,ai-agent,streaming,sdk,llm,tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"

# 🧰 BobStack for Python

Developer stack and Python client for the **Bob Agent Client Protocol (ACP)**.

Build autonomous coding assistants, IDE tools, streaming agent workflows, and terminal bots directly on top of Bob ACP without requiring any middleman server.

---

## ✨ Features

- ⚡ **Direct ACP Connection**: Directly launches and speaks JSON-RPC 2.0 with `bob acp` via standard I/O (`stdio`).
- 🌊 **Stream-First AsyncIterables**: Consume token deltas smoothly with `async for chunk in stream:`.
- 🎮 **Full Control Channels**:
  - **Cancel Channel**: Immediately aborts inference locally and dispatches `session/cancel` to Bob ACP.
  - **Intermediate Steering Channel**: Dynamically steer ongoing agent execution mid-turn.
- 🔧 **First-Class Tool & Thought Events**: Listen to live reasoning (`on_thought`), tool calls (`on_tool_call`), stdout/stderr chunks (`on_tool_output`), and results (`on_tool_result`).
- 🔄 **Stateful Sessions & Mode Switching**: Multi-turn conversation management with dynamic switching between `agent`, `ask`, and `plan` modes.
- 🛡️ **Zero Runtime Dependencies**: Built with standard library (`asyncio`, `subprocess`, `json`).

---

## 📋 Prerequisites

BobStack speaks directly with the Bob CLI (`bob acp`). Ensure you have:
1. **Node.js `>= 22`**
2. **Bob CLI (`@ibm/bob`)** installed globally:
   ```bash
   npm install --registry=https://registry.npmjs.org/ --allow-scripts=@officecli/officecli -g @ibm/bob
   ```
3. **Python `>= 3.9`**

---

## 📦 Installation

```bash
pip install bobstack
```

---

## 🚀 Quickstart: One-Liner `Bob.invoke`

```python
import asyncio
from bobstack import Bob

async def main():
    # 1. One-liner invocation (automatically spawns `bob acp`)
    stream = await Bob.invoke(
        "Write a Python script to check for prime numbers",
        mode="agent",
        on_thought=lambda thought: print(f"💭 [Thinking] {thought}"),
        on_tool_call=lambda tool: print(f"🔧 [Tool] {tool.name}: {tool.parameters}")
    )

    # 2. Stream tokens in real-time
    async for chunk in stream:
        print(chunk, end="", flush=True)

    # 3. Await final result and stop reason
    result = await stream.result()
    print(f"\nFinished: {result.stop_reason}")

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 🎛️ Control Channels (Pause, Resume, Cancel, Steer)

```python
import asyncio
from bobstack import Bob

async def main():
    stream = await Bob.invoke("Generate a detailed architectural analysis of a microservices backend")

    # 1. Pause & Resume (backpressure control without losing data)
    stream.pause()
    stream.resume()

    # 2. Intermediate Steering (inject guidance mid-flight)
    await stream.send_intermediate_message("Make sure to focus on Redis caching!")

    # 3. Cancel (stop agent execution immediately)
    await stream.cancel()
    print(stream.is_cancelled)  # True

    async for chunk in stream:
        print(chunk, end="", flush=True)

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 💬 Stateful Sessions & Mode Switching

```python
import asyncio
from bobstack import BobClient

async def main():
    client = BobClient()
    await client.connect()

    # 1. List active sessions
    sessions = await client.list_sessions()
    print(f"Active sessions: {len(sessions)}")

    # 2. Create session in 'agent' mode
    session = await client.create_session(mode="agent")

    # Turn 1:
    turn1 = await session.chat("Create a new index.ts file with an express server")
    async for chunk in turn1:
        print(chunk, end="", flush=True)

    # Switch mode to 'ask' for Q&A
    await session.set_mode("ask")

    # Turn 2 (context preserved!):
    turn2 = await session.chat("Explain the route structure you created")
    async for chunk in turn2:
        print(chunk, end="", flush=True)

    # View history
    print(session.get_history())

    await client.close()

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 📜 License

Apache-2.0
