Generate a function from description

<p align="center">
  <img src="docs/images/banner.png" alt="Agentic Programming" width="800">
</p>

<h1 align="center">Agentic Programming</h1>

<p align="center">
  <strong>Python functions that think.</strong><br>
  A programming paradigm where Python controls flow and LLM handles reasoning.
</p>

<p align="center">
  <a href="https://pypi.org/project/agentic-programming/"><img src="https://img.shields.io/pypi/v/agentic-programming?color=blue" alt="PyPI"></a>
  <a href="https://pepy.tech/project/agentic-programming"><img src="https://static.pepy.tech/badge/agentic-programming" alt="Downloads"></a>
  <a href="https://github.com/Fzkuji/Agentic-Programming/actions/workflows/ci.yml"><img src="https://github.com/Fzkuji/Agentic-Programming/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Fzkuji/Agentic-Programming/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Fzkuji/Agentic-Programming" alt="License"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/pypi/pyversions/agentic-programming" alt="Python"></a>
</p>

<p align="center">
  <a href="docs/GETTING_STARTED.md">Getting Started</a> &middot;
  <a href="docs/API.md">API Reference</a> &middot;
  <a href="docs/README_CN.md">中文</a>
</p>

---

> **This is a paradigm proposal.** Current LLM agent frameworks let the LLM control everything — what to do, when, and how. The result? Unpredictable execution, context explosion, and no output guarantees. We flip this: **Python controls the flow, LLM only reasons when asked.**

<p align="center">
  <img src="docs/images/code_hero.png" alt="Agentic Programming code example" width="800">
</p>

## Quick Start

### Prerequisites

Agentic Programming requires at least one LLM provider. Set up any one:

| Provider | Setup |
|----------|-------|
| Claude Code CLI | `npm i -g @anthropic-ai/claude-code && claude login` |
| Codex CLI | `npm i -g @openai/codex && codex auth` |
| Gemini CLI | `npm i -g @google/gemini-cli` |
| Anthropic API | `export ANTHROPIC_API_KEY=...` |
| OpenAI API | `export OPENAI_API_KEY=...` |
| Gemini API | `export GOOGLE_API_KEY=...` |

Then choose how you want to use it:

### Option A: Python — write agentic code

Install the package and start coding:

```bash
pip install agentic-programming          # core package
pip install "agentic-programming[openai]" # add API provider (or [anthropic], [gemini])
```

```python
from agentic import agentic_function, create_runtime

runtime = create_runtime()

@agentic_function
def login_flow(username, password):
    """Complete login flow."""
    observe(task="find login form")       # Python decides what to do
    click(element="login button")         # Python decides the order
    return verify(expected="dashboard")   # Python decides when to stop
```

### Option B: Skills — let your LLM agent use it

```bash
pip install agentic-programming
agentic install-skills                    # auto-detects Claude Code / Gemini CLI
```

Or manually:

```bash
git clone https://github.com/Fzkuji/Agentic-Programming.git
cp -r Agentic-Programming/skills/* ~/.claude/skills/    # Claude Code
cp -r Agentic-Programming/skills/* ~/.gemini/skills/    # Gemini CLI
```

Then talk to your agent: *"Create a function that extracts emails from text"*

The agent picks up the skill, calls `agentic create`, and the generated function handles everything from there.

### Option C: MCP — connect any MCP client

Install with the MCP extra, then add to your client config:

```bash
pip install "agentic-programming[mcp]"
```

```json
{
    "mcpServers": {
        "agentic": {
            "command": "python",
            "args": ["-m", "agentic.mcp"]
        }
    }
}
```

This starts a local MCP server that any compatible client (Claude Desktop, Cursor, VS Code, etc.) can connect to. Exposes: `list_functions`, `run_function`, `create_function`, `create_application`, `fix_function`.

Verify your setup with `agentic providers`.

---

## Why Agentic Programming?

<p align="center">
  <img src="docs/images/the_idea.png" alt="Python controls flow, LLM reasons" width="800">
</p>

| Principle | How |
|-----------|-----|
| **Deterministic flow** | Python controls `if/else/for/while`. Execution is guaranteed, not suggested. |
| **Minimal LLM calls** | Call the LLM only when reasoning is needed. 2 calls, not 10. |
| **Docstring = Prompt** | Change the docstring, change the LLM's behavior. No separate prompt files. |
| **Self-evolving** | Functions generate, fix, and improve themselves at runtime. |

<details>
<summary><strong>The problem with current frameworks</strong></summary>

<p align="center">
  <img src="docs/images/the_problem.png" alt="LLM as Scheduler" width="800">
</p>

Current LLM agent frameworks place the LLM as the central scheduler. This creates three fundamental problems:

- **Unpredictable execution** — the LLM may skip, repeat, or invent steps regardless of defined workflows
- **Context explosion** — each tool-call round-tr

... (truncated)