ops-copilot 0.1.0__tar.gz

ops_copilot-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,30 @@
+name: Bug report
+description: Report an investigation, tool execution, SSH, or streaming issue.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: textarea
+    id: scenario
+    attributes:
+      label: Scenario
+      description: What were you trying to investigate?
+    validations:
+      required: true
+  - type: textarea
+    id: tool_config
+    attributes:
+      label: Tool configuration
+      description: Paste a minimal redacted YAML snippet if relevant.
+      render: yaml
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true

ops_copilot-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Suggest a new SRE workflow, tool type, or safety control.
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: workflow
+    attributes:
+      label: Workflow
+      description: Which maintenance or incident workflow would this improve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+    validations:
+      required: true
+  - type: textarea
+    id: safety
+    attributes:
+      label: Safety considerations
+      description: Any command, SSH, secret, or permission risks?

ops_copilot-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "monthly"

ops_copilot-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Summary
+
+## Safety checklist
+
+- [ ] Added or updated tests.
+- [ ] `uv run ruff check .` passes.
+- [ ] `uv run pytest` passes.
+- [ ] No real hostnames, private IPs, credentials, tokens, or internal service names were added.
+- [ ] Tool output is redacted before it reaches the LLM or SSE stream.
+- [ ] New shell commands are narrow, documented, and non-destructive.
+- [ ] Security assumptions are documented when behavior changes.

ops_copilot-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,27 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build package
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

ops_copilot-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Test
+        run: uv run pytest

ops_copilot-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build package
+        run: uv build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

ops_copilot-0.1.0/.github/workflows/smoke.yml

@@ -0,0 +1,23 @@
+name: Smoke
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Run smoke test
+        run: uv run python scripts/smoke.py

ops_copilot-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.env
+.env.*
+!.env.example
+.DS_Store

ops_copilot-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## Unreleased
+
+- Added maintainer documentation, security policy, release process, and issue/PR templates.
+- Added security model, tool-writing, server, and maintenance-workflow documentation.
+- Added local demo and custom tool examples.
+- Added build and manual publish workflows.
+
+## 0.1.0
+
+Initial public release.
+
+- Added SSH client with lazy reconnect and command timeout handling.
+- Added YAML-driven shell tools and injectable custom tool registry.
+- Added LangGraph investigation loop with streaming events.
+- Added FastAPI SSE integration helper.
+- Added input/output sanitization and secret redaction.
+- Added examples, tests, and CI.

ops_copilot-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Thanks for helping improve `ops-copilot`.
+
+## Development setup
+
+`ops-copilot` depends on `langchain-content-normalizer`. Before that package is published to a package index, use the sibling checkout during local development:
+
+```bash
+PYTHONPATH="../langchain-content-normalizer/src" uv run --no-sync ruff check .
+PYTHONPATH="../langchain-content-normalizer/src" uv run --no-sync pytest
+```
+
+Once the dependency is available through the configured Git URL, the normal workflow is:
+
+```bash
+uv sync --dev
+uv run ruff check .
+uv run pytest
+```
+
+## Contribution guidelines
+
+- Treat YAML tool definitions as privileged code.
+- Add tests for every new command renderer, sanitizer, or graph event behavior.
+- Never add real hostnames, credentials, private IPs, or internal service names.
+- Keep tool outputs redacted before they reach the LLM or SSE stream.
+- Prefer narrow, explicit parameters over free-form shell fragments.
+- Document security assumptions in `docs/security-model.md`.
+
+## Useful PRs
+
+- Safer command policy and allowlist validation.
+- Built-in systemd and Docker tool packs.
+- More fake incident fixtures for tests.
+- Better documentation for custom tools and server deployment.

ops_copilot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Jornet
+
+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.

ops_copilot-0.1.0/MAINTAINERS.md

@@ -0,0 +1,21 @@
+# Maintainers
+
+## Primary maintainer
+
+- Benjamin Jornet (`@BenjaminJornet`)
+
+## Maintainer responsibilities
+
+- Review pull requests that add tools, command templates, graph behavior, or server endpoints.
+- Triage issues with redacted YAML snippets and reproduction steps.
+- Maintain the security model for SSH and LLM-driven tool execution.
+- Keep examples runnable without private infrastructure.
+- Publish releases and maintain `CHANGELOG.md`.
+
+## Review priorities
+
+1. No real hostnames, private IPs, credentials, tokens, or internal service names.
+2. Tool output must be redacted before it reaches the LLM or SSE stream.
+3. Shell commands should be narrow, documented, and non-destructive.
+4. New graph/server behaviors need tests.
+5. Security assumptions must be documented.

ops_copilot-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: ops-copilot
+Version: 0.1.0
+Summary: Self-hosted SRE investigation copilot with YAML tools, SSH execution, SSE streaming, and secret redaction.
+Project-URL: Homepage, https://github.com/benjaminjornet/ops-copilot
+Project-URL: Issues, https://github.com/benjaminjornet/ops-copilot/issues
+Author-email: Benjamin Jornet <benjamin.jornet@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Benjamin Jornet
+        
+        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.
+License-File: LICENSE
+Keywords: incident-response,langgraph,llm,ops,sre,ssh
+Classifier: Development Status :: 3 - Alpha
+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
+Requires-Python: >=3.11
+Requires-Dist: asyncssh>=2.14
+Requires-Dist: langchain-content-normalizer>=0.1.0
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langgraph>=0.2
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Provides-Extra: ollama
+Requires-Dist: langchain-community>=0.3; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.2; extra == 'openai'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: sse-starlette>=2; extra == 'server'
+Requires-Dist: uvicorn>=0.32; extra == 'server'
+Description-Content-Type: text/markdown
+
+# ops-copilot
+
+[![CI](https://github.com/BenjaminJornet/ops-copilot/actions/workflows/ci.yml/badge.svg)](https://github.com/BenjaminJornet/ops-copilot/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+Self-hosted SRE investigation copilot for production systems.
+
+`ops-copilot` lets an LLM call tools defined in YAML, execute safe remote commands over SSH, redact secrets from outputs, and stream investigation events through LangGraph or an optional FastAPI SSE server.
+
+## Architecture
+
+```text
+User question -> InvestigationGraph -> LLM -> YAML tools -> SSH host
+                                      <- redacted tool output <- command result
+```
+
+The package is intentionally generic. You can start with shell tools from YAML, then inject custom Python `RemoteTool` classes for richer workflows.
+
+## Install
+
+```bash
+uv add ops-copilot
+```
+
+Optional extras:
+
+```bash
+uv add 'ops-copilot[server]'
+uv add 'ops-copilot[openai]'
+uv add 'ops-copilot[ollama]'
+```
+
+## YAML tools
+
+```yaml
+tools:
+  - name: disk_usage
+    type: shell
+    description: Show filesystem usage.
+    command: df -h
+
+  - name: journalctl_service
+    type: shell
+    description: Show recent logs for a systemd service.
+    command: journalctl -u {service} --since '{since}' --no-pager
+    parameters:
+      service:
+        type: string
+      since:
+        type: string
+        required: false
+        default: "30 minutes ago"
+```
+
+## Minimal usage
+
+```python
+from ops_copilot import InvestigationGraph, SSHClient, ToolRegistry
+
+ssh = SSHClient(host="server.example.com", user="deploy", key_path="~/.ssh/id_ed25519")
+tools = ToolRegistry(ssh, config_path="tools.yaml").load()
+
+graph = InvestigationGraph(
+    llm=your_langchain_chat_model,
+    tools=tools,
+    system_prompt="You are an SRE copilot. Investigate safely and report evidence.",
+)
+
+async for event in graph.stream("The API is slow. What should I check?"):
+    print(event)
+```
+
+## Streaming events
+
+`InvestigationGraph.stream()` yields dictionaries with these event names:
+
+| Event | Meaning |
+| --- | --- |
+| `token` | streamed model text |
+| `tool_start` | tool call started with input and step id |
+| `tool_end` | tool call finished with redacted output |
+| `error` | graph or stream error |
+| `done` | investigation complete |
+
+## Optional FastAPI server
+
+The `ops_copilot.server.create_app()` helper exposes:
+
+- `POST /investigate`
+- `POST /investigate/stream`
+
+If `OPS_COPILOT_API_KEY` is set, clients must send `X-API-Key`.
+
+## Security notes
+
+This project executes commands on servers you control. Treat `tools.yaml` as privileged code.
+
+Recommendations:
+
+- Use SSH key auth with least-privilege users.
+- Review every command template before exposing it to an LLM.
+- Avoid destructive commands in YAML.
+- Keep parameterized commands narrow.
+- Store no secrets in YAML or prompts.
+- Rely on built-in redaction as a safety net, not as your only control.
+
+Built-in redaction covers env-style secret lines, Bearer tokens, OpenAI-style keys, JWTs, long hex runs, and inline image data URLs.
+
+## Documentation and examples
+
+- `docs/security-model.md` documents threat boundaries and deployment controls.
+- `docs/writing-tools.md` explains YAML and custom Python tools.
+- `docs/server.md` covers the optional FastAPI/SSE integration.
+- `docs/maintenance-workflows.md` describes maintainer workflows and review checklists.
+- `examples/local_demo.py` runs without a real SSH host using fake outputs.
+- `examples/custom_tool.py` shows how to inject a custom `RemoteTool` class.
+
+## Roadmap
+
+- Command allowlist validation for shell tools.
+- Built-in Docker and systemd tool packs.
+- Persistent investigation sessions.
+- Audit log export.
+- More fake incident fixtures for regression tests.
+
+## Development
+
+```bash
+uv sync --dev
+uv run ruff check .
+uv run pytest
+uv run python scripts/smoke.py
+```
+
+## License
+
+MIT

ops_copilot-0.1.0/README.md

@@ -0,0 +1,138 @@
+# ops-copilot
+
+[![CI](https://github.com/BenjaminJornet/ops-copilot/actions/workflows/ci.yml/badge.svg)](https://github.com/BenjaminJornet/ops-copilot/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+Self-hosted SRE investigation copilot for production systems.
+
+`ops-copilot` lets an LLM call tools defined in YAML, execute safe remote commands over SSH, redact secrets from outputs, and stream investigation events through LangGraph or an optional FastAPI SSE server.
+
+## Architecture
+
+```text
+User question -> InvestigationGraph -> LLM -> YAML tools -> SSH host
+                                      <- redacted tool output <- command result
+```
+
+The package is intentionally generic. You can start with shell tools from YAML, then inject custom Python `RemoteTool` classes for richer workflows.
+
+## Install
+
+```bash
+uv add ops-copilot
+```
+
+Optional extras:
+
+```bash
+uv add 'ops-copilot[server]'
+uv add 'ops-copilot[openai]'
+uv add 'ops-copilot[ollama]'
+```
+
+## YAML tools
+
+```yaml
+tools:
+  - name: disk_usage
+    type: shell
+    description: Show filesystem usage.
+    command: df -h
+
+  - name: journalctl_service
+    type: shell
+    description: Show recent logs for a systemd service.
+    command: journalctl -u {service} --since '{since}' --no-pager
+    parameters:
+      service:
+        type: string
+      since:
+        type: string
+        required: false
+        default: "30 minutes ago"
+```
+
+## Minimal usage
+
+```python
+from ops_copilot import InvestigationGraph, SSHClient, ToolRegistry
+
+ssh = SSHClient(host="server.example.com", user="deploy", key_path="~/.ssh/id_ed25519")
+tools = ToolRegistry(ssh, config_path="tools.yaml").load()
+
+graph = InvestigationGraph(
+    llm=your_langchain_chat_model,
+    tools=tools,
+    system_prompt="You are an SRE copilot. Investigate safely and report evidence.",
+)
+
+async for event in graph.stream("The API is slow. What should I check?"):
+    print(event)
+```
+
+## Streaming events
+
+`InvestigationGraph.stream()` yields dictionaries with these event names:
+
+| Event | Meaning |
+| --- | --- |
+| `token` | streamed model text |
+| `tool_start` | tool call started with input and step id |
+| `tool_end` | tool call finished with redacted output |
+| `error` | graph or stream error |
+| `done` | investigation complete |
+
+## Optional FastAPI server
+
+The `ops_copilot.server.create_app()` helper exposes:
+
+- `POST /investigate`
+- `POST /investigate/stream`
+
+If `OPS_COPILOT_API_KEY` is set, clients must send `X-API-Key`.
+
+## Security notes
+
+This project executes commands on servers you control. Treat `tools.yaml` as privileged code.
+
+Recommendations:
+
+- Use SSH key auth with least-privilege users.
+- Review every command template before exposing it to an LLM.
+- Avoid destructive commands in YAML.
+- Keep parameterized commands narrow.
+- Store no secrets in YAML or prompts.
+- Rely on built-in redaction as a safety net, not as your only control.
+
+Built-in redaction covers env-style secret lines, Bearer tokens, OpenAI-style keys, JWTs, long hex runs, and inline image data URLs.
+
+## Documentation and examples
+
+- `docs/security-model.md` documents threat boundaries and deployment controls.
+- `docs/writing-tools.md` explains YAML and custom Python tools.
+- `docs/server.md` covers the optional FastAPI/SSE integration.
+- `docs/maintenance-workflows.md` describes maintainer workflows and review checklists.
+- `examples/local_demo.py` runs without a real SSH host using fake outputs.
+- `examples/custom_tool.py` shows how to inject a custom `RemoteTool` class.
+
+## Roadmap
+
+- Command allowlist validation for shell tools.
+- Built-in Docker and systemd tool packs.
+- Persistent investigation sessions.
+- Audit log export.
+- More fake incident fixtures for regression tests.
+
+## Development
+
+```bash
+uv sync --dev
+uv run ruff check .
+uv run pytest
+uv run python scripts/smoke.py
+```
+
+## License
+
+MIT

ops_copilot-0.1.0/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest minor release receives security fixes while the project is pre-1.0.
+
+## Reporting a vulnerability
+
+Please open a private GitHub security advisory if available, or contact the maintainer through GitHub.
+
+## Security model summary
+
+`ops-copilot` executes commands over SSH on systems you control. The project reduces accidental exposure with secret redaction, input/output sanitizers, and explicit tool definitions, but it does not make arbitrary shell commands safe.
+
+Review `docs/security-model.md` before deploying the server or exposing tools to an LLM.

ops_copilot-0.1.0/docs/maintenance-workflows.md

@@ -0,0 +1,30 @@
+# Maintenance Workflows
+
+`ops-copilot` is designed to be maintained with the same workflows it supports: structured investigation, explicit tools, safety review, and repeatable releases.
+
+## Codex-assisted maintenance use cases
+
+- Review pull requests that add YAML tools or custom `RemoteTool` classes.
+- Generate edge-case tests for command rendering and redaction.
+- Review SSH and command-execution safety boundaries.
+- Draft release notes from merged changes.
+- Triage issues by reproducing reported tool configurations against fake SSH clients.
+- Improve documentation for operational workflows.
+
+## Review checklist for tool PRs
+
+- Is the command read-only or clearly documented?
+- Are parameters narrow and typed?
+- Could a parameter inject arbitrary shell syntax?
+- Is output redacted before it reaches the graph or stream?
+- Is there a test for the command template?
+- Does the README or docs explain the workflow?
+
+## Release checklist
+
+- Run `uv run ruff check .`.
+- Run `uv run pytest`.
+- Scan source files for hostnames, private IPs, credentials, and client-specific names.
+- Update `CHANGELOG.md`.
+- Tag the release.
+- Publish release notes.