📝 docs(docs): add documentation

.github/workflows/ci.yml

@@ -8,7 +8,7 @@ jobs:
   commit-check:
     name: Commit Messages
     runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request' # Only run on PRs
+    if: github.event_name == 'pull_request'
     steps:
       - name: Check out code with full history
         uses: actions/checkout@v4

.github/workflows/docs.yml

@@ -0,0 +1,96 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'hackagent/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: "cloudflare-pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: 'docs/package-lock.json'
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Poetry
+        uses: abatilo/actions-poetry@v4.0.0
+        with:
+          poetry-version: '1.8.3'
+
+      - name: Configure Poetry
+        run: |
+          poetry config virtualenvs.create true
+          poetry config virtualenvs.in-project true
+
+      - name: Cache Poetry dependencies
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: poetry-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install Python dependencies
+        run: poetry install --with docs
+
+      - name: Install Node.js dependencies
+        run: |
+          cd docs
+          npm ci
+
+      - name: Generate API documentation
+        run: poetry run python docs/scripts/generate_docs.py --current
+
+      - name: Build documentation
+        run: |
+          cd docs
+          npm run build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-build
+          path: docs/build
+          retention-days: 1
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-build
+          path: docs/build
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: ${{ secrets.CLOUDFLARE_PROJECT_NAME }}
+          directory: docs/build
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+          wranglerVersion: '3' 

docs/.gitignore

@@ -0,0 +1,59 @@
+build/
+node_modules/
+
+.DS_Store
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.iml
+*.code-workspace
+.changelog
+.history
+
+node_modules
+.yarn
+package-lock.json
+
+.eslintcache
+
+yarn-error.log
+website/build
+coverage
+.docusaurus
+.cache-loader
+types
+test-website
+test-website-in-workspace
+
+packages/create-docusaurus/lib/
+packages/lqip-loader/lib/
+packages/docusaurus/lib/
+packages/docusaurus-*/lib/*
+packages/eslint-plugin/lib/
+packages/stylelint-copyright/lib/
+
+website/netlifyDeployPreview/*
+website/changelog
+!website/netlifyDeployPreview/index.html
+!website/netlifyDeployPreview/_redirects
+
+website/_dogfooding/_swizzle_theme_tests
+
+CrowdinTranslations_*.zip
+
+website/.cpu-prof
+
+website/i18n/**/*
+#!website/i18n/fr
+#!website/i18n/fr/**/*
+
+.netlify
+
+website/rspack-tracing.json
+website/bundler-cpu-profile.json
+
+.next
+.env
+.env.local
+.env.development.local
+.env.test.local

docs/README.md

@@ -0,0 +1,57 @@
+# HackAgent Documentation
+
+This directory contains the documentation generation tools for HackAgent.
+
+## Quick Start
+
+```bash
+# Generate docs for latest PyPI version (default)
+poetry run python docs/scripts/generate_docs.py
+
+# Generate docs for specific version
+poetry run python docs/scripts/generate_docs.py --version 0.2.4
+
+# Generate docs for current local version
+poetry run python docs/scripts/generate_docs.py --current
+```
+
+## NPM Scripts
+
+```bash
+# From docs/ directory
+npm run generate-docs
+npm run build
+npm run start
+```
+
+## View Documentation
+
+After generation, the API reference will be available in `docs/api-reference/` and integrated into the main documentation site.
+
+```bash
+# View documentation locally
+cd docs && npm start
+```
+
+## Requirements
+
+- Poetry: `curl -sSL https://install.python-poetry.org | python3 -`
+- Node.js 18+ and npm
+- Internet connection (for fetching PyPI versions)
+
+## What the Script Does
+
+The script automatically handles:
+- Installing documentation dependencies via Poetry
+- Fetching version information from PyPI
+- Generating Markdown files from Python docstrings using pydoc-markdown
+- Creating proper Docusaurus-compatible output
+- Copying generated files to the correct locations for the documentation site
+
+## Deployment
+
+The documentation is automatically deployed to Cloudflare Pages via GitHub Actions when changes are pushed to the main branch. The workflow:
+
+1. Generates API documentation from the hackagent package
+2. Builds the complete Docusaurus site
+3. Deploys to Cloudflare Pages

docs/api-reference/hackagent/agent.md

@@ -0,0 +1,128 @@
+---
+sidebar_label: agent
+title: hackagent.agent
+---
+
+## HackAgent Objects
+
+```python
+class HackAgent()
+```
+
+The primary client for orchestrating security assessments with HackAgent.
+
+This class serves as the main entry point to the HackAgent library, providing
+a high-level interface for:
+- Configuring victim agents that will be assessed.
+- Defining and selecting attack strategies.
+- Executing automated security tests against the configured agents.
+- Retrieving and handling test results.
+
+It encapsulates complexities such as API authentication, agent registration
+with the backend (via `AgentRouter`), and the dynamic dispatch of various
+attack methodologies.
+
+**Attributes**:
+
+- `client` - An `AuthenticatedClient` instance for API communication.
+- `prompts` - A dictionary of default prompts. This dictionary is a copy of
+  `DEFAULT_PROMPTS` and can be modified after instantiation if needed,
+  though the primary mechanism for custom prompts is usually via attack
+  configurations.
+- `router` - An `AgentRouter` instance managing the agent's representation
+  in the HackAgent backend.
+- `attack_strategies` - A dictionary mapping strategy names to their
+  `AttackStrategy` implementations.
+
+#### \_\_init\_\_
+
+```python
+def __init__(endpoint: str,
+             name: Optional[str] = None,
+             agent_type: Union[AgentTypeEnum, str] = AgentTypeEnum.UNKNOWN,
+             base_url: Optional[str] = None,
+             api_key: Optional[str] = None,
+             raise_on_unexpected_status: bool = False,
+             timeout: Optional[float] = None,
+             env_file_path: Optional[str] = None)
+```
+
+Initializes the HackAgent client and prepares it for interaction.
+
+This constructor sets up the authenticated API client, loads default
+prompts, resolves the agent type, and initializes the agent router
+to ensure the agent is known to the backend. It also prepares available
+attack strategies.
+
+**Arguments**:
+
+- `endpoint` - The target application's endpoint URL. This is the primary
+  interface that the configured agent will interact with or represent
+  during security tests.
+- `name` - An optional descriptive name for the agent being configured.
+  If not provided, a default name might be assigned or behavior might
+  depend on the specific backend agent management policies.
+- `agent_type` - Specifies the type of the agent. This can be provided
+  as an `AgentTypeEnum` member (e.g., `AgentTypeEnum.GOOGLE_ADK`) or
+  as a string identifier (e.g., "google-adk", "litellm").
+  String values are automatically converted to the corresponding
+  `AgentTypeEnum` member. Defaults to `AgentTypeEnum.UNKNOWN` if
+  not specified or if an invalid string is provided.
+- `base_url` - The base URL for the HackAgent API service.
+- `api_key` - The API key for authenticating with the HackAgent API.
+  If omitted, the client will attempt to retrieve it from the
+  `HACKAGENT_API_KEY` environment variable. The `name`0
+  parameter can specify a .env file to load this variable from.
+- `name`1 - If set to `name`2, the API client will
+  raise an exception for any HTTP status codes that are not typically
+  expected for a successful operation. Defaults to `name`3.
+- `name`4 - The timeout duration in seconds for API requests made by the
+  authenticated client. Defaults to `name`5 (which might mean a
+  default timeout from the underlying HTTP library is used).
+- `name`0 - An optional path to a .env file. If provided, environment
+  variables (such as `HACKAGENT_API_KEY`) will be loaded from this
+  file if not already present in the environment.
+
+#### hack
+
+```python
+def hack(attack_config: Dict[str, Any],
+         run_config_override: Optional[Dict[str, Any]] = None,
+         fail_on_run_error: bool = True) -> Any
+```
+
+Executes a specified attack strategy against the configured victim agent.
+
+This method serves as the primary action command for initiating an attack.
+It identifies the appropriate attack strategy based on `attack_config`,
+ensures the victim agent (managed by `self.router`) is ready, and then
+delegates the execution to the chosen strategy.
+
+**Arguments**:
+
+- `attack_config` - A dictionary containing parameters specific to the
+  chosen attack type. Must include an 'attack_type' key that maps
+  to a registered strategy (e.g., "advprefix"). Other keys provide
+  configuration for that strategy (e.g., 'category', 'prompt_text').
+- `run_config_override` - An optional dictionary that can override default
+  run configurations. The specifics depend on the attack strategy
+  and backend capabilities.
+- `fail_on_run_error` - If `True` (the default), an exception will be
+  raised if the attack run encounters an error and fails. If `False`,
+  errors might be suppressed or handled differently by the strategy.
+
+
+**Returns**:
+
+  The result returned by the `execute` method of the chosen attack
+  strategy. The nature of this result is strategy-dependent.
+
+
+**Raises**:
+
+- `ValueError` - If the 'attack_type' is missing from `attack_config` or
+  if the specified 'attack_type' is not a supported/registered
+  strategy.
+- `self.router`0 - For issues during API interaction, problems with backend
+  agent operations, or other unexpected errors during the attack process.
+

docs/api-reference/hackagent/attacks/base.md

@@ -0,0 +1,43 @@
+---
+sidebar_label: base
+title: hackagent.attacks.base
+---
+
+## BaseAttack Objects
+
+```python
+class BaseAttack(abc.ABC)
+```
+
+Abstract base class for black-box attacks against language models.
+
+#### \_\_init\_\_
+
+```python
+def __init__(config: Dict[str, Any])
+```
+
+Initializes the attack with configuration parameters.
+
+**Arguments**:
+
+- `config` - A dictionary containing configuration settings for the attack.
+
+#### run
+
+```python
+@abc.abstractmethod
+def run(**kwargs: Any) -> Any
+```
+
+Executes the attack logic.
+
+**Arguments**:
+
+- `**kwargs` - Attack-specific arguments (e.g., input prompts, goals, dataset).
+
+
+**Returns**:
+
+  Attack-specific results (e.g., adversarial examples, success metrics, report).
+