Transform plain text into powerful AI prompts with async efficiency
APA is an async, provider-agnostic command-line tool that converts .txt files into structured prompts for leading LLM providers. Built on LiteLLM with enterprise-grade retry logic and clean architecture.
Features • Installation • Usage • Configuration • API • Contributing
|
|
|
|
apa/
├── 📄 configuration.toml # Runtime settings
├── 📄 system_prompt.toml # Customizable system prompt
├── 🐍 __init__.py
├── 🔧 config.py # Configuration loader
├── 📂 infrastructure/
│ └── 🔌 llm_client.py # Async LiteLLM wrapper
└── 📂 services/
└── 🎯 __init__.py # Service facade
📄 main.py # CLI entry point
🚀 run.sh # Environment helper
📋 requirements.txt # Dependencies
📦 pyproject.toml # Project metadata
- Python 3.13+
- API Key for at least one provider
- uv (recommended) or pip
# 1. Clone the repository
git clone https://github.com/yourusername/apa.git
cd apa
# 2. Create virtual environment
uv venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# 3. Install APA
uv pip install -e .
# 4. Set up your API key
echo "OPENAI_API_KEY=sk-..." > .envCreate a prompt file:
echo "Explain quantum computing in simple terms" > prompt.txtRun APA:
# Using the helper script (auto-loads .env)
./run.sh --msg-file prompt.txt
# Direct execution
python main.py --msg-file prompt.txt
# Force streaming mode
python main.py --msg-file prompt.txt --stream
# After installation
apa --msg-file prompt.txtimport asyncio
from apa.services import acompletion
from apa.config import load_settings
async def main():
cfg = load_settings()
# Non-streaming
response = await acompletion(
cfg.system_prompt,
"Explain the SOLID principles",
model="gpt-4",
stream=False
)
print(response)
# Streaming
stream = await acompletion(
cfg.system_prompt,
"Write a haiku about coding",
model="claude-3-7-sonnet",
stream=True
)
async for chunk in stream:
print(chunk, end='', flush=True)
asyncio.run(main())# Model parameters
temperature = 0.2 # Creativity level (0.0-1.0)
stream = true # Enable real-time streaming
# Provider-specific settings
programming_language = "Python" # Default language injected into system prompt
reasoning_effort = "high" # OpenAI o3/o4 models only
thinking_tokens = 16384 # Anthropic Claude models only
# Model selection
provider = "openai" # openai | anthropic | deepseek | openrouter
model = "o3" # Model identifier
# Fallback configuration (optional)
fallback_provider = "anthropic" # Provider to use if primary fails
fallback_model = "claude-sonnet-4-20250514" # Model to use if primary failsCustomize the AI assistant's behavior:
system_prompt = """
## Role
You are an advanced AI programming assistant specializing in $programming_language programming language...
## Task
Your tasks include...
"""
The only variable required is `programming_language`. The value comes from `configuration.toml`; if omitted it defaults to "Python".
### 🔐 Environment Variables
Create a `.env` file:
```bash
# Provider API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=anthropic-...
DEEPSEEK_API_KEY=...
OPENROUTER_API_KEY=...
| Feature | Supported Models |
|---|---|
| 🎯 Reasoning Effort | o3, o3-mini, o4, o4-mini |
| 🧠 Extended Thinking | Claude 3.7 Sonnet, Sonnet 4, Opus 4 |
| 👨💻 Developer Role | o1, o3, o4, gpt-4.1 |
| 🌡️ No Temperature | DeepSeek Reasoner, o1-o4 series |
APA automatically retries failed requests:
- 3 attempts maximum
- Exponential backoff: 2-8 seconds
- Smart error handling
APA includes an intelligent fallback system that automatically switches providers when the primary fails:
- Primary attempts: 3 tries with exponential backoff
- Automatic switchover: Seamlessly transitions to fallback provider
- Provider hot-swap: Loads provider-specific settings without restart
- Configurable: Set
fallback_providerandfallback_modelinconfiguration.toml
To disable fallback, simply omit these keys from your configuration.
Example configuration:
# Primary provider
provider = "openai"
model = "gpt-4"
# Fallback provider (activated after 3 primary failures)
fallback_provider = "anthropic"
fallback_model = "claude-sonnet-4-20250514"- Update
PROVIDER_ENV_MAPinapa/config.py - Add model capabilities to
llm_client.py - Test with your API key
- Retry Policy: Modify
@retrydecorator inllm_client.py - New Endpoints: Extend
acompletionin services - UI/API: Build on top of the async service layer
MIT License - see LICENSE for details.
Built with ❤️ by Kenny Dizi