agentirc 1.0.0__tar.gz

agentirc-1.0.0/.dockerignore

@@ -0,0 +1,10 @@
+.venv
+__pycache__
+*.pyc
+.env
+*.enc
+.git
+.pytest_cache
+.claude
+tests
+docs

agentirc-1.0.0/.env.example

@@ -0,0 +1,40 @@
+IRC_HOST=irc.rizon.net
+IRC_PORT=6667
+IRC_NICK=mybot
+IRC_USER=mybot
+IRC_REALNAME=My IRC Bot
+IRC_CHANNELS=#general,#bots
+IRC_PASSWORD=
+IRC_USE_TLS=false
+IRC_CMD_PREFIX=!
+
+# AI agent provider settings (used by: python -m agentirc)
+OPENAI_API_BASE=https://api.openai.com
+OPENAI_API_KEY=
+OPENAI_MODELS=
+
+XAI_API_BASE=https://api.x.ai/v1
+XAI_API_KEY=
+XAI_MODELS=
+
+LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
+LMSTUDIO_API_KEY=
+LMSTUDIO_MODELS=
+
+DEFAULT_MODEL=gpt-5-mini
+AGENTIRC_TOOLS=web_search,x_search,code_interpreter,mcp
+AGENTIRC_MCP_SERVERS=[]
+AGENTIRC_ADMINS=
+AGENTIRC_SERVER_MODELS=true
+AGENTIRC_DEFAULT_PERSONALITY="a helpful agentic chatbot named agentirc."
+AGENTIRC_PROMPT_PREFIX="You are "
+AGENTIRC_PROMPT_SUFFIX=".  Roleplay and never break character.  Do not use markdown or lists in your responses, this is a text-only environment."
+AGENTIRC_PROMPT_SUFFIX_EXTRA=" Keep responses concise, around 400 characters.  Do not output a character count."
+AGENTIRC_MAX_TOKENS=1024
+
+# Search country bias for web_search tool (ISO 3166-1 alpha-2 code, e.g. US)
+WEB_SEARCH_COUNTRY=
+
+# Fernet encryption key for persisting conversation history across restarts.
+# Generate one with: python -m agentirc --generate-key
+HISTORY_ENCRYPTION_KEY=

agentirc-1.0.0/.github/workflows/dockerhub.yml

@@ -0,0 +1,49 @@
+name: Publish to Docker Hub
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: h1ddenpr0cess20/agentirc
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

agentirc-1.0.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentirc-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+.env
+*.enc
+.venv
+.pytest_cache

agentirc-1.0.0/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY ircbot/ ircbot/
+COPY agentirc/ agentirc/
+
+RUN pip install --no-cache-dir '.[crypto]'
+
+CMD ["agentirc"]

agentirc-1.0.0/LICENSE

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

agentirc-1.0.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: agentirc
+Version: 1.0.0
+Summary: AI-powered IRC agent with multi-provider LLM support
+Project-URL: Homepage, https://github.com/h1ddenpr0cess20/agentirc
+Project-URL: Repository, https://github.com/h1ddenpr0cess20/agentirc
+Project-URL: Issues, https://github.com/h1ddenpr0cess20/agentirc/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,bot,chatbot,irc,llm,ollama,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: crypto
+Requires-Dist: cryptography>=43; extra == 'crypto'
+Description-Content-Type: text/markdown
+
+# agentirc
+
+An AI-powered IRC agent built on a minimal async IRC bot framework. Supports multiple LLM providers (OpenAI, xAI, LM Studio) with per-user conversation history, tool use, and encrypted persistence.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [CLI Options](#cli-options)
+- [Commands](#commands)
+- [Documentation](#documentation)
+- [License](#license)
+
+## Quick Start
+
+```bash
+git clone <repo-url>
+cd agentirc
+cp .env.example .env
+# Edit .env with your IRC server, nick, and at least one API provider
+pip install .
+agentirc
+```
+
+Or with Docker:
+
+```bash
+cp .env.example .env
+# Edit .env
+docker compose up -d
+```
+
+> **Requirements:** Python 3.10+, `httpx`, and optionally `cryptography` for encrypted history persistence.
+
+## CLI Options
+
+```
+agentirc [options]
+```
+
+| Flag | Description |
+|---|---|
+| `--env-file PATH` | Path to .env file (default: `.env`) |
+| `--debug` | Enable debug logging |
+| `--host HOST` | IRC server hostname (overrides `IRC_HOST`) |
+| `--port PORT` | IRC server port (overrides `IRC_PORT`) |
+| `--nick NICK` | Bot nickname (overrides `IRC_NICK`) |
+| `--channels CHANS` | Comma-separated channels (overrides `IRC_CHANNELS`) |
+| `--tls` | Connect with TLS (overrides `IRC_USE_TLS`) |
+| `--model MODEL` | Default model (overrides `DEFAULT_MODEL`) |
+| `--generate-key` | Generate a Fernet encryption key and exit |
+
+CLI flags override their corresponding environment variables.
+
+## Commands
+
+### User Commands
+
+| Command | Aliases | Description |
+|---|---|---|
+| `!ai <message>` | `!chat`, `!ask` | Talk to the AI |
+| `!persona <text>` | | Set a persona and reintroduce |
+| `!custom <prompt>` | | Set a custom system prompt |
+| `!reset` | | Reset conversation to defaults |
+| `!stock` | | Reset conversation with no system prompt |
+| `!mymodel [name]` | | Show or set your model |
+| `!location <place>` | | Set your location for contextual answers |
+| `!x <nick> <message>` | | Talk as another user |
+
+### Admin Commands
+
+| Command | Description |
+|---|---|
+| `!model [name\|reset]` | Show/set global default model |
+| `!tools [on\|off\|toggle\|status]` | Enable/disable tool use |
+| `!verbose [on\|off\|toggle]` | Toggle verbose mode |
+| `!clear` | Clear all conversation state |
+| `!country [on\|off\|status]` | Toggle search country filtering |
+| `!join <#channel>` | Join a channel |
+| `!part [#channel] [reason]` | Leave a channel |
+
+Built-in IRC commands (`!ping`, `!time`, `!help`) are also available.
+
+## Documentation
+
+- [docs/configuration.md](docs/configuration.md) -- IRC and AI provider configuration
+- [docs/commands.md](docs/commands.md) -- command registry and decorator API
+- [docs/extending.md](docs/extending.md) -- subclassing IRCBot, event hooks
+- [docs/ai-agent.md](docs/ai-agent.md) -- AI agent architecture, providers, tools, and history
+- [docs/ai-output-disclaimer.md](docs/ai-output-disclaimer.md) -- AI output disclaimer and conditions of use
+- [docs/not-a-companion.md](docs/not-a-companion.md) -- project scope and intended use
+
+## License
+
+MIT

agentirc-1.0.0/README.md

@@ -0,0 +1,94 @@
+# agentirc
+
+An AI-powered IRC agent built on a minimal async IRC bot framework. Supports multiple LLM providers (OpenAI, xAI, LM Studio) with per-user conversation history, tool use, and encrypted persistence.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [CLI Options](#cli-options)
+- [Commands](#commands)
+- [Documentation](#documentation)
+- [License](#license)
+
+## Quick Start
+
+```bash
+git clone <repo-url>
+cd agentirc
+cp .env.example .env
+# Edit .env with your IRC server, nick, and at least one API provider
+pip install .
+agentirc
+```
+
+Or with Docker:
+
+```bash
+cp .env.example .env
+# Edit .env
+docker compose up -d
+```
+
+> **Requirements:** Python 3.10+, `httpx`, and optionally `cryptography` for encrypted history persistence.
+
+## CLI Options
+
+```
+agentirc [options]
+```
+
+| Flag | Description |
+|---|---|
+| `--env-file PATH` | Path to .env file (default: `.env`) |
+| `--debug` | Enable debug logging |
+| `--host HOST` | IRC server hostname (overrides `IRC_HOST`) |
+| `--port PORT` | IRC server port (overrides `IRC_PORT`) |
+| `--nick NICK` | Bot nickname (overrides `IRC_NICK`) |
+| `--channels CHANS` | Comma-separated channels (overrides `IRC_CHANNELS`) |
+| `--tls` | Connect with TLS (overrides `IRC_USE_TLS`) |
+| `--model MODEL` | Default model (overrides `DEFAULT_MODEL`) |
+| `--generate-key` | Generate a Fernet encryption key and exit |
+
+CLI flags override their corresponding environment variables.
+
+## Commands
+
+### User Commands
+
+| Command | Aliases | Description |
+|---|---|---|
+| `!ai <message>` | `!chat`, `!ask` | Talk to the AI |
+| `!persona <text>` | | Set a persona and reintroduce |
+| `!custom <prompt>` | | Set a custom system prompt |
+| `!reset` | | Reset conversation to defaults |
+| `!stock` | | Reset conversation with no system prompt |
+| `!mymodel [name]` | | Show or set your model |
+| `!location <place>` | | Set your location for contextual answers |
+| `!x <nick> <message>` | | Talk as another user |
+
+### Admin Commands
+
+| Command | Description |
+|---|---|
+| `!model [name\|reset]` | Show/set global default model |
+| `!tools [on\|off\|toggle\|status]` | Enable/disable tool use |
+| `!verbose [on\|off\|toggle]` | Toggle verbose mode |
+| `!clear` | Clear all conversation state |
+| `!country [on\|off\|status]` | Toggle search country filtering |
+| `!join <#channel>` | Join a channel |
+| `!part [#channel] [reason]` | Leave a channel |
+
+Built-in IRC commands (`!ping`, `!time`, `!help`) are also available.
+
+## Documentation
+
+- [docs/configuration.md](docs/configuration.md) -- IRC and AI provider configuration
+- [docs/commands.md](docs/commands.md) -- command registry and decorator API
+- [docs/extending.md](docs/extending.md) -- subclassing IRCBot, event hooks
+- [docs/ai-agent.md](docs/ai-agent.md) -- AI agent architecture, providers, tools, and history
+- [docs/ai-output-disclaimer.md](docs/ai-output-disclaimer.md) -- AI output disclaimer and conditions of use
+- [docs/not-a-companion.md](docs/not-a-companion.md) -- project scope and intended use
+
+## License
+
+MIT

agentirc-1.0.0/agentirc/__init__.py

@@ -0,0 +1,9 @@
+"""agentirc -- AI-powered IRC agent using OpenAI-compatible Responses APIs."""
+
+from .bot import ChatBot
+from .config import ChatConfig
+
+__all__ = [
+    "ChatBot",
+    "ChatConfig",
+]

agentirc-1.0.0/agentirc/__main__.py

@@ -0,0 +1,97 @@
+"""Entry point: python -m agentirc"""
+
+import argparse
+import asyncio
+import logging
+import os
+
+from .config import ChatConfig
+from .bot import ChatBot
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="AI-powered IRC agent")
+    parser.add_argument(
+        "--generate-key",
+        action="store_true",
+        help="Generate a Fernet encryption key for history persistence and exit",
+    )
+    parser.add_argument(
+        "--env-file",
+        metavar="PATH",
+        default=".env",
+        help="Path to .env file (default: .env)",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    parser.add_argument(
+        "--host",
+        metavar="HOST",
+        help="IRC server hostname (overrides IRC_HOST)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        metavar="PORT",
+        help="IRC server port (overrides IRC_PORT)",
+    )
+    parser.add_argument(
+        "--nick",
+        metavar="NICK",
+        help="Bot nickname (overrides IRC_NICK)",
+    )
+    parser.add_argument(
+        "--channels",
+        metavar="CHANS",
+        help="Comma-separated channels to join (overrides IRC_CHANNELS)",
+    )
+    parser.add_argument(
+        "--tls",
+        action="store_true",
+        default=None,
+        help="Connect with TLS (overrides IRC_USE_TLS)",
+    )
+    parser.add_argument(
+        "--model",
+        metavar="MODEL",
+        help="Default model (overrides DEFAULT_MODEL)",
+    )
+    args = parser.parse_args()
+
+    if args.generate_key:
+        from cryptography.fernet import Fernet
+        print(Fernet.generate_key().decode())
+        return
+
+    # Load .env first, then apply CLI overrides (which win via direct set)
+    from ircbot.config import load_env
+    load_env(args.env_file)
+
+    if args.host:
+        os.environ["IRC_HOST"] = args.host
+    if args.port is not None:
+        os.environ["IRC_PORT"] = str(args.port)
+    if args.nick:
+        os.environ["IRC_NICK"] = args.nick
+    if args.channels:
+        os.environ["IRC_CHANNELS"] = args.channels
+    if args.tls:
+        os.environ["IRC_USE_TLS"] = "true"
+    if args.model:
+        os.environ["DEFAULT_MODEL"] = args.model
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.debug else logging.INFO,
+        format="%(asctime)s %(levelname)-8s %(name)s: %(message)s",
+    )
+
+    config = ChatConfig.from_env()
+    bot = ChatBot(config)
+    asyncio.run(bot.run())
+
+
+if __name__ == "__main__":
+    main()