Skip to content

README.md

Latest commit

 

History

History
175 lines (128 loc) · 7.67 KB

README.md

File metadata and controls

175 lines (128 loc) · 7.67 KB

PyCodeFlow

Turn a plain-language instruction into a ready-to-use source file — generated 100% locally by Ollama. No cloud, no API keys, no data leaves your machine.

Python Ollama Offline License

PyCodeFlow is a tiny single-file CLI. You start it, type an instruction such as "create index.php with header and footer", and it asks a local Ollama model to generate the code, automatically figures out the target filename, strips any markdown code fences, and writes the raw source into the output directory.

Features

  • Interactive prompt loop — start once, then issue as many instructions as you like; type exit to quit.
  • Local LLM generation via Ollama (qwen2.5:7b by default).
  • Bracket tags — pull existing files in as context with [file-in:NAME], read them from a subfolder with [dir-in:NAME], pin the target file with [file-out:NAME], choose an output subfolder with [dir-out:NAME], and switch model per request with [model:NAME].
  • TAB autocompletion — type [ then press TAB to list every tag, or [fi then TAB to complete [file-in: (works in the Windows console via pyreadline3).
  • Built-in help command — lists every available tag and command.
  • Automatic filename detection from the instruction (falls back to output.xxx).
  • Clean output — markdown code fences (```php ... ```) and chatty preambles are stripped, leaving only raw code.
  • Fully offline — talks only to http://localhost:11434; nothing is sent outside your local network.
  • Tag highlighting — bracketed tags are echoed back in color so you can confirm they were parsed.
  • Session logging — every run is appended to pycodeflow.log next to the script.

Requirements

  • Python 3.8+
  • requests library
  • pyreadline3 — Windows only, enables TAB completion (Linux/macOS use the built-in readline)
  • A running Ollama instance with at least one model installed

Setup

# 1. Install the Python dependencies
pip install -r requirements.txt

# 2. Make sure Ollama is installed and running
ollama serve

# 3. Pull a model (default is qwen2.5:7b)
ollama pull qwen2.5:7b

Usage

PyCodeFlow runs as an interactive prompt loop. Start it once:

python gen.py

Then type instructions at the Enter instruction: prompt:

Enter instruction: create index.php with header and footer

What happens for each instruction:

  1. The instruction is sent to the local Ollama server (synchronously).
  2. Markdown code fences and any preamble are stripped from the reply.
  3. The target filename is detected from the instruction (e.g. index.php), falling back to output.xxx if none is found.
  4. The raw code is saved to the configured output directory (output/ by default).
  5. A green confirmation message is printed.
  6. The session is appended to pycodeflow.log.

Type help to see all options, or exit / quit to leave.

Tags

Tags are written inline in your instruction and are parsed before the instruction reaches the model:

Tag Purpose
[file-in:NAME] Load an existing file and pass its contents to the model as input context.
[dir-in:NAME] Read [file-in:] context files from the NAME subfolder of the output dir.
[file-out:NAME] Force the output filename, overriding automatic filename detection.
[dir-out:NAME] Write the result into the NAME subfolder of the output dir (created if missing).
[model:NAME] Use the Ollama model NAME for this request, overriding the default model.

[file-out:...], [dir-in:...], [dir-out:...], and [model:...] are directives and are stripped from the text sent to the model. The final path is always confined to the output directory — a tag that tries to escape it (e.g. ..) is rejected.

Tip: you don't have to type tags in full. Press TAB after [ to list all tags, or type a prefix such as [fi and press TAB to complete it to [file-in: — the same way TAB completion works in the Windows console. On Windows this is provided by pyreadline3 (installed with pip install -r requirements.txt); on Linux/macOS the standard-library readline is used.

Examples

Enter instruction: create hello.py that prints hello world
Enter instruction: create index.html, a simple HTML5 page with a Hello World heading
Enter instruction: [file-in:index.html] generate matching CSS for this page [file-out:style.css]
Enter instruction: [file-in:index.html] add a link to style.css in the head [file-out:index.html]
Enter instruction: [dir-out:mysite] create index.html with a hero section
Enter instruction: [model:codellama] create a quicksort implementation in quicksort.py

Configuration

All settings live in config.py. Edit the values there, or override any of them with the matching environment variable (the environment variable always wins).

Variable in config.py Environment variable Default Description
OLLAMA_URL OLLAMA_URL http://localhost:11434/api/generate Ollama server endpoint used for code generation.
DEFAULT_MODEL OLLAMA_MODEL qwen2.5:7b Ollama model used when generating code.
OUTPUT_DIR PYCODEFLOW_OUTPUT_DIR output Directory where generated files are saved (created if missing).
LOG_FILE PYCODEFLOW_LOG_FILE pycodeflow.log File that every session appends its log to.
REQUEST_TIMEOUT PYCODEFLOW_TIMEOUT 600 Seconds to wait for the Ollama response before giving up.

Relative OUTPUT_DIR and LOG_FILE paths resolve from the project directory. By default generated files are written to the output/ folder, which is excluded from version control via .gitignore.

# Linux / macOS
OLLAMA_MODEL=qwen2.5:7b python gen.py
# Windows PowerShell
$env:OLLAMA_MODEL = "qwen2.5:7b"; python gen.py

Tip: small models (e.g. deepseek-coder:1.3b) are fast but can produce messy code. For better results use a stronger model such as qwen2.5:7b, codellama, or llama3.1:8b.

Project structure

PyCodeFlow/
├── gen.py             # the CLI tool
├── config.py          # configuration variables
├── requirements.txt   # Python dependencies
├── output/            # default output directory (git-ignored)
├── pycodeflow.log     # appended session log (created at runtime)
└── README.md          # this file

Privacy

PyCodeFlow only communicates with http://localhost:11434. Your instructions and the generated code never leave your machine — making it safe for private and air-gapped environments.

License

Released under the MIT License.