Skip to main content

bsy-clippy

bsy-clippy is a lightweight Python client for the OpenAI Chat Completions API (and compatible deployments).

It supports both batch (stdin) mode for one-shot prompts and interactive mode for chatting directly in the terminal.
You can also load system prompts from a file to guide the LLM’s behavior.


Features

  • Speaks to the OpenAI Chat Completions API or any OpenAI-compatible deployment.
  • Loads credentials from .env (OPENAI_API_KEY) via python-dotenv when the selected profile requires them.
  • Reads defaults (profile, provider, base URL, model) from bsy-clippy.yaml and falls back to a packaged sample if none is found.
  • Switch profiles by editing api.profile or passing --profile (e.g. --profile openai) on the CLI.
  • Defaults to:
    • Provider: ollama
    • Base URL: http://172.20.0.100:11434
    • Model: qwen3:1.7b
    • Mode: stream (see --mode to switch)
    • Bundled system prompt file that can be overridden with --system-file
  • Configurable parameters:
    • --config / --profile → select a profile file and profile name
    • -b / --base-url, -i / --ip, -p / --port → override connection details per run
    • -M / --model, -t / --temperature, -m / --mode → tuning controls
    • -s / --system-file, -u / --user-prompt → additional prompting knobs
    • -r / --memory-lines, -c / --chat-after-stdin → conversation persistence options (interactive mode remembers 12 entries by default)
  • Two modes of operation:
    • Batch mode → waits until the answer is complete, then prints only the final result.
    • Stream mode (default) → shows response in real-time, tokens appear as they are generated.
  • Colored terminal output:
    • Yellow = streaming tokens (the model’s “thinking” in progress).
    • Default terminal color = final assembled answer.

Installation

pipx install .

After updating the source, reinstall with pipx reinstall bsy-clippy.

pip / virtual environments

pip install .

To install the latest code directly from GitHub after it is pushed:

pip install --upgrade git+https://github.com/stratosphereips/bsy-clippy.git@main

Configuration

API credentials (.env)

Create a .env file next to where you run bsy-clippy and add your key:

OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk_...

The CLI loads this automatically via python-dotenv; environment variables from your shell work too. The openai profile uses OPENAI_API_KEY, the groq profile uses GROQ_API_KEY, and ollama profiles need no API key. Keep .env out of version control.

YAML defaults (bsy-clippy.yaml)

bsy-clippy.yaml selects which profile to use and what settings belong to it. The CLI looks for this file in the current working directory, then in ~/.config/bsy-clippy/, and finally falls back to the bundled sample. Copy the sample to your project or config directory, edit it, and switch profiles as needed:

api:
  profile: ollama
  profiles:
    ollama:
      provider: ollama
      base_url: http://172.20.0.100:11434
      model: qwen3:1.7b
    # openai:
    #   provider: openai
    #   base_url: https://api.openai.com/v1
    #   model: gpt-4o-mini
    #   api_key_env: OPENAI_API_KEY
    groq:
      provider: openai
      base_url: https://api.groq.com/openai/v1
      model: openai/gpt-oss-120b
      api_key_env: GROQ_API_KEY
    cesnet:
      provider: openai
      base_url: https://chat.ai.e-infra.cz/api
      #model: glm-5.3
      model: mini
      api_key_env: CESNET_API_KEY

Switching profiles

  • Use profile: ollama to talk to an Ollama server; no API token is required. Adjust base_url if your host or port differs.
  • To use OpenAI, either set profile: openai in the file or pass --profile openai on the command line. Make sure the OPENAI_API_KEY environment variable (or the name set in api_key_env) is populated before running the command.
  • To use Groq, add GROQ_API_KEY to .env or your shell and select --profile groq. The repository config selects this profile by default.
  • For CESNET/e-INFRA CZ, set CESNET_API_KEY and select --profile cesnet. The CLI maps the configured https://chat.ai.e-infra.cz/api URL to the current API endpoint, https://llm.ai.e-infra.cz/v1.
  • You can define additional profiles (for example, staging clusters) under api.profiles and select them with --profile <name>.

Quick check

pip install -r requirements.txt          # or pipx install .
cp src/bsy_clippy/data/bsy-clippy.yaml ./bsy-clippy.yaml
python bsy-clippy.py --help              # confirms dependencies are in place

After copying the sample config you can edit it in-place and re-run bsy-clippy to target a different profile. If you installed via pipx or pip, copy the bundled sample with:

python -c "import importlib.resources as r, pathlib; pathlib.Path('bsy-clippy.yaml').write_text(r.files('bsy_clippy').joinpath('data/bsy-clippy.yaml').read_text())"

Usage

System prompt file

By default, bsy-clippy loads a bundled prompt (Be very brief. Be very short.).
You can change this with --system-file or disable it via --no-default-system. The CLI always adds its tool instructions so models know when and how to request a local command.

Example bsy-clippy.txt:

You are a helpful assistant specialized in cybersecurity.
Always explain your reasoning clearly, and avoid unnecessary markdown formatting.

These lines will be sent to the LLM before every user prompt.

User prompt parameter

Use --user-prompt "Classify the following log:" when piping data so the model receives:

system prompt (if any)

user prompt text

data from stdin or interactive input

Interactive memory

Interactive mode remembers the last 12 conversation entries (user, assistant, and tool results) by default. Use --memory-lines 6 (or -r 6) to keep six, or -r 0 to disable memory. Only the final assistant reply and tool results are stored; thinking traces are not.

Local command tool

When a request needs information from this machine, the model can request a command. The CLI displays it and asks Execute command? [y/N]: before running it. The command output is sent back to the model so it can answer in the same turn. A declined or blocked command is reported back as well. Up to three commands can run in one turn. Piped input without an interactive terminal cannot approve commands.

Chat after stdin

Use -c / --chat-after-stdin to process piped data first and then remain in interactive mode with the response (and any configured memory) available:

cat sample.txt | bsy-clippy -u "Summarize this report" -r 6 -c

After the initial answer prints, you can continue the conversation while the tool remembers the piped data and the model’s reply.


Interactive mode (default = stream)

Run without piping input:

bsy-clippy

Streaming session looks like:

You: Hello!
LLM (thinking): <think>
Reasoning step by step...
</think>
Hello! How can I assist you today? 😊

Prefer a single print at the end? Switch to batch mode:

bsy-clippy --mode batch

Batch output:

You: Hello!
Hello! How can I assist you today? 😊

Batch mode (stdin)

Pipe input directly:

echo "Tell me a joke" | bsy-clippy

Output:

Why don’t scientists trust atoms? Because they make up everything!

Forcing modes

bsy-clippy --mode batch
bsy-clippy --mode stream

Adjusting temperature

bsy-clippy --temperature 0.2
bsy-clippy --temperature 1.2

Custom server and model

bsy-clippy --profile ollama --base-url http://127.0.0.1:11434 --model llama2

Requirements

See requirements.txt.

Metadata

Release files for bsy-clippy 0.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bsy-clippy 0.3.5
File Size Uploaded Provenance Actions
bsy_clippy-0.3.5.tar.gz 27.4 kB Without provenance Details for bsy_clippy-0.3.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bsy-clippy 0.3.5
File Interpreter ABI Platform Actions
bsy_clippy-0.3.5-py3-none-any.whl Python 3 none any Details for bsy_clippy-0.3.5-py3-none-any.whl

Total release size: 51.6 kB

Release files / bsy_clippy-0.3.5.tar.gz

Download URL bsy_clippy-0.3.5.tar.gz
Size 27.4 kB
Tags Source
SHA-256 checksum
How to use checksums
d69e6458903353ad8a8f13bc0d223a665c208fdd2eb3a41103c75654f176106e
BLAKE2b-256 checksum
How to use checksums
2c7c15c272341117bceab4b266bd17dd20b9cbba38a81d5cfcf1b7a24956b23d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Release files / bsy_clippy-0.3.5-py3-none-any.whl

Download URL bsy_clippy-0.3.5-py3-none-any.whl
Size 24.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4fa07942f7e18377249f263085579e52f917a00bb3fa0e56e5988414959e1818
BLAKE2b-256 checksum
How to use checksums
524c42f0603b324cab04e989315040c497e86ef1e1d81cdfd714ec84d8606608
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Security for bsy-clippy 0.3.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page