Metadata-Version: 2.4
Name: notebook-assistant
Version: 0.2.0
Summary: Bring-your-own-LLM chat assistant for Jupyter notebooks — works with OpenAI, Anthropic, Gemini, AWS Bedrock, and any OpenAI-compatible endpoint.
Author: Ben Roshan
License: MIT License
        
        Copyright (c) 2026 Ben Roshan
        
        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.
        
Project-URL: Homepage, https://github.com/benroshan100/NotebookAssistant
Project-URL: Repository, https://github.com/benroshan100/NotebookAssistant
Project-URL: Issues, https://github.com/benroshan100/NotebookAssistant/issues
Project-URL: Changelog, https://github.com/benroshan100/NotebookAssistant/blob/main/CHANGELOG.md
Keywords: jupyter,notebook,llm,openai,anthropic,bedrock,gemini,data-analysis,assistant,chatbot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: Framework :: Jupyter
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm>=1.50
Requires-Dist: ipython
Requires-Dist: ipywidgets>=8
Requires-Dist: pandas
Requires-Dist: tabulate
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34; extra == "bedrock"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: all
Requires-Dist: boto3>=1.34; extra == "all"
Dynamic: license-file

# notebook-assistant

[![PyPI version](https://img.shields.io/pypi/v/notebook-assistant.svg)](https://pypi.org/project/notebook-assistant/)
[![Python versions](https://img.shields.io/pypi/pyversions/notebook-assistant.svg)](https://pypi.org/project/notebook-assistant/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/benroshan100/NotebookAssistant/actions/workflows/test.yml/badge.svg)](https://github.com/benroshan100/NotebookAssistant/actions/workflows/test.yml)

Bring-your-own-LLM chat assistant for Jupyter notebooks. Load a DataFrame or
markdown file, ask questions in plain English, get markdown-rendered answers
right in your cell — with the provider you already pay for.

Supports **OpenAI**, **Anthropic**, **Google Gemini**, **AWS Bedrock**, and
any OpenAI-compatible endpoint (e.g. **Euron**), routed through
[LiteLLM](https://github.com/BerriAI/litellm).

## Install

```bash
pip install notebook-assistant
```

For AWS Bedrock also install the `bedrock` extra (adds `boto3`):

```bash
pip install "notebook-assistant[bedrock]"
```

## Quickstart

Pick a provider, pass your key, ask a question.

### OpenAI

```python
from notebook_assistant import NotebookAssistant

assistant = NotebookAssistant(
    model="openai/gpt-4o",
    api_key="sk-...",   # or set OPENAI_API_KEY env var
)
assistant.ask("Give me three exploratory questions for a sales dataset.")
```

### Anthropic

```python
assistant = NotebookAssistant(
    model="anthropic/claude-3-5-sonnet-20241022",
    api_key="sk-ant-...",   # or ANTHROPIC_API_KEY
)
```

### Google Gemini

```python
assistant = NotebookAssistant(
    model="gemini/gemini-1.5-pro",
    api_key="...",   # or GEMINI_API_KEY
)
```

### AWS Bedrock

```python
assistant = NotebookAssistant(
    model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    aws_region="ap-south-1",
    # aws_access_key_id / aws_secret_access_key optional — falls back to
    # boto3's standard credential chain (env vars, IAM role, ~/.aws/credentials).
)
```

You can also pass an inference-profile ARN as the model id.

### Euron (OpenAI-compatible)

```python
assistant = NotebookAssistant(
    model="openai/gpt-5.3-instant",
    api_key="...",   # your Euron API key
    api_base="https://api.euron.one/api/v1/euri",
)
```

Any other OpenAI-compatible endpoint works the same way — pass
`model="openai/<name>"` with a matching `api_base`.

## Loading context

```python
import pandas as pd
from notebook_assistant import NotebookAssistant

df = pd.read_csv("sales.csv")

assistant = NotebookAssistant(model="openai/gpt-4o", api_key="sk-...")
assistant.add_context(
    instructions="Focus on month-over-month trends.",
    dataframes={"sales": df},
    markdown_path="docs/glossary.md",   # optional
)

assistant.ask("Which product saw the steepest decline last quarter?")
```

`add_context` accepts any combination of `instructions`, `dataframes`, and
`markdown_path`. The content becomes the first user message in the
conversation so every follow-up question sees it.

## Interactive chat

```python
assistant.chat()   # type 'exit' to quit
```

## Conversation management

```python
assistant.history   # list of {"role", "content"} dicts
assistant.reset()   # clear context and history
```

## Configuration reference

| Argument | Description |
|---|---|
| `model` | LiteLLM-style string: `<provider>/<model>`. See the [LiteLLM provider list](https://docs.litellm.ai/docs/providers). |
| `api_key` | Provider API key. If omitted, LiteLLM reads the provider's standard env var. |
| `api_base` | Override endpoint — for Euron or self-hosted OpenAI-compatible gateways. |
| `aws_region`, `aws_access_key_id`, `aws_secret_access_key`, `aws_session_token` | Bedrock-specific credentials. Fall back to the boto3 credential chain. |
| `system_prompt` | Custom system prompt. Defaults to a data-analysis-focused prompt. |
| `temperature` | Sampling temperature (default `0.2`). |
| `max_tokens` | Max response tokens (default `2048`). |
| `read_timeout` | Per-request timeout in seconds (default `60`). |

## Examples

- [`examples/quickstart.ipynb`](examples/quickstart.ipynb) — end-to-end walkthrough
  with multiple providers.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.

## License

[MIT](LICENSE)
