Skip to content

README.md

Latest commit

 

History

History
138 lines (110 loc) · 5.28 KB

README.md

File metadata and controls

138 lines (110 loc) · 5.28 KB

← Back to AIPass

API

Purpose: Centralized external API gateway — authenticated service clients for all external APIs (OpenRouter, Google, future providers). Module: aipass.api Last Updated: 2026-04-07

Overview

What I Do

  • Provide authenticated service clients for external APIs (Google Drive, OpenRouter, etc.)
  • Manage OAuth2 flows, credential storage, and token refresh
  • Offer thread-safe service factories for concurrent consumers
  • Handle API key management and validation across providers
  • Provide SSL retry and connection resilience utilities

What I Don't Do

  • Host business logic — consumers own what they do with the service
  • Set default models or configs — consumers provide their own
  • Manage application workflows, polling loops, or orchestration

How I Work

  • Entry Point: apps/api.py -- auto-discovers and routes to modules
  • Pattern: Standard AIPass 3-tier architecture (entry point / modules / handlers)
  • Design principle: If it's not auth, credentials, or service factory — it doesn't belong here

Commands / Usage

drone @api get-key           # Retrieve API key for provider
drone @api validate          # Validate API credentials and connection
drone @api validate google   # Validate Google OAuth2 credentials
drone @api reauth google     # Re-authenticate Google OAuth2
drone @api test              # Test OpenRouter connection status
drone @api models [--all]    # List available models from provider
drone @api status            # Check OpenRouter client status
drone @api call "prompt" --model MODEL  # Make API call to model
drone @api list-providers    # List available API providers
drone @api init              # Initialize .env template
drone @api track <gen_id>    # Track API usage metrics
drone @api stats             # Display API usage statistics
drone @api session           # Show session usage data
drone @api caller-usage <caller>  # Show usage by caller module
drone @api cleanup [days]    # Clean up old usage data *(not operational — fails with no data)*
drone @api --help            # Full help output
drone @api --version         # Show version

Running drone @api with no arguments displays module introspection (discovered modules and status).

Cross-Branch API

# LLM access (OpenRouter)
from aipass.api.apps.modules.openrouter_client import get_response
response = get_response(prompt="...", model="anthropic/claude-3.5-sonnet", caller="flow")

# Google Drive (or any Google API)
from aipass.api.apps.modules.google_client import get_drive_service
service = get_drive_service()                   # Single-threaded
service = get_drive_service(thread_safe=True)   # For concurrent workers

# Any Google service
from aipass.api.apps.modules.google_client import get_google_service
service = get_google_service("calendar", "v3")

# Retry utility for raw API calls
from aipass.api.apps.modules.google_client import api_call_with_retry

Architecture

api/
├── __init__.py                    # Public API exports
├── apps/
│   ├── api.py                     # Entry point (module discovery, command routing)
│   ├── modules/
│   │   ├── api_key.py             # Key retrieval and validation logic
│   │   ├── openrouter_client.py   # OpenRouter API client
│   │   ├── google_client.py       # Google API services (Drive, Calendar, etc.)
│   │   └── usage_tracker.py       # Usage metrics tracking
│   └── handlers/
│       ├── auth/
│       │   ├── env.py             # Environment variable credential loading
│       │   └── keys.py            # API key storage and retrieval
│       ├── config/
│       │   └── provider.py        # Provider configuration management
│       ├── google/
│       │   ├── auth.py            # OAuth2 lifecycle, credential I/O
│       │   ├── service_factory.py # Service object factory (single + thread-safe)
│       │   └── retry.py           # SSL retry with exponential backoff
│       ├── json/
│       │   └── json_handler.py    # JSON operation logging
│       ├── openrouter/
│       │   ├── caller.py          # HTTP request execution
│       │   ├── client.py          # OpenRouter client implementation
│       │   ├── models.py          # Model discovery and listing
│       │   └── provision.py       # Provider provisioning
│       └── usage/
│           ├── aggregation.py     # Usage data aggregation
│           ├── cleanup.py         # Usage data cleanup
│           └── tracking.py        # Usage event tracking
└── README.md

Integration Points

Depends On

  • aipass.prax -- structured logging via system_logger
  • aipass.cli -- Rich console output formatting

Provides To

  • All branches -- authenticated external API clients
  • System-wide API key management and credential validation

Credentials

  • ~/.secrets/aipass/.env -- API keys (OpenRouter, etc.)
  • ~/.secrets/aipass/google_creds.json -- Google OAuth2 tokens
  • ~/.secrets/aipass/google_client_secret.json -- Google OAuth app config

Last Updated: 2026-04-07

← Back to AIPass