diff --git a/.env.example b/.env.example index 8c60ff1..c33dc70 100644 --- a/.env.example +++ b/.env.example @@ -18,3 +18,11 @@ DEEPSEEK_API_KEY="your_deepseek_key_here" # Create a fine-grained PAT with read-only Contents + Issues access: # https://github.com/settings/personal-access-tokens/new GITHUB_TOKEN="github_pat_..." + +# DeFi / EVM agent wallet (defi/evm_tx_handler) +# Use a dedicated agent wallet with limited funds — never a personal or treasury wallet. +# Preview and dry-run before live transfers. Never commit real private keys. +# AGENT_WALLET_PRIVATE_KEY="0x..." +# ETHEREUM_RPC_URL="https://..." +# BASE_RPC_URL="https://..." +# COINGECKO_API_KEY="optional_for_usd_caps" diff --git a/CHANGELOG.md b/CHANGELOG.md index dc5b7cf..0c2f3e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta - **Tests**: `tests/test_skill_issuer.py` now requires `test_skill.py` for every registry skill under `skills/` (#160). - **Documentation**: Clarified that bundle tests must mock network calls and model downloads in CI (#170). - **Documentation**: Added a **Status** section to [TESTING.md](docs/TESTING.md) summarizing the current testing model and planned CLI work (#179). +- **Documentation**: Post-release alignment — category tables, Python 3.10+ badge, dev install (`[dev,all]` vs `[dev]`), README configuration via `.env.example`, DeFi env vars in `.env.example`, framework env vars in [api_keys.md](docs/usage/api_keys.md) (#154). ## [0.3.7] - 2026-06-22 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e74a081..a2b7b85 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,6 +79,8 @@ git checkout -b feat/issue--short-description pip install -e ".[dev,all]" ``` +For documentation-only PRs, `pip install -e ".[dev]"` is sufficient. For skill or framework work, use `[dev,all]` to match CI. + See [TESTING.md](docs/TESTING.md) for the bundle / framework / maintainer / example model and pytest usage. ### 5. Implement and verify @@ -98,7 +100,7 @@ Follow the [Agent Code of Conduct](CODE_OF_CONDUCT.md): deterministic skill outp ### Style - **No emojis** in source code, documentation, commit messages, or PR titles. -- Use **Black** for formatting and **Flake8** for linting (see [TESTING.md](docs/TESTING.md)). +- Use **Black** for formatting (CI runs `black --check`) and **Flake8** for linting (see [TESTING.md](docs/TESTING.md)). - Match existing naming, structure, and documentation tone in the files you touch. ### Scope @@ -308,14 +310,15 @@ Place each skill under one top-level directory under `skills/`. Use an existing | Category | Purpose | Examples in registry | | :--- | :--- | :--- | | `compliance` | Privacy, policy, regulatory guardrails | `pii_masker`, `mica_module`, `tos_evaluator` | -| `data_engineering` | Datasets, generation, ETL-style tooling | `synthetic_generator` | -| `finance` | Blockchain, risk, financial analysis | `wallet_screening` | +| `data_engineering` | Datasets, generation, ETL-style tooling | `synthetic_generator`, `novelty_extractor` | | `defi` | On-chain trading and agent wallet execution | `evm_tx_handler` | +| `dev_tools` | Developer workflows, issue resolution, repo tooling | `issue_resolver` | +| `finance` | Blockchain, risk, financial analysis | `wallet_screening` | | `office` | Documents, productivity | `pdf_form_filler` | | `optimization` | Middleware, compression, efficiency | `prompt_rewriter` | | `wellness` | Coaching guardrails, mental health support | `mental_coach` | -Skill IDs follow `category/skill_name` and should match the path under `skills/`. +Skill IDs follow `category/skill_name` and should match the path under `skills/`. For the live registry, see [Skill Library](docs/skills/README.md). Propose new top-level categories in an issue before adding a folder. --- @@ -332,7 +335,7 @@ Skill IDs follow `category/skill_name` and should match the path under `skills/` ## Safety and security -- Skills that touch real-world assets (wallets, email, production APIs) should support a **dry run** or read-only mode when feasible. +- Skills that touch real-world assets (wallets, email, production APIs) should support a **dry run** or read-only mode when feasible. High-risk skills (on-chain transfers, wallet operations) should use preview and confirmation flows before sending transactions; read each skill's instructions before enabling live keys. - Sanitize inputs in `skill.py` before external calls. - Respect the skill `constitution` in both code and documentation. - Malicious or deceptive contributions may be rejected and blocked from the project. diff --git a/README.md b/README.md index 677b79f..07f206e 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@
License - Python Version + Python Version PyPI Version
@@ -79,6 +79,8 @@ Skillware/ ## Quick Start +Requires **Python 3.10 or newer** (see `requires-python` in `pyproject.toml`). + ### 1. Installation You can install Skillware directly from PyPI: @@ -92,9 +94,11 @@ Or for development, clone the repository and install in editable mode: ```bash git clone https://github.com/arpahls/skillware.git cd skillware -pip install -e . +pip install -e ".[dev,all]" ``` +For documentation-only work, `pip install -e ".[dev]"` is enough. Skill and framework contributors should use `[dev,all]` to match CI (see [TESTING.md](docs/TESTING.md)). + > **Note**: Individual skills may have their own dependencies. The `SkillLoader` validates `manifest.yaml` and warns of missing packages (e.g., `requests`, `pandas`) upon loading a skill. ### 2. Verify your installation @@ -113,12 +117,22 @@ your PATH — use `python -m skillware list` as a fallback. See ### 3. Configuration -Create a `.env` file with your API keys (e.g., Google Gemini API Key): +Copy the environment template and add your keys. + +**Unix / macOS:** + +```bash +cp .env.example .env +``` -```ini -GOOGLE_API_KEY="your_key" +**Windows (PowerShell):** + +```powershell +Copy-Item .env.example .env ``` +Edit `.env` with agent keys (for example Gemini) and any keys your skills need. Agent keys power your LLM client; skill keys are declared per skill in the [Skill library](docs/skills/README.md). See [API keys for skills](docs/usage/api_keys.md) for setup, security, and framework variables. + ### 4. Usage Example (Gemini) This example requires the Google SDK optional extra: `pip install "skillware[gemini]"` (local dev: `pip install -e ".[gemini]"`). See the [Gemini usage guide](docs/usage/gemini.md) for setup details. diff --git a/docs/TESTING.md b/docs/TESTING.md index 7bf59bf..e695694 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -100,7 +100,7 @@ Run Black on the entire repository to automatically fix formatting issues: python -m black . ``` -Run `python -m black --check .` to verify formatting without writing files. GitHub Actions runs the same check before flake8 and pytest. +Run `python -m black --check .` to verify formatting without writing files. GitHub Actions runs the same check on every pull request before flake8 and pytest; run `python -m black .` locally to fix issues before you push. ## 2. Linting (Flake8) diff --git a/docs/contributing/ai_native_workflow.md b/docs/contributing/ai_native_workflow.md index b731b0a..99c198e 100644 --- a/docs/contributing/ai_native_workflow.md +++ b/docs/contributing/ai_native_workflow.md @@ -55,6 +55,8 @@ pip install -e ".[dev,all]" git checkout -b feat/issue--short-description ``` +Use `pip install -e ".[dev]"` when the issue is documentation-only; use `[dev,all]` for skill or framework work so local pytest matches CI. + Before Stage 2, confirm: - Correct issue number and branch name @@ -225,7 +227,7 @@ These align with [CONTRIBUTING.md](../../CONTRIBUTING.md). Violations block merg - `card.json` issuer must match manifest `name` and `email` when present - Update `docs/skills/.md` and `docs/skills/README.md` - On each catalog page, add a **Usage Examples** section (Gemini, Claude, OpenAI, DeepSeek, Ollama prompt mode) per [skill usage template](../usage/skill_usage_template.md). Keep provider mechanics in `docs/usage/`; put skill-specific paths, sample user messages, and `execute` payloads on the skill page. -- Categories: `compliance`, `data_engineering`, `finance`, `office`, `optimization`—propose new ones in the issue first +- Categories: `compliance`, `data_engineering`, `defi`, `dev_tools`, `finance`, `office`, `optimization`, `wellness` — see [Skill library](../skills/README.md) for the live registry; propose new top-level categories in the issue first - Do not bump `pyproject.toml` version in skill-only PRs unless requested - Logic in `skill.py`; prompts and persona in `instructions.md` - Never commit secrets; document `env_vars` in the manifest diff --git a/docs/skills/README.md b/docs/skills/README.md index ccffa67..8246f24 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -23,7 +23,7 @@ On-chain execution and trading for dedicated agent wallets (structured intent, p | Skill | ID | Issuer | Description | | :--- | :--- | :--- | :--- | -| **[EVM Transaction Handler](evm_tx_handler.md)** | `defi/evm_tx_handler` | [@Hendobox](https://github.com/Hendobox) | Uni V2 quote, preview, execute, and transfer on Ethereum/Base from structured intent (#142). | +| **[EVM Transaction Handler](evm_tx_handler.md)** | `defi/evm_tx_handler` | [@Hendobox](https://github.com/Hendobox) | Uni V2 quote, preview, execute, and transfer on Ethereum/Base from structured intent. | ## Optimization Middleware skills that operate on text or state to increase performance, security, or efficiency. @@ -61,7 +61,7 @@ Supportive coaching guardrails, crisis triage, and grounded psychoeducation for | Skill | ID | Issuer | Description | | :--- | :--- | :--- | :--- | -| **[Mental Coach](mental_coach.md)** | `wellness/mental_coach` | [@mrmasa88](https://github.com/mrmasa88) (AO) | Deterministic wellness coaching firewall with crisis triage, scope limits, and cited KB retrieval (#148). | +| **[Mental Coach](mental_coach.md)** | `wellness/mental_coach` | [@mrmasa88](https://github.com/mrmasa88) (AO) | Deterministic wellness coaching firewall with crisis triage, scope limits, and cited KB retrieval. | --- diff --git a/docs/usage/api_keys.md b/docs/usage/api_keys.md index 48b3a85..3c8e144 100644 --- a/docs/usage/api_keys.md +++ b/docs/usage/api_keys.md @@ -7,6 +7,7 @@ Many Skillware skills call external services (block explorers, model APIs, and s ## Navigation - [Skill keys vs agent keys](#skill-keys-vs-agent-keys) +- [Framework environment variables](#framework-environment-variables) - [Local development](#local-development) - [Cloud and CI](#cloud-and-ci) - [Secret managers](#secret-managers) @@ -27,6 +28,19 @@ A single workflow may need both: for example, a skill that screens wallets may r --- +## Framework environment variables + +These are read by Skillware itself (loader and CLI), not by individual skills: + +| Variable | Purpose | +| :--- | :--- | +| `SKILLWARE_SKILL_PATH` | Extra filesystem roots for skill discovery (OS path separator between multiple entries). See [CLI reference](cli.md#path-resolution). | +| `SKILLWARE_NO_VERSION_CHECK` | Set to `1` to disable the CLI version advisory (useful in CI and automation). See [CLI reference](cli.md#version-advisory). | + +Skill-specific names remain on each skill's catalog page and in `manifest.yaml` `env_vars`. + +--- + ## Local development ### `.env` file (recommended) diff --git a/requirements.txt b/requirements.txt index 5d1b381..40647f7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ # Development convenience — same install GitHub Actions CI uses (see pyproject.toml). # Installs core + dev tools (pytest, flake8, black) + all optional SDK extras. +# Documentation-only PRs can use: pip install -e ".[dev]" # For production installs use pyproject.toml extras instead, e.g.: # pip install skillware # core only # pip install "skillware[gemini]" # + Google Gemini SDK