aistrap

A small command line tool that generates clean, ready-to-use AI/ML project structures from templates.

aistrap create my-rag-app --template rag
cd my-rag-app

You get a project that runs immediately: source layout, tests, configuration, .env.example, .gitignore, requirements.txt and a README that already knows your project's name.

Why this project exists

Starting a new AI project means making the same decisions again and again: where does the source go, how are settings loaded, where do datasets live, how do the tests find the code. Copying the last project's folders usually drags along things you no longer need.

aistrap gives you a sensible starting point in one command. The templates are deliberately small - you are meant to read them, understand every file in a couple of minutes, and then replace the parts you disagree with.

Features

• Ten templates covering plain Python AI, FastAPI, RAG, ML, autonomous agents, fullstack web applications, MCP servers, multimodal vision, streaming chat, and LLM evaluation.
• Generated projects actually run. Every template ships working code and a passing test suite - no stubs to fill in before you can check that it works.
• No paid APIs, no accounts. Deterministic/offline fallback modes let every project run immediately without requiring API keys or cloud accounts.
• No runtime dependencies. The CLI itself uses only the standard library.
• Safe by default. It refuses to write into a non-empty directory unless you confirm or pass --force.
• An environment check (doctor) that tells you what is installed without failing because an optional tool is missing.

Installation

pip install aistrap

Or install from source:

git clone https://github.com/ramalingamthangamani/Aistrap.git
cd aistrap
pip install .

Requires Python 3.9 or newer.

Quick start

# See what is available
aistrap list

# Create a project (defaults to the python-ai template)
aistrap create my-ai-app

# Or pick a template
aistrap create my-rag-app --template rag

cd my-rag-app
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pytest
python -m app.main "What is retrieval-augmented generation?"

CLI commands

create

aistrap create NAME [--template NAME] [--directory PATH] [--force]

If the target directory exists and is not empty, the command asks for confirmation. When it is not running interactively it stops instead, so nothing is overwritten by accident in a script.

$ aistrap create my-rag-app --template rag
OK Created my-rag-app from the rag template

my-rag-app/
├── app/
│   ├── __init__.py
│   ├── config.py
│   ├── ingestion.py
│   ├── main.py
│   └── retrieval.py
├── config/
│   └── .gitkeep
├── data/
│   └── .gitkeep
├── documents/
│   └── getting-started.md
├── tests/
│   └── test_app.py
├── .env.example
├── .gitignore
├── Dockerfile
├── pytest.ini
├── README.md
└── requirements.txt

15 files written to /home/you/my-rag-app

Next steps:
  cd my-rag-app
  python -m venv .venv
  source .venv/bin/activate
  pip install -r requirements.txt
  cp .env.example .env

list

$ aistrap list
Available templates:

  python-ai     Basic Python AI project (default)
  fastapi       FastAPI AI backend
  rag           Retrieval-Augmented Generation project
  ml-project    Machine learning project
  ai-agent      Autonomous AI Agent with tool calling
  ai-fullstack  Fullstack AI app with FastAPI backend and Web UI
  mcp-server    Model Context Protocol (MCP) AI server
  multimodal    Multimodal AI pipeline for vision, image, and media analysis
  chat-stream   Streaming conversational AI with Server-Sent Events (SSE)
  llm-eval      LLM evaluation and benchmark harness

doctor

Checks for Python, pip, Git and Docker and reports what it finds. Missing optional tools are reported but do not fail the command.

$ aistrap doctor
Environment check:

  OK       Python  Python 3.12.3
  OK       pip     pip 24.0
  OK       Git     git version 2.43.0
  MISSING  Docker  not found on PATH

--version and --help

aistrap --version
aistrap --help
aistrap create --help

Templates

python-ai

A minimal application package with settings, a working entry point, tests and folders for data, notebooks and configuration.

aistrap create my-ai-app
cd my-ai-app && pip install -r requirements.txt
python -m app.main   # prints the most common words in a sample text
pytest

fastapi

A FastAPI service with a /health endpoint, a root metadata endpoint, an application factory, tests using TestClient, and a Dockerfile.

aistrap create my-api --template fastapi
cd my-api && pip install -r requirements.txt
uvicorn app.main:app --reload
curl http://127.0.0.1:8000/health
# {"status":"ok","app":"my-api","version":"0.1.0"}

rag

A complete retrieval pipeline - ingestion, chunking, TF-IDF retrieval and prompt building - written with the standard library only. Drop .md, .txt or .rst files into documents/ and ask questions.

aistrap create my-rag-app --template rag
cd my-rag-app && pip install -r requirements.txt
python -m app.main "What is retrieval-augmented generation?"

ml-project

A scikit-learn workflow that trains a model, reports its accuracy, saves it to models/, and loads it again to make predictions.

aistrap create my-model --template ml-project
cd my-model && pip install -r requirements.txt
python -m app.train                     # Accuracy: 0.933, model saved
python -m app.predict 5.1 3.5 1.4 0.2   # Prediction: setosa (confidence 0.981)

ai-agent

An autonomous ReAct agent with a Think-Act-Observe reasoning loop and an extensible tool registry (calculator, word count, knowledge lookup).

aistrap create my-agent --template ai-agent
cd my-agent && pip install -r requirements.txt
python -m app.main "Calculate 25 * 4 and tell me what is AI"

ai-fullstack

A fullstack application pairing a FastAPI API (/api/generate, /api/health) with a responsive, dark-mode web interface served statically from static/.

aistrap create my-fullstack --template ai-fullstack
cd my-fullstack && pip install -r requirements.txt
uvicorn app.main:app --reload
# Open http://127.0.0.1:8000 in your browser

mcp-server

A Model Context Protocol server exposing tools and system resources over stdio via standard JSON-RPC 2.0.

aistrap create my-mcp --template mcp-server
cd my-mcp && pip install -r requirements.txt
python -m app.main

multimodal

An image inspection and multimodal prompt-building pipeline supporting PNG, JPEG, GIF, and WebP, ready for vision LLMs.

aistrap create my-vision --template multimodal
cd my-vision && pip install -r requirements.txt
python -m app.main

chat-stream

A conversational AI service with real-time token streaming using Server-Sent Events (SSE) and session message memory.

aistrap create my-chat --template chat-stream
cd my-chat && pip install -r requirements.txt
uvicorn app.main:app --reload

llm-eval

An evaluation and benchmark harness calculating exact match, token overlap F1, and response latency against a golden dataset.

aistrap create my-eval --template llm-eval
cd my-eval && pip install -r requirements.txt
python -m app.main

Generated project examples

See examples/ for the exact output of each template, the commands that produced it, and what to run next.

Every generated project follows the same shape:

my-project/
├── app/               # Your code
├── config/            # Configuration files
├── data/              # Datasets, git-ignored by default
├── tests/             # A passing pytest suite
├── .env.example       # Copy to .env and edit
├── .gitignore
├── pytest.ini
├── README.md          # Written for your project by name
└── requirements.txt

Development setup

git clone https://github.com/ramalingamthangamani/Aistrap.git
cd aistrap

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e ".[dev,templates]"

The dev extra installs pytest, ruff and build. The templates extra installs the dependencies of the generated projects (FastAPI, scikit-learn), so the test suite can run every template end to end instead of skipping two of them.

Testing

pytest                     # the whole suite
pytest -k create           # just the create command
pytest --cov=aistrap

The suite covers the CLI (help, version, dispatch), the template registry, project creation for every template, invalid templates and names, existing directories, and the doctor command. It also runs the installed console script in a subprocess and runs each generated project's own test suite, so packaging mistakes and broken templates are caught.

Lint and formatting use ruff:

ruff check .
ruff format --check .

Contributing

Contributions are welcome - especially new templates. See CONTRIBUTING.md for the development workflow and a step-by-step guide to adding a template. If you use an AI coding agent, point it at AGENTS.md.

Roadmap

Ideas for future releases, roughly in order of usefulness:

• More templates: LLM agent, fine-tuning, data pipeline.
• A flag to preview what a template would create before creating it.
• Optional git init and first commit after creating a project.
• Support for user-defined templates in a local directory.
• A --no-input flag for fully scripted use.

Suggestions and pull requests for any of these are welcome.

License

MIT