sysop is a Jupyter notebook assistant powered by GitHub's Copilot SDK. It provides an AI chatbot interface that integrates seamlessly with JupyterLab, enabling natural language interactions for code analysis, suggestions, and general assistance—all within your notebook environment.
- 🤖 GitHub Copilot Integration - Powered by GitHub's official Copilot SDK
- 📓 Jupyter Native - Load as an IPython extension with
%load_ext sysop - 💬 Auto-Rendering Markdown - Responses display as formatted markdown automatically
- 🔄 Conversation History - Maintains context across multiple interactions
- 🛠️ Extensible Tools - Register custom tools using
@define_tooldecorator - ⚡ Async-First - Built on asyncio for responsive notebook experience
pip install sysopgit clone https://github.com/NavigatorBBS/sysop.git
cd sysop
pip install -e ".[dev]"Create a .env file or set an environment variable:
GITHUB_COPILOT_PAT=your-github-copilot-pat-hereGet your token from: https://github.com/settings/tokens (requires copilot scope)
You can test the agent from your terminal:
sysop -c "How can I optimize this pandas DataFrame?"
sysop --chat "Analyze this code for efficiency"from dotenv import load_dotenv
load_dotenv()
%load_ext sysopThis automatically:
- Initializes the
NotebookChatAgentwith your GitHub Copilot credentials - Injects the
agentvariable into your notebook namespace - Makes
display()andMarkdown()utilities available
# Simple usage - response auto-displays as markdown
response = await agent.chat("How can I optimize this pandas DataFrame?")
response# Ask questions
sysop -c "What's the best way to handle missing data in pandas?"
# For longer questions with special characters, use quotes
sysop --chat "How do I optimize DataFrame groupby operations?"# Ask questions
response = await agent.chat("What's the best way to handle missing data in pandas?")
response # Auto-displays as formatted markdown
# For plain text without markdown formatting
plain_text = await agent.chat("Your question", as_markdown=False)# Analyze code snippets
code = '''
df = pd.read_csv('data.csv')
df = df[df['value'] > 0]
result = df.groupby('category').sum()
'''
response = await agent.analyze_code(code, context="data aggregation pipeline")
response# Get conversation history
messages = await agent.get_messages()
print(f"Conversation has {len(messages)} messages")
# Clear history to start fresh
await agent.clear_history()
# Cleanup when done (releases resources)
await agent.cleanup()Create custom tools that the agent can use:
from pydantic import BaseModel, Field
from copilot import define_tool
class AnalyzeCodeParams(BaseModel):
code: str = Field(description="Python code to analyze")
context: str = Field(default="", description="Optional context")
@define_tool(description="Analyze Python code for quality and best practices")
async def analyze_code_tool(params: AnalyzeCodeParams) -> str:
# Your analysis logic here
return f"Analyzing {len(params.code)} characters of code..."
# Register tools before first use
agent = NotebookChatAgent(model="gpt-4o")
agent.tools = [analyze_code_tool]
response = await agent.chat("Can you analyze my code?")sysop uses environment variables for configuration:
| Variable | Required | Description |
|---|---|---|
GITHUB_COPILOT_PAT |
Yes | Your GitHub Copilot Personal Access Token |
You can also initialize the agent programmatically:
from sysop import NotebookChatAgent
agent = NotebookChatAgent(
github_token="your-token",
model="gpt-4o",
system_prompt="Custom system prompt..."
)The main chatbot agent class.
Methods:
async chat(user_message: str, as_markdown: bool = True)- Send a message and get a responseasync analyze_code(code: str, context: Optional[str] = None)- Analyze Python codeasync suggest_notebook_improvements(notebook_summary: str)- Get notebook improvement suggestionsasync get_messages()- Get conversation historyasync clear_history()- Clear conversation and start freshasync cleanup()- Clean up resources (call when done)add_plugin(plugin_instance, plugin_name)- Register a plugin (before first chat)
A string subclass that auto-renders as Markdown in Jupyter notebooks.
load_ipython_extension(ipython)- Called by%load_ext sysopunload_ipython_extension(ipython)- Called by%unload_ext sysop
git clone https://github.com/NavigatorBBS/sysop.git
cd sysop
pip install -e ".[dev]"pytest tests/ -v# Format code
black src/ tests/ examples/
isort src/ tests/ examples/
# Check style
flake8 src/ tests/ examples/ --max-line-length=100Contributions are welcome! Please see CONTRIBUTING.md for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Built on GitHub Copilot SDK
- Inspired by the need for AI-assisted data science workflows
- Documentation: https://github.com/NavigatorBBS/sysop/wiki
- Issues: https://github.com/NavigatorBBS/sysop/issues
- PyPI: https://pypi.org/project/sysop/ (coming soon)
- Python 3.10 or higher
- GitHub Copilot subscription and access token
- JupyterLab 4.0+ or IPython 8.0+
- Tools/plugins must be registered before the first
chat()call - Session creation is lazy (initialized on first use)
- Requires valid GitHub Copilot PAT with appropriate scopes
- Core
NotebookChatAgentwith GitHub Copilot SDK integration - IPython extension for seamless Jupyter integration
- Auto-rendering markdown responses
- Conversation history management
- Custom tool support via
@define_tool - Async-first API design
Made with ❤️ by Christopher Landry