python-slack-agents 0.6.0__tar.gz → 0.6.1__tar.gz

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/AGENTS.md

@@ -103,12 +103,13 @@ The project includes AI-agent-friendly documentation following the llms.txt conv
 ## Releasing
 
 1. Update `version` in `pyproject.toml`
-2. Update the minimum version in `src/slack_agents/cli/init.py` (`python-slack-agents>=X.Y,<2`)
-3. Commit and push to `main`
-3. Create a GitHub Release (which creates a git tag)
-4. The `publish.yml` workflow automatically builds and publishes to PyPI via trusted publishing
+2. Update `CHANGELOG.md` with the new version and changes
+3. Run `python3 src/slack_agents/scripts/generate_llms_full.py` to regenerate `llms-full.txt`
+4. Commit and push to `main`
+5. Create a GitHub Release (which creates a git tag)
+6. The `publish.yml` workflow automatically builds and publishes to PyPI via trusted publishing
 
-Do NOT publish to PyPI manually — the GitHub Release trigger handles it.
+The PyPI deployment requires manual approval in the GitHub Actions UI. Do NOT publish to PyPI manually — the GitHub Release trigger handles it.
 
 ## Style
 
@@ -116,3 +117,4 @@ Do NOT publish to PyPI manually — the GitHub Release trigger handles it.
 - Ruff rules: E, F, I (errors, pyflakes, isort)
 - Keep it simple. Minimal abstractions, no unnecessary indirection.
 - Commit messages: Conventional Commits — `feat:`, `fix:`, `docs:`, `chore:`, `test:`, `refactor:`. Lowercase, imperative, under 72 chars.
+- **Always propose the commit message and wait for explicit user approval before committing or pushing.** Never commit or push autonomously.

python_slack_agents-0.6.1/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.6.1] - 2026-03-19
+
+### Added
+
+- `slack-agents init` now generates `.gitignore` 
+- `.env.example` template includes comments explaining where to get each token and links to setup guide
+- `build-docker` lists required environment variables after build completes
+- `build-docker` errors if `req*.txt` files are found (dependencies must be in `pyproject.toml`)
+- `init` warns when `req*.txt` files are found with migration instructions
+
+### Changed
+
+- `pyproject.toml` template uses `python-slack-agents<2` (no minimum pin) 
+- Setup flow uses venv-first approach: create venv, install package, then `slack-agents init`
+- Updated README, docs/setup.md, and docs/private-repo.md with new setup flow
+
+### Fixed
+
+- Config loader now strips YAML comments before env var interpolation — commented-out `{ENV_VAR}` patterns no longer cause `KeyError`
+- `init` shows proposed file content when skipping existing files
+
+## [0.6.0] - 2026-03-18
+
+### Added
+
+- `slack-agents init <project_name>` CLI command to scaffold new projects
+- `llms.txt` and `llms-full.txt` for AI agent discoverability
+- `llms-full.txt` bundled in PyPI wheel
+- Script to generate `llms-full.txt` from docs (`src/slack_agents/scripts/generate_llms_full.py`)
+- "Project Structure" section in README
+- Release process documentation in AGENTS.md
+
+### Changed
+
+- Simplified Dockerfile: empty placeholders for README.md and llms-full.txt so builds work for both framework and user projects
+- Updated docs/private-repo.md to use `slack-agents init`
+- Updated docs/cli.md with `init` command reference
+
+## [0.5.0] - 2025-03-13
+
+### Added
+
+- Plugin architecture for LLM providers, storage backends, and tools
+- Anthropic and OpenAI LLM providers
+- SQLite and PostgreSQL storage providers
+- MCP over HTTP tool provider
+- Built-in document export tools (PDF, DOCX, XLSX, CSV, PPTX)
+- Streaming output with native Slack table rendering
+- Socket Mode support (no public URL required)
+- OpenTelemetry observability
+- `{ENV_VAR}` interpolation in agent configs
+- Per-agent Docker builds via `docker-build-and-push.sh`

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-slack-agents
-Version: 0.6.0
+Version: 0.6.1
 Summary: A Python framework for deploying AI agents as Slack bots
 Project-URL: Homepage, https://github.com/CompareNetworks/python-slack-agents
 Project-URL: Repository, https://github.com/CompareNetworks/python-slack-agents
@@ -82,17 +82,16 @@ Each agent is a directory with two files: a `config.yaml` and a `system_prompt.t
 ## Quick Start
 
 ```bash
+mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
 pip install python-slack-agents
 
-# Scaffold a new project
-mkdir my-agents && cd my-agents
+# Scaffold the project
 slack-agents init my-agents
 
-# Add your tokens
-cp .env.example .env
-# Edit .env: SLACK_BOT_TOKEN, SLACK_APP_TOKEN, ANTHROPIC_API_KEY
-
-# Install for development (makes custom providers importable)
+# Add your tokens and install for development
+cp .env.example .env       # add your Slack and LLM tokens
 pip install -e .
 
 # Run the hello-world agent

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/README.md

@@ -36,17 +36,16 @@ Each agent is a directory with two files: a `config.yaml` and a `system_prompt.t
 ## Quick Start
 
 ```bash
+mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
 pip install python-slack-agents
 
-# Scaffold a new project
-mkdir my-agents && cd my-agents
+# Scaffold the project
 slack-agents init my-agents
 
-# Add your tokens
-cp .env.example .env
-# Edit .env: SLACK_BOT_TOKEN, SLACK_APP_TOKEN, ANTHROPIC_API_KEY
-
-# Install for development (makes custom providers importable)
+# Add your tokens and install for development
+cp .env.example .env       # add your Slack and LLM tokens
 pip install -e .
 
 # Run the hello-world agent

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/docs/private-repo.md

@@ -16,6 +16,9 @@ For production agents with company-specific prompts, tools, and configs, create
 
 ```bash
 mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
+pip install python-slack-agents
 slack-agents init my-agents
 pip install -e .
 ```

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/docs/setup.md

@@ -6,9 +6,32 @@
 - A Slack workspace (all plans supported, including free)
 - API key for your LLM provider (Anthropic and/or OpenAI)
 
-## Installation
+## New Project
 
 ```bash
+mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
+pip install python-slack-agents
+
+# Scaffold the project
+slack-agents init my-agents
+
+# Add your tokens and install for development
+cp .env.example .env       # add your Slack and LLM tokens (see below)
+pip install -e .
+
+# Run the hello-world agent
+slack-agents run agents/hello-world
+```
+
+## Framework Development
+
+If you're working on the framework itself:
+
+```bash
+git clone https://github.com/CompareNetworks/python-slack-agents.git
+cd python-slack-agents
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
@@ -40,7 +63,7 @@ ANTHROPIC_API_KEY=sk-ant-...
   - Copy: App Token (eg, SLACK_APP_TOKEN=xapp-...)
 - Settings > Install App
   - Copy: Bot User OAuth Token (eg, SLACK_BOT_TOKEN=xoxb-...)
-3. If App does not appeat in your Slack client:
+3. If App does not appear in your Slack client:
   - ... > Tools > Apps > (search by name and add the app)
 
 ## Download Fonts
@@ -53,12 +76,6 @@ python -m slack_agents.scripts.download_fonts
 
 This downloads `DejaVuSans.ttf` and `DejaVuSans-Bold.ttf` into `fonts/` (~700KB total). Without these fonts, PDF generation falls back to Helvetica (latin-1 only).
 
-## Running an Agent
-
-```bash
-slack-agents run agents/hello-world
-```
-
 ## Optional: PostgreSQL
 
 For conversation persistence via PostgreSQL, update your agent's `config.yaml`:

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/llms-full.txt

@@ -1,7 +1,8 @@
 # python-slack-agents: Complete Reference
 
 > A Python framework for deploying AI agents as Slack bots.
-> Each agent is a YAML config and a system prompt — pick your LLM, connect some MCP tools, and `slack-agents run`.
+> Each agent is a YAML config and a system prompt — pick your LLM,
+> connect some MCP tools, and `slack-agents run`.
 
 - **Package:** `pip install python-slack-agents`
 - **CLI entry point:** `slack-agents`
@@ -11,15 +12,26 @@
 
 ## How to read this document
 
-This file is a concatenation of all documentation files, designed to be consumed in a single read.
-The sections below correspond to individual doc files in the `docs/` directory.
+This file is a concatenation of all documentation files,
+designed to be consumed in a single read.
+The sections below correspond to individual doc files
+in the `docs/` directory.
 
 ### Key concepts
 
-- **Config-driven:** each agent is a directory with `config.yaml` + `system_prompt.txt`. All behavior is configured in YAML.
-- **Plugin pattern:** every pluggable component (LLM, storage, tools, access) uses a `type` field with a dotted Python import path pointing to a module with a `Provider` class. All other config keys are passed as kwargs to `Provider.__init__`.
-- **Two kinds of tool providers:** `BaseToolProvider` (tools the LLM calls) and `BaseFileImporterProvider` (file handlers the *framework* calls automatically — invisible to the LLM). Both are configured under `tools:` in config.yaml.
-- **Environment variables:** `{ENV_VAR}` patterns in config values are resolved from environment variables at startup.
+- **Config-driven:** each agent is a directory with
+  `config.yaml` + `system_prompt.txt`.
+  All behavior is configured in YAML.
+- **Plugin pattern:** every pluggable component (LLM, storage,
+  tools, access) uses a `type` field with a dotted Python import
+  path pointing to a module with a `Provider` class. All other
+  config keys are passed as kwargs to `Provider.__init__`.
+- **Two kinds of tool providers:** `BaseToolProvider` (tools the
+  LLM calls) and `BaseFileImporterProvider` (file handlers the
+  *framework* calls automatically — invisible to the LLM). Both
+  are configured under `tools:` in config.yaml.
+- **Environment variables:** `{ENV_VAR}` patterns in config values
+  are resolved from environment variables at startup.
 
 ---
 
@@ -31,9 +43,32 @@ The sections below correspond to individual doc files in the `docs/` directory.
 - A Slack workspace (all plans supported, including free)
 - API key for your LLM provider (Anthropic and/or OpenAI)
 
-## Installation
+## New Project
 
 ```bash
+mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
+pip install python-slack-agents
+
+# Scaffold the project
+slack-agents init my-agents
+
+# Add your tokens and install for development
+cp .env.example .env       # add your Slack and LLM tokens (see below)
+pip install -e .
+
+# Run the hello-world agent
+slack-agents run agents/hello-world
+```
+
+## Framework Development
+
+If you're working on the framework itself:
+
+```bash
+git clone https://github.com/CompareNetworks/python-slack-agents.git
+cd python-slack-agents
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
@@ -65,7 +100,7 @@ ANTHROPIC_API_KEY=sk-ant-...
   - Copy: App Token (eg, SLACK_APP_TOKEN=xapp-...)
 - Settings > Install App
   - Copy: Bot User OAuth Token (eg, SLACK_BOT_TOKEN=xoxb-...)
-3. If App does not appeat in your Slack client:
+3. If App does not appear in your Slack client:
   - ... > Tools > Apps > (search by name and add the app)
 
 ## Download Fonts
@@ -78,12 +113,6 @@ python -m slack_agents.scripts.download_fonts
 
 This downloads `DejaVuSans.ttf` and `DejaVuSans-Bold.ttf` into `fonts/` (~700KB total). Without these fonts, PDF generation falls back to Helvetica (latin-1 only).
 
-## Running an Agent
-
-```bash
-slack-agents run agents/hello-world
-```
-
 ## Optional: PostgreSQL
 
 For conversation persistence via PostgreSQL, update your agent's `config.yaml`:
@@ -1101,6 +1130,9 @@ For production agents with company-specific prompts, tools, and configs, create
 
 ```bash
 mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
+pip install python-slack-agents
 slack-agents init my-agents
 pip install -e .
 ```

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-slack-agents"
-version = "0.6.0"
+version = "0.6.1"
 description = "A Python framework for deploying AI agents as Slack bots"
 authors = [{name = "Eric Pichon", email = "epichon@comparenetworks.com"}]
 readme = "README.md"

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/src/slack_agents/cli/build_docker.py

@@ -33,6 +33,7 @@ def _is_valid_docker_name(name: str) -> bool:
 
 
 def execute(args):
+    import re
     import subprocess
     import sys
     from pathlib import Path
@@ -66,6 +67,18 @@ def execute(args):
     else:
         image_tag = f"{image_name}:{version}"
 
+    req_files = sorted(Path(".").glob("req*.txt"))
+    if req_files:
+        names = ", ".join(f.name for f in req_files)
+        print(
+            f"Error: found {names} in the project root.\n"
+            "Docker builds install dependencies from pyproject.toml, not\n"
+            "requirements files. Move your dependencies into pyproject.toml\n"
+            "under [project] dependencies, then remove the requirements file(s).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
     print(f"Building {image_tag} ...")
     result = subprocess.run(
         [
@@ -92,3 +105,12 @@ def execute(args):
             sys.exit(result.returncode)
 
     print(f"Done: {image_tag}")
+
+    # Show required env vars last so they're visible without scrolling
+    raw_config = (agent_dir / "config.yaml").read_text()
+    active_config = re.sub(r"(?m)^(\s*)#.*$", r"\1", raw_config)
+    env_vars = sorted(set(re.findall(r"\{([A-Z_][A-Z0-9_]*)\}", active_config)))
+    if env_vars:
+        print(f"\nRequired environment variables ({len(env_vars)}):")
+        for var in env_vars:
+            print(f"  {var}")

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/src/slack_agents/cli/init.py

@@ -10,20 +10,39 @@ name = "{project_name}"
 version = "0.1.0"
 requires-python = ">=3.12"
 dependencies = [
-    "python-slack-agents>=0.6,<2",
+    "python-slack-agents<2",
+    # add packages required by your plugins here
 ]
 
 [tool.setuptools.packages.find]
-where = ["src"]
+where = ["src"]  # required to import plugins and to build docker images
 """
 
 ENV_EXAMPLE = """\
+# Full setup guide:
+# https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/setup.md
+
 SLACK_BOT_TOKEN=xoxb-...
 SLACK_APP_TOKEN=xapp-...
+
+# LLM provider
 ANTHROPIC_API_KEY=sk-ant-...
 # OPENAI_API_KEY=sk-...
 """
 
+GITIGNORE = """\
+.env
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+*.db
+.DS_Store
+.idea/
+.vscode/
+dist/
+"""
+
 HELLO_WORLD_CONFIG = """\
 version: "1.0.0"
 schema: "slack-agents/v1"
@@ -74,6 +93,7 @@ def execute(args):
         ),
         f"src/{package_name}/__init__.py": "",
         ".env.example": ENV_EXAMPLE,
+        ".gitignore": GITIGNORE,
         "agents/hello-world/config.yaml": HELLO_WORLD_CONFIG,
         "agents/hello-world/system_prompt.txt": HELLO_WORLD_PROMPT,
     }
@@ -82,13 +102,27 @@ def execute(args):
         path = Path(rel_path)
         if path.exists():
             print(f"Skipping {rel_path} (already exists — remove it to regenerate)")
+            print("  Proposed content:\n")
+            for line in content.splitlines():
+                print(f"    {line}")
+            print()
             continue
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(content)
         print(f"Created {rel_path}")
 
-    print()
+    # Warn about requirements files that won't be picked up by Docker builds
+    req_files = sorted(Path(".").glob("req*.txt"))
+    if req_files:
+        names = ", ".join(f.name for f in req_files)
+        print(f"WARNING: found {names}")
+        print("  Docker builds install dependencies from pyproject.toml, not")
+        print("  requirements files. Move your dependencies into pyproject.toml")
+        print("  under [project] dependencies or your Docker images will be")
+        print("  missing packages.")
+        print()
+
     print("Next steps:")
-    print("  cp .env.example .env       # add your tokens")
-    print("  pip install -e .           # install for development")
-    print("  slack-agents run agents/hello-world")
+    print("  cp .env.example .env                # add your tokens")
+    print("  pip install -e .                     # install for development")
+    print("  slack-agents run agents/hello-world  # run the example agent")

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/src/slack_agents/config.py

@@ -14,8 +14,14 @@ logger = logging.getLogger(__name__)
 CURRENT_SCHEMA = "slack-agents/v1"
 
 
+def _strip_yaml_comments(text: str) -> str:
+    """Blank out YAML comment lines, preserving line numbers for error messages."""
+    return re.sub(r"(?m)^(\s*)#.*$", r"\1", text)
+
+
 def _resolve_env_vars(text: str) -> str:
     """Replace {VAR_NAME} with os.environ[VAR_NAME]. Only matches uppercase/underscore names."""
+    text = _strip_yaml_comments(text)
     return re.sub(r"\{([A-Z_][A-Z0-9_]*)\}", lambda m: os.environ[m.group(1)], text)
 
 

{python_slack_agents-0.6.0 → python_slack_agents-0.6.1}/uv.lock

@@ -1607,7 +1607,7 @@ wheels = [
 
 [[package]]
 name = "python-slack-agents"
-version = "0.6.0"
+version = "0.6.1"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

python_slack_agents-0.6.0/CHANGELOG.md

@@ -1,22 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
-
-## [Unreleased]
-
-## [0.5.0] - 2025-03-13
-
-### Added
-
-- Plugin architecture for LLM providers, storage backends, and tools
-- Anthropic and OpenAI LLM providers
-- SQLite and PostgreSQL storage providers
-- MCP over HTTP tool provider
-- Built-in document export tools (PDF, DOCX, XLSX, CSV, PPTX)
-- Streaming output with native Slack table rendering
-- Socket Mode support (no public URL required)
-- OpenTelemetry observability
-- `{ENV_VAR}` interpolation in agent configs
-- Per-agent Docker builds via `docker-build-and-push.sh`