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

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

@@ -90,9 +90,31 @@ Each agent lives in `agents/<name>/` with `config.yaml` and `system_prompt.txt`.
 - **Tool definitions in Anthropic format** -- `{"name", "description", "input_schema"}` is the canonical format everywhere
 - **1 replica per agent** -- Socket Mode requires exactly one WebSocket connection per app
 
+## AI Documentation Files
+
+The project includes AI-agent-friendly documentation following the llms.txt convention:
+
+- `llms.txt` (repo root) -- concise index pointing to docs and llms-full.txt
+- `llms-full.txt` (repo root) -- generated from docs via `python3 src/slack_agents/scripts/generate_llms_full.py`
+- `llms-full.txt` is bundled in the PyPI wheel via `force-include` in pyproject.toml
+
+**When modifying docs:** re-run `python3 src/slack_agents/scripts/generate_llms_full.py` and commit the result.
+
+## Releasing
+
+1. Update `version` in `pyproject.toml`
+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
+
+The PyPI deployment requires manual approval in the GitHub Actions UI. Do NOT publish to PyPI manually — the GitHub Release trigger handles it.
+
 ## Style
 
 - Python 3.12+, line length 100
 - 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.5.0 → python_slack_agents-0.6.1}/CONTRIBUTING.md

@@ -67,6 +67,19 @@ Keep PRs focused — one concern per PR. Small PRs get reviewed faster.
 
 LLM providers, storage backends, and tools all follow the same pattern: a module with a `Provider` class. See the [docs/](docs/) directory for guides on creating each type.
 
+## AI Documentation
+
+This project ships `llms.txt` and `llms-full.txt` for AI agent discoverability. `llms-full.txt` is bundled in the PyPI wheel and generated from the docs by concatenation:
+
+```bash
+python3 src/slack_agents/scripts/generate_llms_full.py
+```
+
+When making changes that affect docs:
+- Update the relevant file in `docs/` as you normally would
+- Re-run the script above to regenerate `llms-full.txt` and commit the result
+- `llms.txt` only needs updating if you add/remove/rename a doc file
+
 ## License
 
 By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-slack-agents
-Version: 0.5.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,15 +82,17 @@ 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
 
-# Set up your environment
-cp .env.example .env
+# Scaffold the project
+slack-agents init my-agents
 
-# Edit .env with your Slack and LLM tokens
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_APP_TOKEN=xapp-...
-ANTHROPIC_API_KEY=sk-ant-...
+# 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
 slack-agents run agents/hello-world
@@ -170,6 +172,7 @@ All secrets in `{ENV_VAR}` are resolved from environment variables at startup.
 ## CLI
 
 ```bash
+slack-agents init <project-name>                    # scaffold a new project
 slack-agents run agents/<name>                      # start an agent
 slack-agents healthcheck agents/<name>              # liveness probe (for k8s)
 slack-agents export-conversations agents/<name> \   # export conversation history
@@ -238,20 +241,39 @@ tools:
       - "get_document"    # exact match works too
 ```
 
+## Project Structure
+
+When you add custom providers (tools, LLM, storage, or access control), your project needs a `pyproject.toml` and a `src/` directory so that `pip install -e .` makes your code importable and `slack-agents build-docker` works:
+
+```
+my-agents/
+├── pyproject.toml          # declares python-slack-agents as dependency
+├── src/
+│   └── my_agents/          # your custom providers go here
+│       └── __init__.py
+├── agents/
+│   └── my-agent/
+│       ├── config.yaml
+│       └── system_prompt.txt
+└── .env
+```
+
+`slack-agents init` scaffolds this for you. See [Organizing agents](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/private-repo.md) for details.
+
 ## Extending
 
-Every pluggable component follows the same pattern. Add a new LLM provider, storage backend, tool, or access policy by creating a module with a `Provider` class:
+Every pluggable component follows the same pattern. Add a new LLM provider, storage backend, tool, or access policy by creating a module with a `Provider` class in `src/`:
 
 ```yaml
 # In config.yaml
 llm:
-  type: my_package.my_llm_provider
+  type: my_agents.my_llm_provider
   model: my-model
   api_key: "{MY_API_KEY}"
 ```
 
 ```python
-# In my_package/my_llm_provider.py
+# In src/my_agents/my_llm_provider.py
 from slack_agents.llm.base import BaseLLMProvider
 
 class Provider(BaseLLMProvider):
@@ -259,6 +281,8 @@ class Provider(BaseLLMProvider):
         ...
 ```
 
+After `pip install -e .`, your providers are importable and the `type` field in config resolves them. This also works with `slack-agents build-docker` — the bundled Dockerfile runs `pip install .` automatically.
+
 See the docs for the full interface for each component:
 
 - [LLM providers](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/llm.md)
@@ -299,6 +323,10 @@ To create a Slack app, use the manifest in [`docs/slack-app-manifest.json`](http
 - [CLI](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/cli.md) — command reference
 - [Organizing agents](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/private-repo.md) — in-repo, separate directory, or private repository
 
+## For AI Agents
+
+If you're an AI agent or coding assistant, see [`llms-full.txt`](https://raw.githubusercontent.com/CompareNetworks/python-slack-agents/main/llms-full.txt) for a complete, single-file reference to the config schema, all providers, and the plugin system. After `pip install`, the reference is available locally inside the package at `slack_agents/llms-full.txt`.
+
 ## Related Projects
 
 If this framework isn't the right fit, here are some good alternatives:

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

@@ -36,15 +36,17 @@ 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
 
-# Set up your environment
-cp .env.example .env
+# Scaffold the project
+slack-agents init my-agents
 
-# Edit .env with your Slack and LLM tokens
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_APP_TOKEN=xapp-...
-ANTHROPIC_API_KEY=sk-ant-...
+# 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
 slack-agents run agents/hello-world
@@ -124,6 +126,7 @@ All secrets in `{ENV_VAR}` are resolved from environment variables at startup.
 ## CLI
 
 ```bash
+slack-agents init <project-name>                    # scaffold a new project
 slack-agents run agents/<name>                      # start an agent
 slack-agents healthcheck agents/<name>              # liveness probe (for k8s)
 slack-agents export-conversations agents/<name> \   # export conversation history
@@ -192,20 +195,39 @@ tools:
       - "get_document"    # exact match works too
 ```
 
+## Project Structure
+
+When you add custom providers (tools, LLM, storage, or access control), your project needs a `pyproject.toml` and a `src/` directory so that `pip install -e .` makes your code importable and `slack-agents build-docker` works:
+
+```
+my-agents/
+├── pyproject.toml          # declares python-slack-agents as dependency
+├── src/
+│   └── my_agents/          # your custom providers go here
+│       └── __init__.py
+├── agents/
+│   └── my-agent/
+│       ├── config.yaml
+│       └── system_prompt.txt
+└── .env
+```
+
+`slack-agents init` scaffolds this for you. See [Organizing agents](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/private-repo.md) for details.
+
 ## Extending
 
-Every pluggable component follows the same pattern. Add a new LLM provider, storage backend, tool, or access policy by creating a module with a `Provider` class:
+Every pluggable component follows the same pattern. Add a new LLM provider, storage backend, tool, or access policy by creating a module with a `Provider` class in `src/`:
 
 ```yaml
 # In config.yaml
 llm:
-  type: my_package.my_llm_provider
+  type: my_agents.my_llm_provider
   model: my-model
   api_key: "{MY_API_KEY}"
 ```
 
 ```python
-# In my_package/my_llm_provider.py
+# In src/my_agents/my_llm_provider.py
 from slack_agents.llm.base import BaseLLMProvider
 
 class Provider(BaseLLMProvider):
@@ -213,6 +235,8 @@ class Provider(BaseLLMProvider):
         ...
 ```
 
+After `pip install -e .`, your providers are importable and the `type` field in config resolves them. This also works with `slack-agents build-docker` — the bundled Dockerfile runs `pip install .` automatically.
+
 See the docs for the full interface for each component:
 
 - [LLM providers](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/llm.md)
@@ -253,6 +277,10 @@ To create a Slack app, use the manifest in [`docs/slack-app-manifest.json`](http
 - [CLI](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/cli.md) — command reference
 - [Organizing agents](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/private-repo.md) — in-repo, separate directory, or private repository
 
+## For AI Agents
+
+If you're an AI agent or coding assistant, see [`llms-full.txt`](https://raw.githubusercontent.com/CompareNetworks/python-slack-agents/main/llms-full.txt) for a complete, single-file reference to the config schema, all providers, and the plugin system. After `pip install`, the reference is available locally inside the package at `slack_agents/llms-full.txt`.
+
 ## Related Projects
 
 If this framework isn't the right fit, here are some good alternatives:

{python_slack_agents-0.5.0 → python_slack_agents-0.6.1}/docs/cli.md

@@ -2,6 +2,16 @@
 
 All commands are available as `slack-agents <command>`.
 
+## init
+
+Scaffold a new project in the current directory.
+
+```bash
+slack-agents init <project_name>
+```
+
+Creates `pyproject.toml`, `src/<package>/`, `.env.example`, and a `hello-world` agent. Existing files are skipped with a warning.
+
 ## run
 
 Start a Slack agent.

python_slack_agents-0.6.1/docs/private-repo.md

@@ -0,0 +1,65 @@
+# Organizing Your Agents
+
+Agents are just directories with `config.yaml` and `system_prompt.txt`. Where you put them depends on your situation.
+
+## Option 1: In the framework repo
+
+If you're developing the framework itself, add agents directly to `agents/`. To keep private agents out of version control, use a gitignored directory instead:
+
+```bash
+slack-agents run agents-local/my-agent
+```
+
+## Option 2: Separate repository
+
+For production agents with company-specific prompts, tools, and configs, create a standalone repository:
+
+```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 .
+```
+
+This scaffolds:
+
+```
+my-agents/
+├── pyproject.toml
+├── src/
+│   └── my_agents/
+│       └── __init__.py
+├── agents/
+│   └── hello-world/
+│       ├── config.yaml
+│       └── system_prompt.txt
+└── .env.example
+```
+
+The `pyproject.toml` and `src/` directory are required so that:
+
+- **`slack-agents run`** can import custom providers under `src/` (via `pip install -e .`)
+- **`slack-agents build-docker`** works (the bundled Dockerfile runs `pip install .`)
+
+### Custom providers
+
+Add custom providers to `src/` and reference them in config:
+
+```yaml
+tools:
+  internal-api:
+    type: my_agents.tools.internal_api
+    allowed_functions: [".*"]
+    base_url: "{INTERNAL_API_URL}"
+```
+
+### Docker
+
+No custom Dockerfile needed — `python-slack-agents` bundles one:
+
+```bash
+slack-agents build-docker agents/my-agent
+slack-agents build-docker agents/my-agent --push registry.example.com
+```

{python_slack_agents-0.5.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`: