seer-ai 1.0.0__tar.gz

seer_ai-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Build & Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/seer-ai/
+
+    permissions:
+      id-token: write   # required for Trusted Publishing (OIDC)
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

seer_ai-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+dist/
+*.egg-info/
+.vscode/

seer_ai-1.0.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: seer-ai
+Version: 1.0.0
+Summary: SEER - Shell Enhanced Execution & Reasoning
+Project-URL: Homepage, https://github.com/zeddius1983/seer
+Project-URL: Repository, https://github.com/zeddius1983/seer
+Project-URL: Issues, https://github.com/zeddius1983/seer/issues
+License: MIT
+Keywords: ai,assistant,llm,shell,terminal
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# SEER - Shell Enhanced Execution & Reasoning
+
+![Built with AI assistance](https://img.shields.io/badge/Built%20with-AI%20assistance-blueviolet?logo=openai&logoColor=white)
+
+LLM-powered assistant for your terminal. Get contextual help from your local or cloud LLM based on what just happened in your shell — errors, failed commands, unexpected output.
+
+Inspired by [PEEL](https://github.com/lemonade-sdk/peel) for PowerShell.
+
+**Supported platforms:** macOS, Linux  
+**Supported shells:** zsh, bash
+
+```
+$ git pull-request
+git: 'pull-request' is not a git command. See 'git --help'.
+
+$ seer help
+The command `git pull-request` is not valid. Use `git pull` to fetch and
+merge, or install the `gh` CLI and run `gh pr create` to open a pull request.
+```
+
+---
+
+## How it works
+
+Shell hooks (`PROMPT_COMMAND` / `precmd`) save your terminal's scrollback after every command. When you run `seer help`, the saved context is sent to your LLM of choice. No copy-pasting, no switching windows.
+
+With tmux, the full screen output (including stderr) is captured. Without tmux, the last command and exit code are saved as fallback.
+
+---
+
+## Installation
+
+### Method 1: Installer (Recommended)
+
+Run directly from GitHub — installs `seer`, sets up shell integration and implicit mode:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash
+```
+
+`uv` is installed automatically if not already present. To install a specific version or branch:
+
+```bash
+# By version tag
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version v1.1.0
+
+# By branch
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version feature/v1.1.0
+```
+
+`--version` accepts any git ref (tag, branch, or SHA). It can be combined with other flags:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version v1.1.0 --all
+```
+
+> **Note:** Whenever `~/.zshrc` is modified, a backup is created first as `~/.zshrc.YYYYMMDD_HHMMSS.bak`.
+
+### Method 2: Build from source
+
+```bash
+git clone https://github.com/zeddius1983/seer
+cd seer
+uv tool install .
+```
+
+---
+
+## Uninstallation
+
+If you installed via the **installer** (Method 1):
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --uninstall
+```
+
+---
+
+## Usage
+
+### Implicit Mode (Ctrl+Space)
+
+Implicit mode is installed automatically with seer. Type any question directly into your terminal and press `Ctrl+Space`:
+
+```bash
+find the largest file in this folder[Press Ctrl+Space]
+# Instantly expands and runs: seer find the largest file in this folder
+```
+
+### Standard Commands
+
+```bash
+# Explain what just went wrong
+seer help
+
+# Ask anything shell-related
+seer how to list all datasets in a ZFS pool
+seer what does SIGKILL mean
+seer how do I find which process is using port 8080
+
+# Let seer do it — generates a command, shows it, asks before running
+seer do find the largest file in ~/Downloads
+seer do show disk usage by folder in /var
+seer do list all listening ports
+
+# Tip: quote the task if it contains apostrophes or special characters
+seer do "show all files modified in the last week"
+seer do "find the largest file and show it's size in MB"
+
+# Pipe output directly (no shell hook needed)
+kubectl get pods 2>&1 | seer
+journalctl -xe | seer why is nginx failing
+
+# Skip context, ask a clean question
+seer --no-context explain the difference between hard and soft links
+
+# Raw output — no glow or rich rendering
+seer --raw how do I list open ports
+seer -r help
+
+# Use a specific provider or model for one query
+seer -p anthropic help
+seer -p openai -m gpt-4o how do I list listening ports
+```
+
+### Subcommands
+
+| Command | Description |
+|---|---|
+| `seer help` | Analyse your last terminal output and explain errors |
+| `seer do <task>` | Generate a shell command, preview it, confirm before running |
+| `seer config` | Show the active config file, or create a default one |
+| `seer --context` | Show the full system prompt and captured terminal context |
+| `seer --stats` | Show provider, model, context size, and system info |
+
+### Flags
+
+| Flag | Short | Description |
+|---|---|---|
+| `--no-context` | | Skip attaching terminal context |
+| `--raw` | `-r` | Disable glow and rich rendering, stream plain text |
+| `--provider <name>` | `-p` | Override the active provider for this query |
+| `--model <name>` | `-m` | Override the model for this query |
+
+---
+
+## Configuration
+
+Generate the default config file:
+```bash
+seer config
+```
+
+This creates `~/.config/seer/config.yaml`:
+
+```yaml
+provider: lmstudio        # active provider
+
+providers:
+  lmstudio:               # LM Studio (or any OpenAI-compatible local server)
+    type: openai
+    base_url: http://localhost:1234/v1
+    api_key: lmstudio
+    model: google/gemma-3-4b
+
+  ollama:
+    type: openai
+    base_url: http://localhost:11434/v1
+    api_key: ollama
+    model: llama3.2
+
+  openai:
+    type: openai
+    model: gpt-4o
+    api_key: sk-...       # or set OPENAI_API_KEY env var
+
+  anthropic:
+    type: anthropic
+    model: claude-sonnet-4-6
+    api_key: sk-ant-...   # or set ANTHROPIC_API_KEY env var
+
+  # Any OpenAI-compatible endpoint (vLLM, llama.cpp, etc.)
+  custom:
+    type: openai
+    base_url: http://myserver:8080/v1
+    api_key: none
+    model: my-model
+```
+
+---
+
+## Supported providers
+
+| Provider | `type` | Notes |
+|---|---|---|
+| [LM Studio](https://lmstudio.ai) | `openai` | Default. Set `base_url: http://localhost:1234/v1` |
+| [Ollama](https://ollama.com) | `openai` | Set `base_url: http://localhost:11434/v1` |
+| [vLLM](https://github.com/vllm-project/vllm) | `openai` | Set `base_url: http://localhost:8000/v1` |
+| [llama.cpp](https://github.com/ggerganov/llama.cpp) | `openai` | Set `base_url: http://localhost:8080/v1` |
+| [OpenAI](https://platform.openai.com) | `openai` | Set `OPENAI_API_KEY` |
+| [Anthropic](https://anthropic.com) | `anthropic` | Set `ANTHROPIC_API_KEY` |
+| Any OpenAI-compatible endpoint | `openai` | Set `base_url` to your server |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/zeddius1983/seer
+cd seer
+
+# Install dev environment
+uv sync
+
+# Run directly without installing
+.venv/bin/seer --help
+
+# Build a wheel
+uv build
+# → dist/seer-1.0.0-py3-none-any.whl
+```
+
+

seer_ai-1.0.0/README.md

@@ -0,0 +1,222 @@
+# SEER - Shell Enhanced Execution & Reasoning
+
+![Built with AI assistance](https://img.shields.io/badge/Built%20with-AI%20assistance-blueviolet?logo=openai&logoColor=white)
+
+LLM-powered assistant for your terminal. Get contextual help from your local or cloud LLM based on what just happened in your shell — errors, failed commands, unexpected output.
+
+Inspired by [PEEL](https://github.com/lemonade-sdk/peel) for PowerShell.
+
+**Supported platforms:** macOS, Linux  
+**Supported shells:** zsh, bash
+
+```
+$ git pull-request
+git: 'pull-request' is not a git command. See 'git --help'.
+
+$ seer help
+The command `git pull-request` is not valid. Use `git pull` to fetch and
+merge, or install the `gh` CLI and run `gh pr create` to open a pull request.
+```
+
+---
+
+## How it works
+
+Shell hooks (`PROMPT_COMMAND` / `precmd`) save your terminal's scrollback after every command. When you run `seer help`, the saved context is sent to your LLM of choice. No copy-pasting, no switching windows.
+
+With tmux, the full screen output (including stderr) is captured. Without tmux, the last command and exit code are saved as fallback.
+
+---
+
+## Installation
+
+### Method 1: Installer (Recommended)
+
+Run directly from GitHub — installs `seer`, sets up shell integration and implicit mode:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash
+```
+
+`uv` is installed automatically if not already present. To install a specific version or branch:
+
+```bash
+# By version tag
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version v1.1.0
+
+# By branch
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version feature/v1.1.0
+```
+
+`--version` accepts any git ref (tag, branch, or SHA). It can be combined with other flags:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version v1.1.0 --all
+```
+
+> **Note:** Whenever `~/.zshrc` is modified, a backup is created first as `~/.zshrc.YYYYMMDD_HHMMSS.bak`.
+
+### Method 2: Build from source
+
+```bash
+git clone https://github.com/zeddius1983/seer
+cd seer
+uv tool install .
+```
+
+---
+
+## Uninstallation
+
+If you installed via the **installer** (Method 1):
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --uninstall
+```
+
+---
+
+## Usage
+
+### Implicit Mode (Ctrl+Space)
+
+Implicit mode is installed automatically with seer. Type any question directly into your terminal and press `Ctrl+Space`:
+
+```bash
+find the largest file in this folder[Press Ctrl+Space]
+# Instantly expands and runs: seer find the largest file in this folder
+```
+
+### Standard Commands
+
+```bash
+# Explain what just went wrong
+seer help
+
+# Ask anything shell-related
+seer how to list all datasets in a ZFS pool
+seer what does SIGKILL mean
+seer how do I find which process is using port 8080
+
+# Let seer do it — generates a command, shows it, asks before running
+seer do find the largest file in ~/Downloads
+seer do show disk usage by folder in /var
+seer do list all listening ports
+
+# Tip: quote the task if it contains apostrophes or special characters
+seer do "show all files modified in the last week"
+seer do "find the largest file and show it's size in MB"
+
+# Pipe output directly (no shell hook needed)
+kubectl get pods 2>&1 | seer
+journalctl -xe | seer why is nginx failing
+
+# Skip context, ask a clean question
+seer --no-context explain the difference between hard and soft links
+
+# Raw output — no glow or rich rendering
+seer --raw how do I list open ports
+seer -r help
+
+# Use a specific provider or model for one query
+seer -p anthropic help
+seer -p openai -m gpt-4o how do I list listening ports
+```
+
+### Subcommands
+
+| Command | Description |
+|---|---|
+| `seer help` | Analyse your last terminal output and explain errors |
+| `seer do <task>` | Generate a shell command, preview it, confirm before running |
+| `seer config` | Show the active config file, or create a default one |
+| `seer --context` | Show the full system prompt and captured terminal context |
+| `seer --stats` | Show provider, model, context size, and system info |
+
+### Flags
+
+| Flag | Short | Description |
+|---|---|---|
+| `--no-context` | | Skip attaching terminal context |
+| `--raw` | `-r` | Disable glow and rich rendering, stream plain text |
+| `--provider <name>` | `-p` | Override the active provider for this query |
+| `--model <name>` | `-m` | Override the model for this query |
+
+---
+
+## Configuration
+
+Generate the default config file:
+```bash
+seer config
+```
+
+This creates `~/.config/seer/config.yaml`:
+
+```yaml
+provider: lmstudio        # active provider
+
+providers:
+  lmstudio:               # LM Studio (or any OpenAI-compatible local server)
+    type: openai
+    base_url: http://localhost:1234/v1
+    api_key: lmstudio
+    model: google/gemma-3-4b
+
+  ollama:
+    type: openai
+    base_url: http://localhost:11434/v1
+    api_key: ollama
+    model: llama3.2
+
+  openai:
+    type: openai
+    model: gpt-4o
+    api_key: sk-...       # or set OPENAI_API_KEY env var
+
+  anthropic:
+    type: anthropic
+    model: claude-sonnet-4-6
+    api_key: sk-ant-...   # or set ANTHROPIC_API_KEY env var
+
+  # Any OpenAI-compatible endpoint (vLLM, llama.cpp, etc.)
+  custom:
+    type: openai
+    base_url: http://myserver:8080/v1
+    api_key: none
+    model: my-model
+```
+
+---
+
+## Supported providers
+
+| Provider | `type` | Notes |
+|---|---|---|
+| [LM Studio](https://lmstudio.ai) | `openai` | Default. Set `base_url: http://localhost:1234/v1` |
+| [Ollama](https://ollama.com) | `openai` | Set `base_url: http://localhost:11434/v1` |
+| [vLLM](https://github.com/vllm-project/vllm) | `openai` | Set `base_url: http://localhost:8000/v1` |
+| [llama.cpp](https://github.com/ggerganov/llama.cpp) | `openai` | Set `base_url: http://localhost:8080/v1` |
+| [OpenAI](https://platform.openai.com) | `openai` | Set `OPENAI_API_KEY` |
+| [Anthropic](https://anthropic.com) | `anthropic` | Set `ANTHROPIC_API_KEY` |
+| Any OpenAI-compatible endpoint | `openai` | Set `base_url` to your server |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/zeddius1983/seer
+cd seer
+
+# Install dev environment
+uv sync
+
+# Run directly without installing
+.venv/bin/seer --help
+
+# Build a wheel
+uv build
+# → dist/seer-1.0.0-py3-none-any.whl
+```
+
+

seer_ai-1.0.0/ROADMAP.md

@@ -0,0 +1,141 @@
+# SEER Roadmap
+
+---
+
+## v1.0.0 — Initial Release ✅
+
+**Shell Integration**
+- zsh and bash support via shell hooks (`precmd` / `PROMPT_COMMAND`)
+- Implicit mode: type a question at the prompt and press `Ctrl+Space` to invoke seer
+- Installer script with automatic `uv` setup and shell integration
+- Uninstall / setup menu
+
+**Context Capture**
+- tmux pane capture (full scrollback, takes priority)
+- Hook-based fallback: last command + exit code
+- Shell history fallback
+- Piped input support (`cmd 2>&1 | seer`)
+
+**Error Analysis Mode (`seer help`)**
+- Automatic error detection from terminal context
+- System info auto-population (OS, CPU arch, shell, package managers)
+- Responses tailored to the user's platform
+
+**Command Generation Mode (`seer do`)**
+- Natural language → shell command with syntax highlighting
+- Safety warnings for destructive or privileged commands
+- macOS vs Linux compatibility warnings
+- Inline edit before execution (`e` key)
+- Confirmation prompt (`[Y/n/e]`) before running
+
+**Output Rendering**
+- `glow` integration for rendered Markdown (host-side)
+- `rich` Live streaming fallback
+- `--raw` / `-r` flag for plain text output
+
+**Multi-Provider Support**
+- LM Studio (OpenAI-compatible, local)
+- Ollama (OpenAI-compatible, local)
+- OpenAI
+- Anthropic
+- Custom OpenAI-compatible endpoints
+
+**Diagnostics**
+- `seer info` — active provider, model, context stats, system specs
+- `seer config` — print config path and contents
+
+---
+
+## v1.1.0 — Provider Autoconfig 🔜
+
+Introduce `auto` as a valid value for both `provider` and `model`, removing the need for manual configuration on machines running local LLM servers.
+
+**`provider: auto`**
+- At startup, probe each configured provider in order
+- Select the first provider that responds successfully
+- Probe method: attempt to list models via the provider's API
+
+**`model: auto`**
+- When a provider's model is set to `auto`, query its model list endpoint
+- Select the first available model returned
+
+**Updated default config**
+- Ships with llama.cpp, LM Studio, and Ollama pre-configured
+- All three default to `model: auto`
+- Top-level `provider` defaults to `auto`
+
+```yaml
+provider: auto
+context_lines: 100
+providers:
+  llamacpp:
+    type: openai
+    base_url: http://127.0.0.1:8080/v1
+    api_key: llamacpp
+    model: auto
+  lmstudio:
+    type: openai
+    base_url: http://127.0.0.1:1234/v1
+    api_key: lmstudio
+    model: auto
+  ollama:
+    type: openai
+    base_url: http://localhost:11434/v1
+    api_key: ollama
+    model: auto
+```
+
+---
+
+## v1.2.0 — Brave Mode & Pipe-Aware Output 🔜
+
+### Brave Mode
+
+An autonomous execution mode where seer plans the necessary commands, runs them, and returns an interpreted result — rather than suggesting a command for the user to run manually.
+
+**Example:** `seer find the largest file here` → seer runs `find` + `du` + `sort`, captures output, and responds with a human-readable answer.
+
+**Mode system**
+
+A new top-level `mode` config key controls the default behaviour:
+
+| Value | Behaviour |
+|---|---|
+| `default` | Current behaviour — suggest commands, never execute autonomously |
+| `brave` | Always use brave mode — plan, execute, interpret |
+| `auto` | seer infers the desired mode from the query (e.g. questions → brave, `do`-style tasks → default) |
+
+```yaml
+mode: auto   # default | brave | auto
+```
+
+**Per-invocation override**
+
+`--brave` / `-b` flag forces brave mode for a single query regardless of config:
+
+```
+seer --brave find the largest file here
+seer -b what is eating my disk space
+```
+
+**Execution model**
+- LLM receives the query and generates a plan (sequence of shell commands)
+- seer executes each command and feeds stdout/stderr back to the LLM
+- Before any write or destructive command, seer pauses and prompts for confirmation (`[Y/n/e]`)
+- Read-only commands run without interruption
+- LLM produces a final human-readable summary
+- `--raw` / `-r` outputs plain text (no Markdown formatting)
+
+---
+
+### Pipe-Aware Output
+
+When seer's stdout is not a TTY (i.e. the output is being piped), automatically switch to plain text mode:
+- Disable glow and rich rendering
+- Instruct the LLM to respond with factual, unformatted output suitable for further processing
+- Applies to all modes, including brave mode
+
+```
+seer what docker containers are running | grep local
+seer --brave find the largest log file | xargs wc -l
+```