Overview

llm-project-generator creates a focused, standalone terminal chatbot project from a packaged provider template. Each generated project combines one provider SDK, Pydantic AI, Pydantic Settings, validated schemas, provider-specific configuration, and deterministic tests around a shared application structure.

It generates one-provider projects; it does not perform runtime multi-provider routing.

Quick start

Requirements: Python 3.13 or newer and uv.

The shortest path opens an interactive provider menu in a terminal:

uvx llm-project-generator init my-chatbot

For automation, select a provider explicitly. Non-interactive environments require --provider:

uvx llm-project-generator init my-chatbot --provider groq
uvx llm-project-generator init my-chatbot --provider google
uvx llm-project-generator init my-chatbot --provider openai
uvx llm-project-generator init my-chatbot --provider anthropic

For a persistent installation:

uv tool install llm-project-generator
llm-project-generator init my-chatbot

Multi-provider generation is available in version 0.2.0 and later.

Providers

Deterministic verification covers generation, imports, configuration, mocked provider construction, and shared chatbot behavior. Live verification covers real authentication, model availability, and provider responses. Only Groq has completed both so far.

Use a generated project

cd my-chatbot
uv sync
cp .env.example .env

Open .env in an editor and add the required API key for the provider you selected. LLM_MODEL is an optional model override; when it is omitted, the selected provider's default model is used. The generator never requests or copies API keys. The generated .env does not exist until you create it and is ignored by Git.

Run the chatbot and its deterministic tests:

uv run llm-chat
uv run pytest

Features

• Interactive or explicit provider selection.
• Provider-isolated generated dependencies.
• Pydantic validation for settings and chat messages.
• Conversation history within a terminal session.
• Deterministic fake-model and mocked provider tests.
• Safe destination policy with no force, overwrite, or delete behavior.
• Packaged templates available from the installed wheel.
• No generator runtime dependencies.

Architecture

                         llm-project-generator
                                  |
                    +-------------+-------------+
                    |                           |
          Common chatbot resources      Provider overlay
                    |                           |
                    +-------------+-------------+
                                  |
                         Generated project
                                  |
                  config -> provider -> LLM API

Common resources own the terminal loop, chat orchestration, reply execution, schemas, exceptions, and shared tests. Each overlay owns its environment example, README, dependency metadata, provider configuration, provider construction, and provider tests.

Generated structure

my-chatbot/
|-- .env.example
|-- .gitignore
|-- LICENSE
|-- README.md
|-- pyproject.toml
|-- src/
|   `-- app/
|       |-- __init__.py
|       |-- chat.py
|       |-- client.py
|       |-- config.py
|       |-- exceptions.py
|       |-- main.py
|       |-- provider.py
|       `-- schemas.py
`-- tests/

Safety

The destination parent must already exist, and the destination itself must not exist. Existing files and directories are never overwritten; there is no force or delete behavior.

The generator never creates .env, requests API keys, or copies secrets. Generated configuration uses SecretStr. Model output is probabilistic and untrusted; it is not an authorization or security boundary.

Automated generated tests use fake models and mocks and do not make real provider requests.

Project names and destinations

Project names may contain ASCII letters, numbers, dots, underscores, and hyphens. They must begin and end with a letter or number. Runs of dots, underscores, and hyphens are normalized into lowercase hyphens for distribution metadata. The destination parent must exist, and the destination itself must not already exist. A filesystem failure during generation can leave a partial destination; inspect it or remove it before retrying.

Verification status

The four provider implementations have deterministic generated-suite coverage. Groq has also completed live verification. Google Gemini, OpenAI, and Anthropic Claude live checks remain pending billing/support availability, so this preview does not claim all providers are production-ready or live-verified.

Development

git clone https://github.com/Talhaahmad9/llm-project-generator.git
cd llm-project-generator
uv sync --dev
uv run pytest
uv build --no-sources

CI generates and tests all four provider projects without provider credentials.

Limitations and roadmap

This preview provides a terminal interface only, generates one provider per project, requires Python 3.13+, does not create API keys, does not overwrite existing destinations, and does not make live calls in automated tests. Three live-verification checks are pending.

The next milestones are to complete remaining live verification and prepare the criteria for 1.0.0. Future work such as FastAPI or RAG belongs to separate product milestones; it is not part of the generated chatbot today.

Contributing

Create a focused branch, run the root tests and build locally, and keep provider resources explicitly allowlisted. Pull requests should preserve deterministic tests and must not add credentials or live API calls.

Author and license

Built by Talha Ahmad. Licensed under the MIT License.