ask2api 1.2.0
A minimal CLI tool that turns natural language into instant APIs.
License: MIT
Requires Python: >=3.9

# ask2api

[![CI](https://github.com/atasoglu/ask2api/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/atasoglu/ask2api/actions/workflows/pre-commit.yml)
[![PyPI version](https://img.shields.io/pypi/v/ask2api)](https://pypi.org/project/ask2api/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`ask2api` is a minimal Python CLI tool that turns natural language prompts into structured API-style JSON responses using LLM.

It allows you to define a JSON Schema and force the model to answer strictly in that format.

## Why ask2api?

Because LLMs are no longer just chatbots, they are also programmable API engines.

`ask2api` lets you use them that way. 🚀

Key features:

- Minimal dependencies  
- CLI first  
- Prompt → API behavior  
- No markdown, no explanations, only valid JSON  
- Vision modality support
- Designed for automation pipelines and AI-driven backend workflows

## Installation

```bash
pip install ask2api
```

Set your API key:

```bash
export ASK2API_API_KEY="your_api_key"
# Or you can pass OpenAI key
# export OPENAI_API_KEY="your_api_key"
```

## Provider Support

`ask2api` supports both OpenAI (and OpenAI-compatible) and Anthropic (Claude) models.

### Using OpenAI (default)

By default, `ask2api` uses OpenAI. No additional configuration is needed:

```bash
export OPENAI_API_KEY="sk-..."
ask2api -p "What is 2+2?" -e '{"result": 1}'
```

### Using Anthropic Claude

To use Anthropic's Claude models, set the provider explicitly:

```bash
export ASK2API_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="sk-ant-..."
ask2api -p "What is the capital of France?" -e '{"country": "string", "city": "string"}'
```

You can also customize the model:

```bash
export ASK2API_PROVIDER="anthropic"
export ASK2API_API_KEY="sk-ant-..."
export ASK2API_MODEL="claude-opus-4-5"
ask2api -p "Analyze carbon" -e '{"symbol": "string", "atomic_number": 1}'
```

Anthropic's Claude models support vision as well:

```bash
export ASK2API_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="sk-ant-..."
ask2api -p "What's in this image?" -e '{"description": "string"}' -i photo.jpg
```

## Usage

### Text-only prompts

Instead of asking:

> *"Where is the capital of France?"*

and receiving free-form text, you can do this:

```bash
ask2api -p "Where is the capital of France?" -sf schema.json
```

Or pass an example directly without a schema file:

```bash
ask2api -p "Where is the capital of France?" -e '{"country": "string", "city": "string"}'
```

And get a structured API response:

```json
{
  "country": "France",
  "city": "Paris"
}
```

<details>

<summary>For more complex structures with different data types:</summary>

```bash
ask2api -p "Analyze carbon element" -e '{
  "symbol": "element symbol",
  "atomic_number": 1234,
  "atomic_weight": 12.34,
  "is_metal": true,
  "isotopes": ["name of the isotope"],
  "properties": {
    "melting_point": 1234.5,
    "boiling_point": 2345.6,
    "magnetic": true
  }
}'
```

Output:

```
{
  "symbol": "C",
  "atomic_number": 6,
  "atomic_weight": 12.011,
  "is_metal": false,
  "isotopes": [
    "C-12",
    "C-13",
    "C-14"
  ],
  "properties": {
    "melting_point": 3550,
    "boiling_point": 4827,
    "magnetic": false
  }
}
```

</details>

### Vision modality

You can also analyze images and get structured JSON responses:

```bash
ask2api -p "Where is this place?" -sf schema.json -i https://upload.wikimedia.org/wikipedia/commons/6/64/Lesdeuxmagots.jpg
```

<details>

<summary><b>Note:</b> Some API providers may not accept image URLs...</summary>

...and require images to be provided as base64-encoded data (i.e., a local file). If you encounter problems using an image URL, download the image locally and pass the file path, then `ask2api` will base64-encode local files automatically.

Example (download with curl and run):

```bash
curl -sSL -o place.jpg "https://upload.wikimedia.org/wikipedia/commons/6/64/Lesdeuxmagots.jpg"
ask2api -p "Where is this place?" -sf schema.json -i ./place.jpg
```

Or download with wget:

```bash
wget -O place.jpg "https://upload.wikimedia.org/wikipedia/commons/6/64/Lesdeuxmagots.jpg"
```

</details>

## How it works

1. You define the desired output structure using a JSON Schema.
2. The schema is passed to the model:
   - For OpenAI: using the `json_schema` structured output format
   - For Anthropic: using tool calling with forced tool use
3. The system prompt enforces strict JSON-only responses.
4. For vision tasks, images are automatically encoded (base64 for local files) or passed as URLs.
5. The CLI prints the API-ready JSON output.

The model is treated as a deterministic API function, regardless of provider.

## Example schema

Create a file named `schema.json`:

```json
{
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "city": { "type": "string" }
  },
  "required": ["country", "city"]
}
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT