Metadata-Version: 2.4
Name: llm-project-generator
Version: 0.1.1
Summary: Generate a tested Groq terminal chatbot project
Keywords: llm,groq,pydantic-ai,cli,project-generator
Author: Talha Ahmad
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/Talhaahmad9/llm-project-generator
Project-URL: Repository, https://github.com/Talhaahmad9/llm-project-generator
Project-URL: Issues, https://github.com/Talhaahmad9/llm-project-generator/issues
Description-Content-Type: text/markdown

# llm-project-generator

`llm-project-generator` creates a ready-to-run LLM chatbot project from a reviewed, packaged template.

## Current status

V1 supports only Groq. Groq is included because this template has been live verified. Other providers are not advertised or generated yet.

## Requirements

- Python 3.13 or newer
- [uv](https://docs.astral.sh/uv/)

The generator itself has no runtime dependencies. It uses the standard Python library and includes its template assets in the installed package.

## Quick start

### PyPI with uvx

After the package is published on PyPI, run it without permanently installing it:

```bash
uvx llm-project-generator init my-chatbot --provider groq
```

### Persistent installation

After PyPI publication, install the command for repeated use:

```bash
uv tool install llm-project-generator
llm-project-generator init my-chatbot --provider groq
```

### Tagged GitHub release

The currently valid tagged fallback is:

```bash
uvx --from git+https://github.com/Talhaahmad9/llm-project-generator.git@v0.1.0 llm-project-generator init my-chatbot --provider groq
```

This is longer because uv must be told both the Git source and the executable name. `v0.1.0` contains the same Groq generator functionality, while `v0.1.1` prepares the package metadata for PyPI.

### Development from a clone

From the repository root:

```bash
uv sync --dev
uv run llm-project-generator --help
uv run llm-project-generator init my-chatbot --provider groq
```

## What it creates

The command creates a new destination containing the reviewed Groq chatbot:

```text
.env.example
.gitignore
LICENSE
README.md
pyproject.toml
src/app/
tests/
```

The generated project keeps the `app` Python package, deterministic fake-model tests, the `llm-chat` console entry point, and the default model `groq:openai/gpt-oss-120b`.

## Run a generated chatbot

Enter the generated project and install its dependencies:

```bash
cd <destination>
uv sync
cp .env.example .env
```

Edit `.env` and add your own `GROQ_API_KEY`. `LLM_MODEL` is optional and can override the default model. Then start the chatbot:

```bash
uv run llm-chat
```

`.env.example` is generated as a placeholder. `.env` is excluded by the template's `.gitignore` and is never generated or copied by this project. Never put a real key in source control.

## Project names and destinations

The distribution name comes from the destination directory name. Names may contain ASCII letters, numbers, periods, underscores, and hyphens; they must begin and end with a letter or number. Spaces and invalid boundary characters are rejected. Period, underscore, and hyphen runs are normalized to one lowercase hyphen: `My_Project` becomes `my-project`.

The destination's parent directory must already exist. The destination itself must not exist, even if it is empty. Existing files and directories are never overwritten, and V1 has no force or delete behavior. An operating-system write failure may leave partial output in the destination.

## Development and testing

Install development dependencies and run the root test suite with:

```bash
uv sync --dev
uv run pytest
```

The root tests exercise provider resolution, resource loading, generation, and CLI behavior. The chatbot tests are packaged template assets; they are not collected from their packaged location by the generator's root test suite.

## Layout

```text
src/llm_project_generator/                    generator package
src/llm_project_generator/project_templates/  packaged template assets
tests/                                        generator tests
```

## Security

The generator does not request, create, inspect, or copy API keys. It creates only `.env.example`; users supply their own secret in a local `.env`, which is excluded from version control.

The generator and generated application use deterministic validation, configuration, file selection, and error handling. LLM responses are probabilistic output from the selected provider and should not be treated as deterministic application logic or as a security boundary.

## Limitations

V1 generates only the live-verified Groq chatbot. It does not generate other providers, overwrite existing destinations, delete output, run `uv sync` for the user, or execute the generated chatbot's tests.

## License

This project and its generated projects are licensed under the MIT License. Copyright (c) 2026 Talha Ahmad.

## Further reading

- [uv documentation](https://docs.astral.sh/uv/)
- [Groq documentation](https://console.groq.com/docs)
- [Pydantic AI documentation](https://ai.pydantic.dev/)
