pyfortiaigate 0.1.0__tar.gz

pyfortiaigate-0.1.0/.env.example

@@ -0,0 +1,27 @@
+# pyfortiaigate live tests: copy to .env and fill in. .env is gitignored.
+# Variables already set in your shell win over this file.
+# The live tests only READ (me, list calls, one page of audit logs).
+
+# Set to 1 to run tests/live once the values below are filled in (skipped otherwise)
+FAIG_LIVE=
+
+# Management URL: https://host, a bare host, or https://host/api (e.g. https://faig.example.com)
+FAIG_URL=
+
+# Session login: the account's email (the built-in admin is "admin")
+FAIG_USERNAME=
+FAIG_PASSWORD=
+
+# Or a bearer token instead of a username/password
+FAIG_TOKEN=
+
+# TLS: a CA file that signed the appliance's certificate (preferred), or
+# FAIG_VERIFY_TLS=false to skip checking (isolated labs / localhost tunnels only)
+FAIG_CA_BUNDLE=
+FAIG_VERIFY_TLS=
+
+# Write tests (tests/live/test_live_write.py): the workspace they may write in.
+# They create pytest-* objects there and delete them afterwards. Blank = skipped.
+FAIG_WRITE_WORKSPACE=
+# Optional: model for the two gateway chat calls (default: workspace's first OpenAI model)
+FAIG_TEST_MODEL=

pyfortiaigate-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ '3.10', '3.11', '3.12', '3.13', '3.14' ]
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # hatch-vcs derives the version from tags.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: '**/pyproject.toml'
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test,typecheck,lint]"
+
+      - name: Lint (ruff format check + lint)
+        run: |
+          ruff format --check .
+          ruff check .
+
+      - name: Type check (mypy --strict)
+        run: mypy src
+
+      - name: Test (coverage floor in pyproject.toml)
+        run: pytest -q --cov --cov-report=term-missing
+
+      # The docs toolchain needs a current Python; one build is enough.
+      - name: Docs build
+        if: matrix.python-version == '3.12'
+        run: |
+          pip install -e ".[docs]"
+          mkdocs build --strict

pyfortiaigate-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - run: pip install -e ".[docs]"
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

pyfortiaigate-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  release:
+    types: [ created ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: [ test ]
+    environment: release
+    permissions:
+      contents: read       # checkout
+      id-token: write      # PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # hatch-vcs derives the package version from the release tag.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - run: pip install build
+
+      - run: python -m build
+
+      - name: Publish to PyPI (trusted publishing, no token)
+        uses: pypa/gh-action-pypi-publish@release/v1

pyfortiaigate-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+site/
+.coverage
+coverage.xml
+.ruff_cache/
+.mypy_cache/
+.env
+.env.*
+!.env.example

pyfortiaigate-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-12
+
+### Added
+
+- `FortiAIGate` client for the 8.x management API and OpenAI-compatible
+  gateway: users and invitations, workspaces, detectors, guardrails, policies,
+  the approval workflow, virtual keys, providers, model groups, DLP labels,
+  audit logs, `check_key` and `chat_completion`.
+- Session login with re-login on expiry, a CSRF token per mutation, bearer
+  token auth, and `verify` as a CA bundle path.
+- Transport retries that never resend a mutation that may have landed, on one
+  keep-alive connection.
+- Body builders (`regex_detector_body`, `dlp_detector_body`, `guardrail_body`)
+  and `approve_new`.
+- `delete_detector`, `delete_guardrail`, `delete_policy`; `key_update_body`.
+- Live test suites: read-only, and opt-in writes confined to one workspace
+  (`FAIG_WRITE_WORKSPACE`) that delete everything they create. Settings load
+  from a gitignored `.env` (template: `.env.example`).
+
+### Verified live on FortiAIGate 8.0.2
+
+- `me()` reads `GET /api/v1/user` (`/api/v1/me` does not exist).
+- `create_policy` takes `provider_ids`: a policy that grants no model is
+  refused with HTTP 422.
+- `update_virtual_key` sends only the fields a key PUT accepts, with
+  `policyIds` as plain strings; resending the whole record is refused.
+- `revoke_virtual_key` sends the `reason` the API requires.

pyfortiaigate-0.1.0/LICENSE

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

pyfortiaigate-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: pyfortiaigate
+Version: 0.1.0
+Summary: Python client for the FortiAIGate 8.x management and gateway API, standard library only
+Project-URL: Homepage, https://github.com/ftnt-dspille/pyfortiaigate
+Project-URL: Repository, https://github.com/ftnt-dspille/pyfortiaigate.git
+Project-URL: Issues, https://github.com/ftnt-dspille/pyfortiaigate/issues
+Author: Dylan Spille
+License: MIT
+License-File: LICENSE
+Keywords: ai-gateway,api,fortiaigate,fortinet,guardrails
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff==0.16.10; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: lint
+Requires-Dist: ruff==0.16.10; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.13; extra == 'typecheck'
+Description-Content-Type: text/markdown
+
+# pyfortiaigate
+
+Python client for the **FortiAIGate 8.x** management API and its
+OpenAI-compatible gateway. Standard library only: no dependencies, and the
+client is one self-contained module you can copy onto a host that cannot
+`pip install`.
+
+```bash
+pip install pyfortiaigate
+```
+
+```python
+from pyfortiaigate import FortiAIGate, approve_new, regex_detector_body
+
+with FortiAIGate("https://faig.example.com", "admin", "<password>") as faig:
+    ws = faig.workspace_by_name("team-a")
+    det = faig.create_detector(
+        ws["id"], regex_detector_body("no-ssn", [("ssn", r"\d{3}-\d{2}-\d{4}", "block")])
+    )
+    approve_new(faig, ws["id"], "detectors", det)  # draft -> pending -> active
+```
+
+## What it handles for you
+
+- **Auth:** session login (logs in on first call, again when the session
+  expires) or a bearer token; a fresh CSRF token for every mutation.
+- **Flaky networks:** transport failures are retried with backoff. A request
+  that was never answered is retried for every method; a connection dropped
+  after the request went out is retried only for GET, so a mutation is never
+  sent twice.
+- **One connection:** requests reuse a keep-alive HTTPS connection, which
+  matters through tunnels where every new connect costs seconds.
+- **Undocumented behaviour:** body builders encode what the API silently
+  requires (a regex detector's flat `rules` list, DLP `disposition`, at least
+  one detector per guardrail).
+
+## Coverage
+
+Users and invitations, workspaces, detectors (custom and built-in), guardrails
+(including scan tests), policies, the approval workflow, virtual keys (create,
+update, rotate, revoke), AI providers, model groups, DLP labels, audit logs,
+and the gateway (`check_key`, `chat_completion`).
+
+Full reference: **https://ftnt-dspille.github.io/pyfortiaigate/**
+
+## TLS
+
+Verification is on by default. For an appliance with a self-signed
+certificate, pass its CA: `FortiAIGate(url, user, pw, verify="/path/ca.pem")`.
+`verify=False` turns checking off and is for isolated labs only.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest                 # offline suite, coverage enforced
+.venv/bin/ruff format --check . && .venv/bin/ruff check .
+.venv/bin/mypy src               # strict
+.venv/bin/mkdocs serve           # docs at http://127.0.0.1:8000
+```
+
+Live tests are opt-in and read-only. Fill in `.env` (gitignored; copied from
+`.env.example`), set `FAIG_LIVE=1`, then:
+
+```bash
+.venv/bin/pytest tests/live -v
+```
+
+Unofficial; not affiliated with or supported by Fortinet. MIT licensed.

pyfortiaigate-0.1.0/README.md

@@ -0,0 +1,69 @@
+# pyfortiaigate
+
+Python client for the **FortiAIGate 8.x** management API and its
+OpenAI-compatible gateway. Standard library only: no dependencies, and the
+client is one self-contained module you can copy onto a host that cannot
+`pip install`.
+
+```bash
+pip install pyfortiaigate
+```
+
+```python
+from pyfortiaigate import FortiAIGate, approve_new, regex_detector_body
+
+with FortiAIGate("https://faig.example.com", "admin", "<password>") as faig:
+    ws = faig.workspace_by_name("team-a")
+    det = faig.create_detector(
+        ws["id"], regex_detector_body("no-ssn", [("ssn", r"\d{3}-\d{2}-\d{4}", "block")])
+    )
+    approve_new(faig, ws["id"], "detectors", det)  # draft -> pending -> active
+```
+
+## What it handles for you
+
+- **Auth:** session login (logs in on first call, again when the session
+  expires) or a bearer token; a fresh CSRF token for every mutation.
+- **Flaky networks:** transport failures are retried with backoff. A request
+  that was never answered is retried for every method; a connection dropped
+  after the request went out is retried only for GET, so a mutation is never
+  sent twice.
+- **One connection:** requests reuse a keep-alive HTTPS connection, which
+  matters through tunnels where every new connect costs seconds.
+- **Undocumented behaviour:** body builders encode what the API silently
+  requires (a regex detector's flat `rules` list, DLP `disposition`, at least
+  one detector per guardrail).
+
+## Coverage
+
+Users and invitations, workspaces, detectors (custom and built-in), guardrails
+(including scan tests), policies, the approval workflow, virtual keys (create,
+update, rotate, revoke), AI providers, model groups, DLP labels, audit logs,
+and the gateway (`check_key`, `chat_completion`).
+
+Full reference: **https://ftnt-dspille.github.io/pyfortiaigate/**
+
+## TLS
+
+Verification is on by default. For an appliance with a self-signed
+certificate, pass its CA: `FortiAIGate(url, user, pw, verify="/path/ca.pem")`.
+`verify=False` turns checking off and is for isolated labs only.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest                 # offline suite, coverage enforced
+.venv/bin/ruff format --check . && .venv/bin/ruff check .
+.venv/bin/mypy src               # strict
+.venv/bin/mkdocs serve           # docs at http://127.0.0.1:8000
+```
+
+Live tests are opt-in and read-only. Fill in `.env` (gitignored; copied from
+`.env.example`), set `FAIG_LIVE=1`, then:
+
+```bash
+.venv/bin/pytest tests/live -v
+```
+
+Unofficial; not affiliated with or supported by Fortinet. MIT licensed.

pyfortiaigate-0.1.0/docs/actions.md

@@ -0,0 +1,121 @@
+# Actions
+
+Every client method and the API call it makes. `{ws}` is a workspace id; list
+methods return the records (unwrapped from `{"items": [...]}`), the rest return
+the decoded JSON response.
+
+## Session & raw calls
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `login(username, password)` | `POST /api/v1/login` | Optional: the client logs in on its first call. Falls back to the legacy `/api/login`. |
+| `close()` | `POST /api/v1/logout` | Also runs on leaving a `with` block. |
+| `me()` | `GET /api/v1/user` | The logged-in user: `email`, `role`, `memberships`, ... |
+| `request(method, path, body, params)` | any | Raw management call with auth, CSRF and retries. |
+| `get(path, params)` | `GET` | |
+| `post(path, body)` | `POST` | Sends `{}` when there is no body. |
+| `put(path, body)` | `PUT` | |
+| `patch(path, body)` | `PATCH` | |
+| `delete(path)` | `DELETE` | |
+
+## Users & invitations
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `users()` | `GET /api/v1/admin/users` | |
+| `user(user_id)` | `GET /api/v1/admin/users/{id}` | |
+| `user_by_email(email)` | `GET /api/v1/admin/users` | Case-insensitive match; `None` if absent. |
+| `invite(email, role)` | `POST /api/v1/admin/user-invitations` | Users exist only via invitation; no email is sent. |
+| `accept_invite(invitation_id, email, password, display_name)` | `POST /api/v1/invitations/{id}/accept` | Unauthenticated; sets the password. |
+| `delete_user(user_id)` | `DELETE /api/v1/admin/users/{id}` | |
+| `make_workspace_admin(user_id, ws_id)` | `GET` + `PUT /api/v1/admin/users/{id}` | Keeps the user's other memberships. |
+
+## Workspaces
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `workspaces()` | `GET /api/v1/admin/workspaces` | Every workspace (org admin). |
+| `my_workspaces()` | `GET /api/v1/me/workspaces` | Workspaces the caller belongs to. |
+| `workspace_by_name(name)` | `GET /api/v1/admin/workspaces` | |
+| `create_workspace(name, admin_ids, provider_ids, description)` | `POST /api/v1/admin/workspaces` | Admins must be existing users. |
+| `delete_workspace(ws_id)` | `DELETE /api/v1/admin/workspaces/{ws}` | |
+| `workspace_members(ws_id)` | `GET /api/v1/workspaces/{ws}/members` | |
+| `workspace_budget(ws_id)` | `GET /api/v1/workspaces/{ws}/budget` | |
+| `workspace_analytics(ws_id)` | `GET /api/v1/workspaces/{ws}/analytics` | |
+
+## Detectors
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `detectors(ws_id=None)` | `GET /api/v1/workspaces/{ws}/detectors` or `GET /api/v1/admin/detectors` | Custom detectors. |
+| `builtin_detectors()` | `GET /api/v1/admin/built-in-detectors` | Identified by slug id. |
+| `detector_by_name(ws_id, name)` | `GET /api/v1/workspaces/{ws}/detectors` | |
+| `create_detector(ws_id, body)` | `POST /api/v1/workspaces/{ws}/detectors` | Build `body` with `regex_detector_body` / `dlp_detector_body`. |
+| `update_detector(ws_id, uuid, body)` | `PUT /api/v1/workspaces/{ws}/detectors/{uuid}` | An active detector changes at once. |
+| `delete_detector(uuid)` | `DELETE /api/v1/admin/detectors/{uuid}` | |
+| `test_detector(ws_id, uuid, text)` | `POST /api/v1/workspaces/{ws}/detectors/{uuid}/test` | |
+
+## Guardrails
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `guardrails(ws_id=None)` | `GET /api/v1/workspaces/{ws}/guardrails` or `GET /api/v1/admin/guardrails` | |
+| `guardrail(gid)` | `GET /api/v1/admin/guardrails/{id}` | |
+| `guardrail_by_name(ws_id, name)` | as `guardrails` | `ws_id=None` searches org guardrails. |
+| `create_guardrail(ws_id, name, detector_ids, description)` | `POST /api/v1/workspaces/{ws}/guardrails` | Needs at least one detector. |
+| `update_guardrail(ws_id, gid, name, detector_ids, description)` | `PUT /api/v1/workspaces/{ws}/guardrails/{id}` | |
+| `delete_guardrail(gid, ws_id=None)` | `DELETE /api/v1/workspaces/{ws}/guardrails/{id}` or `DELETE /api/v1/admin/guardrails/{id}` | |
+| `test_guardrail(text, detector_ids, guardrail_id=, deny_suspicious_characters=)` | `POST /api/v1/admin/guardrails/test` | Scans text without an LLM. |
+
+## Policies
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `policies(ws_id=None)` | `GET /api/v1/workspaces/{ws}/policies` or `GET /api/v1/admin/policies` | |
+| `policy(pid)` | `GET /api/v1/admin/policies/{id}` | |
+| `policy_by_name(ws_id, name)` | as `policies` | |
+| `create_policy(ws_id, name, input_guardrail_ids, output_guardrail_ids, provider_ids=, description=, response_scan_mode=)` | `POST /api/v1/workspaces/{ws}/policies` | `provider_ids` grants all of those providers' models; some builds require at least one. |
+
+| `delete_policy(pid, ws_id=None)` | `DELETE /api/v1/workspaces/{ws}/policies/{id}` or `DELETE /api/v1/admin/policies/{id}` | |
+
+## Approval workflow
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `submit(ws_id, kind, obj_id)` | `POST /api/v1/workspaces/{ws}/{kind}/{id}/submit` | `kind`: `detectors`, `guardrails`, `policies`. |
+| `approve(kind, obj_id)` | `POST /api/v1/admin/{kind}/{id}/approve` | |
+| `reject(kind, obj_id, reason)` | `POST /api/v1/admin/{kind}/{id}/reject` | |
+| `review_queue()` | `GET /api/v1/admin/review-queue` | Map an item's `type` with `QUEUE_KIND`. |
+
+See also [`approve_new`](reference/helpers.md#pyfortiaigate.approve_new).
+
+## Virtual keys
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `virtual_keys(ws_id=None, status=)` | `GET /api/v1/workspaces/{ws}/virtual-keys` or `GET /api/v1/admin/virtual-keys` | |
+| `virtual_key(key_id)` | `GET /api/v1/admin/virtual-keys/{id}` | |
+| `create_virtual_key(ws_id, name, policy_ids=, provider_ids=, expires_at=, tpm=, rpm=)` | `POST /api/v1/workspaces/{ws}/virtual-keys` | The secret is returned once. |
+| `update_virtual_key(key_id, expires_at=, tpm=, rpm=, policy_ids=)` | `GET` + `PUT /api/v1/admin/virtual-keys/{id}` | Resends the record's writable fields with your changes. |
+| `rotate_virtual_key(key_id)` | `POST /api/v1/admin/virtual-keys/{id}/rotate` | New secret, once. |
+| `revoke_virtual_key(key_id, reason)` | `POST /api/v1/admin/virtual-keys/{id}/revoke` | The secret stops working; a reason is required. |
+| `delete_virtual_key(key_id)` | `DELETE /api/v1/admin/virtual-keys/{id}` | |
+
+## Providers, models & audit
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `ai_providers()` | `GET /api/v1/admin/ai-providers` | |
+| `model_groups()` | `GET /api/v1/model-groups` | Member public names are what `chat_completion` takes as `model`. |
+| `dlp_labels()` | `GET /api/v1/admin/dlp-labels` | Category names for `dlp_detector_body`. |
+| `audit_logs(offset, limit)` | `GET /api/v1/admin/audit-logs` | |
+| `audit_log_filter_options()` | `GET /api/v1/admin/audit-logs/filter-options` | |
+
+## Gateway (data plane)
+
+Authenticated with a virtual key secret, never the session.
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `check_key(api_key)` | `GET /ai/openai/v1/models` | `{"valid", "model_count", "http_status"}`. |
+| `chat_completion(api_key, model, messages, max_tokens=, temperature=, **extra)` | `POST /ai/openai/v1/chat/completions` | A guardrail block is a 200; test it with `blocked()`. |

pyfortiaigate-0.1.0/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

pyfortiaigate-0.1.0/docs/guide/approval.md

@@ -0,0 +1,45 @@
+# Approval workflow
+
+Detectors, guardrails and policies created inside a workspace start as
+**draft** and only take effect once an org admin approves them:
+
+```
+draft --submit--> pending --approve--> active
+                          --reject---> rejected
+```
+
+Editing an **active** guardrail or detector applies immediately, with no
+re-approval.
+
+## As the org admin
+
+`approve_new` walks a freshly created object to active in one call:
+
+```python
+det = faig.create_detector(ws_id, body)
+approve_new(faig, ws_id, "detectors", det)
+```
+
+If another approver gets there first (the object is no longer pending), that is
+not an error.
+
+## Reviewing what others submitted
+
+```python
+from pyfortiaigate import QUEUE_KIND
+
+for item in faig.review_queue():
+    faig.approve(QUEUE_KIND[item["type"]], item["id"])
+```
+
+## Body builders
+
+The API accepts bodies that store fine and then do nothing. The builders encode
+the shapes that work:
+
+- `regex_detector_body(name, [(rule_name, pattern, disposition)])` fills the
+  flat `rules` list the engine matches on, not just the editor's `regexRules`
+  (which alone matches nothing), and refuses an empty rule list.
+- `dlp_detector_body(name, categories)` uses `disposition` (not `action`);
+  category names come from `dlp_labels()`.
+- `guardrail_body(name, detector_ids)` refuses a guardrail with no detectors.

pyfortiaigate-0.1.0/docs/guide/auth.md

@@ -0,0 +1,46 @@
+# Authentication & TLS
+
+## Session login
+
+```python
+faig = FortiAIGate("https://faig.example.com", "a@example.com", "<password>")
+```
+
+The login name is the account's **email** (the built-in administrator is
+`admin`). The client logs in on its first call, not in the constructor, so
+creating a client never touches the network. Call `login()` to fail fast.
+
+Sessions expire (about 24 minutes on 8.0.2). A `401` means nothing was applied,
+so the client logs in again and resends the request once. A second `401` raises
+`FaigError`.
+
+Every mutation (POST, PUT, PATCH, DELETE) carries a fresh `X-CSRF-Token`
+fetched just before it. A `403` that names the CSRF token is retried once with
+a new token.
+
+## Bearer token
+
+```python
+faig = FortiAIGate("https://faig.example.com", token="<token>")
+```
+
+No login and no CSRF exchange; a `401` is raised as-is.
+
+## Virtual keys are not API credentials
+
+A virtual key (`faig_...`) authenticates on the **gateway** only. Pass it to
+`check_key` or `chat_completion`; it is never accepted on `/api/v1/*`.
+
+## TLS
+
+| `verify=` | Behaviour |
+|---|---|
+| `True` (default) | System trust store. |
+| `"/path/ca.pem"` | Trust the CA that signed the appliance's certificate. Use this for a self-signed appliance. |
+| `False` | No verification. Only for an isolated lab you control. |
+
+## Errors
+
+Every HTTP status >= 400 raises `FaigError` with `.status`, `.method`, `.path`
+and the raw response `.body`. The message uses the response's `error`,
+`message` or `detail` field when there is one.

pyfortiaigate-0.1.0/docs/guide/gateway.md

@@ -0,0 +1,36 @@
+# Virtual keys & the gateway
+
+## Creating a key
+
+```python
+key = faig.create_virtual_key(ws_id, "app", policy_ids=[policy_id], provider_ids=["openai"])
+secret = secret_from_response(key)  # returned ONCE; store it now
+```
+
+The secret is never readable again. It embeds the key's id, so code that only
+holds the secret can still manage the key:
+
+```python
+faig.revoke_virtual_key(key_id_from_secret(secret))
+```
+
+`rotate_virtual_key` returns a new secret, once, the same way.
+`update_virtual_key` reads the current record and resends it with your changes,
+because the API replaces the whole record; `policy_ids` replaces the attached
+policy list.
+
+## Using a key
+
+```python
+faig.check_key(secret)
+# {"valid": True, "model_count": 4, "http_status": 200}
+
+reply = faig.chat_completion(secret, "gpt-4o-mini", [{"role": "user", "content": "hi"}])
+```
+
+The gateway applies the key's policies. **A guardrail block is not an error:**
+the gateway answers HTTP 200 with `finish_reason: "content_filter"`. Test for it
+with `blocked(reply)`.
+
+If the gateway is served from a different host than the management console,
+pass `gateway_url=` to the client.