Skip to main content
Documentation

AdaptsAPI Client

A Python client library and CLI for the Adapts API: generate wiki docs and prompt flows via API Gateway → SNS.

PyPI version Python 3.12+ Test Coverage

Features

  • 🚀 Python clients for generate-docs (adaptsapi.generate_docs) and prompt (adaptsapi.prompt)
  • 🔑 Token loading via ADAPTS_API_TOKEN, ADAPTS_API_KEY, config.json, or interactive prompt
  • 📄 CLI payloads from --data or --payload-file
  • 🔧 config.json URLs: base_url / api_base_url plus generate_wiki_docs_metadata and prompt_metadata (url or path)
  • ✅ Validation: Pydantic models for prompt requests; schema checks for generate-docs payloads
  • 🧪 Test suite with high coverage; integration demos under tests/integ/
  • 🤖 GitHub Actions examples for wiki documentation
  • 📦 CLI: adaptsapi (--generatedoc | --prompt) …

Installation

From PyPI

pip install adaptsapi

From Source

git clone https://github.com/AdaptsAI/adapts_api_client.git
cd adapts_api_client
pip install -e .

Quick Start

1. Set up your API token

load_token() resolves credentials in this order:

  1. ADAPTS_API_TOKEN or ADAPTS_API_KEY (recommended for CI/CD)
  2. token in ./config.json
  3. Interactive prompt (CLI saves token to config.json)
export ADAPTS_API_TOKEN="your-api-token-here"
# or: export ADAPTS_API_KEY="your-api-token-here"

Optional config.json (same directory you run the CLI from) for base URL and per-operation paths:

{
  "token": "your-api-token-here",
  "base_url": "https://prod.api.adapts.ai",
  "generate_wiki_docs_metadata": {
    "path": "/generate_wiki_docs"
  },
  "prompt_metadata": {
    "path": "/prompt"
  }
}

You can set a full URL per operation with "url" instead of "path". Legacy endpoint (full generate-docs URL, or host-only base) is still supported—see Configuration.

First-time CLI without env or token in config:

adaptsapi --generatedoc --data '{"test": "payload"}'
# Prompts for token and merges into config.json

2. Using the Python client (generate docs)

from adaptsapi.config import load_token
from adaptsapi.generate_docs import (
    PayloadValidationError,
    default_generate_docs_url,
    post,
)

payload = {
    "email_address": "user@example.com",
    "user_name": "john_doe",
    "repo_object": {
        "repository_name": "my-repo",
        "source": "github",
        "repository_url": "https://github.com/user/my-repo",
        "branch": "main",
        "size": "12345",
        "language": "python",
        "is_private": False,
        "git_provider_type": "github",
        "refresh_token": "github_token_here",
    },
}

try:
    endpoint = default_generate_docs_url()
    if not endpoint:
        raise RuntimeError("Configure generate_wiki_docs_metadata, endpoint, or base_url in config.json")
    response = post(endpoint, load_token(), payload)
    response.raise_for_status()
    print("Success:", response.json())
except PayloadValidationError as e:
    print("Validation error:", e)

2b. Using the Python client (prompt API)

from adaptsapi.config import load_token
from adaptsapi.prompt import PayloadValidationError, default_prompt_url, post as post_prompt

payload = {
    "action": "your_action",
    "prompt": "Your prompt text",
    "repo_object": {
        "repository_name": "my-repo",
        "source": "github",
        "repository_url": "https://github.com/user/my-repo",
        "branch": "main",
        "size": "12345",
        "language": "python",
        "is_private": False,
        "git_provider_type": "github",
    },
}

try:
    response = post_prompt(default_prompt_url(), load_token(), payload)
    response.raise_for_status()
    print("Success:", response.json())
except PayloadValidationError as e:
    print("Validation error:", e)

3. Using the CLI

Omit --endpoint when config.json supplies defaults (see above).

Generate docs (inline JSON):

adaptsapi --generatedoc \
  --endpoint "https://prod.api.adapts.ai/generate_wiki_docs" \
  --data '{"email_address": "user@example.com", "user_name": "john_doe", "repo_object": {...}}'

Generate docs (payload file):

adaptsapi --generatedoc \
  --endpoint "https://prod.api.adapts.ai/generate_wiki_docs" \
  --payload-file payload.json

Prompt API:

adaptsapi --prompt --data '{"action":"...","prompt":"...","repo_object":{...}}'
adaptsapi --prompt --payload-file prompt_payload.json

Testing

The suite includes unit tests, CLI/config tests, and optional integration demos.

Running tests

# Full check (pytest + lint + mypy) — same as `make test`
python run_tests.py --type all

# Makefile (uses `.venv/bin/python` when present)
make test

Pytest only:

python -m pytest
python -m pytest -v
python -m pytest tests/test_generate_docs.py
python -m pytest --cov=src/adaptsapi --cov-report=html

Test runner:

python run_tests.py --type unit
python run_tests.py --type integration   # needs ADAPTS_API_TOKEN / ADAPTS_API_KEY for live calls
python run_tests.py --type coverage
python run_tests.py --type integration --api-key "your-api-key"

Categories

  • Unit: mocked HTTP and fast paths
  • Integration / API: real calls when marked @pytest.mark.integration or @pytest.mark.api and credentials are set
  • tests/integ/: runnable demos (test_generate_docs_demo.py, test_prompt_demo.py, test_workflow.py)

Test Coverage

The test suite covers:

  • ✅ Payload Validation: All validation logic and error cases
  • ✅ Metadata Population: Automatic metadata generation
  • ✅ API Calls: HTTP request handling and error management
  • ✅ CLI Functionality: Command-line argument parsing and file handling
  • ✅ Configuration: Token loading and config file management

Integration demos

Runnable modules under tests/integ/ (pytest or python tests/integ/...):

  • test_generate_docs_demo.py — validation, metadata, optional live generate-docs call
  • test_prompt_demo.py — prompt payload and optional live call
  • test_workflow.py — end-to-end style walkthrough

Set ADAPTS_API_TOKEN or ADAPTS_API_KEY for live requests.

Usage

Command Line Options

adaptsapi (--generatedoc | --prompt) [OPTIONS]
OptionDescriptionRequired
--generatedocPOST a generate-docs / wiki payloadOne of --generatedoc or --prompt
--promptPOST a prompt-API payloadOne of --generatedoc or --prompt
--endpoint URLFull API URLNo (defaults from config.json per operation)
--data JSONInline JSON payload stringYes (or --payload-file)
--payload-file FILEPath to JSON payload fileYes (or --data)
--timeout SECONDSRequest timeout in seconds (default: 30)No

Payload Structure

For documentation generation, your payload should follow this structure:

{
  "email_address": "user@example.com",
  "user_name": "github_username",
  "repo_object": {
    "repository_name": "my-repo",
    "source": "github",
    "repository_url": "https://github.com/user/my-repo",
    "branch": "main",
    "size": "12345",
    "language": "python",
    "is_private": false,
    "git_provider_type": "github",
    "refresh_token": "github_token_here"
  }
}

Required Fields

  • email_address: Valid email address
  • user_name: Username string
  • repo_object.repository_name: Repository name
  • repo_object.repository_url: Full repository URL
  • repo_object.branch: Branch name
  • repo_object.size: Repository size as string
  • repo_object.language: Primary programming language
  • repo_object.source: Source platform (e.g., "github")

Optional Fields

  • repo_object.is_private: Boolean indicating if repo is private
  • repo_object.git_provider_type: Git provider type
  • repo_object.installation_id: Installation ID (for GitHub Apps)
  • repo_object.refresh_token: Refresh token for authentication
  • repo_object.commit_hash: Specific commit hash
  • repo_object.commit_message: Commit message
  • repo_object.commit_author: Commit author
  • repo_object.directory_name: Specific directory to process

GitHub Actions Integration

This package is designed to work seamlessly with GitHub Actions for automated documentation generation. Here's an example workflow:

name: Generate Wiki Docs

on:
  pull_request:
    branches: [ main ]
    types: [ closed ]

jobs:
  call-adapts-api:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          
      - name: Install adaptsapi
        run: pip install adaptsapi
        
      - name: Generate documentation
        env:
          ADAPTS_API_TOKEN: ${{ secrets.ADAPTS_API_TOKEN }}
        run: |
          python -c "
          import os
          from adaptsapi.generate_docs import post
          
          payload = {
              'email_address': '${{ github.actor }}@users.noreply.github.com',
              'user_name': '${{ github.actor }}',
              'repo_object': {
                  'repository_name': '${{ github.event.repository.name }}',
                  'source': 'github',
                  'repository_url': '${{ github.event.repository.html_url }}',
                  'branch': 'main',
                  'size': '0',
                  'language': 'python',
                  'is_private': False,
                  'git_provider_type': 'github',
                  'refresh_token': '${{ secrets.GITHUB_TOKEN }}'
              }
          }
          
          resp = post(
              'https://prod.api.adapts.ai/generate_wiki_docs',
              os.environ['ADAPTS_API_TOKEN'],
              payload
          )
          resp.raise_for_status()
          print('Documentation generated successfully')
          "

Setting up GitHub Secrets

  1. Go to your repository on GitHub
  2. Click Settings → Secrets and variables → Actions
  3. Click New repository secret
  4. Add ADAPTS_API_TOKEN (recommended) or ADAPTS_API_KEY with your API token value

If the repository already stores the token under ADAPTS_API_KEY, map it in the workflow: ADAPTS_API_TOKEN: ${{ secrets.ADAPTS_API_KEY }}.

Configuration

config.json

Placed in the current working directory. Common keys:

KeyPurpose
tokenAPI key (if not using env)
base_url / api_base_urlAPI host; paths below are appended
generate_wiki_docs_metadata{ "url": "..." } or { "path": "/generate_wiki_docs" }
prompt_metadata{ "url": "..." } or { "path": "/prompt" }
endpointLegacy full generate-docs URL, or host-only base

Override the host with ADAPTS_API_BASE_URL.

Example (paths + base):

{
  "token": "your-api-token-here",
  "base_url": "https://prod.api.adapts.ai",
  "generate_wiki_docs_metadata": { "path": "/generate_wiki_docs" },
  "prompt_metadata": { "path": "/prompt" }
}

Example (legacy single endpoint):

{
  "token": "your-api-token-here",
  "endpoint": "https://prod.api.adapts.ai/generate_wiki_docs"
}

Environment variables

VariablePurpose
ADAPTS_API_TOKEN / ADAPTS_API_KEYAPI key (load_token() checks both)
ADAPTS_API_BASE_URLBase URL when not set in config.json

Error Handling

The library provides comprehensive error handling:

  • PayloadValidationError: Raised when payload validation fails
  • ConfigError: Raised when no token can be found or loaded
  • requests.RequestException: Raised on network failures
  • JSONDecodeError: Raised for invalid JSON in config files

Common Error Scenarios

  • Missing token: CLI prompts for interactive token input
  • Invalid JSON: Shows JSON parsing errors
  • API errors: Displays HTTP status codes and error messages
  • Payload validation: Shows specific validation failures with field names

API reference

adaptsapi.generate_docs

  • post(endpoint, token, payload, timeout=30) — Validate payload, populate metadata, POST with x-api-key.
  • default_generate_docs_url() — Returns the generate-docs URL from config, or None if unset (wraps load_default_endpoint()).

Private helpers _validate_payload and _populate_metadata implement schema checks and metadata fields.

adaptsapi.prompt

  • post(endpoint, token, payload, *, timeout=30, enrich=True) — Pydantic-validated prompt request; optional enrichment like generate-docs.
  • default_prompt_url(...) — Full prompt URL from prompt_metadata + base, or overrides.

Re-exports PromptRequest, RepoObject, WikiObject, MetaData (see adaptsapi.models).

adaptsapi.config

  • load_token() — ADAPTS_API_TOKEN / ADAPTS_API_KEY, then config.json token, then prompt.
  • load_api_base_url() — ADAPTS_API_BASE_URL, then api_base_url / base_url / legacy host-only endpoint, then default prod base.
  • load_default_endpoint() — Default generate-docs URL (metadata block, then legacy endpoint, then base + default path).
  • load_prompt_url() — Full prompt URL from prompt_metadata or base + path.

CLI

  • adaptsapi.cli.main() — Entry point; requires --generatedoc or --prompt, payload via --data or --payload-file, optional --endpoint.

Support

Changelog

v0.1.9 (latest)

  • Prompt API client, Pydantic models, and config.json metadata blocks (generate_wiki_docs_metadata, prompt_metadata)
  • CLI requires --generatedoc or --prompt; shared --payload-file / --data
  • load_token() accepts ADAPTS_API_TOKEN or ADAPTS_API_KEY
  • Python 3.12+

v0.1.4 and earlier

  • Generate-docs client, CLI, tests, and legacy endpoint-only configuration