release: version 0.9.15 🚀

.gitea/conventional_commits/generate-version.sh

@@ -46,7 +46,7 @@ create_file() {
 }
 
 get_commit_range() {
-    rm $TEMP_FILE_PATH/messages.txt
+    rm -f $TEMP_FILE_PATH/messages.txt
     if [[ $LAST_TAG =~ $PATTERN ]]; then
         create_file true
     else
@@ -86,8 +86,8 @@ start() {
         echo "New version: $new_version"
 
         gitchangelog | grep -v "[rR]elease:" > HISTORY.md
-        echo $new_version > project_name/VERSION
+        echo $new_version > ai_software_factory/VERSION
-        git add project_name/VERSION HISTORY.md
+        git add ai_software_factory/VERSION HISTORY.md
         git commit -m "release: version $new_version 🚀"
         echo "creating git tag : $new_version"
         git tag $new_version

.gitea/rename_project.sh

@@ -1,38 +0,0 @@
-#!/usr/bin/env bash
-while getopts a:n:u:d: flag
-do
-    case "${flag}" in
-        a) author=${OPTARG};;
-        n) name=${OPTARG};;
-        u) urlname=${OPTARG};;
-        d) description=${OPTARG};;
-    esac
-done
-
-echo "Author: $author";
-echo "Project Name: $name";
-echo "Project URL name: $urlname";
-echo "Description: $description";
-
-echo "Renaming project..."
-
-original_author="author_name"
-original_name="project_name"
-original_urlname="project_urlname"
-original_description="project_description"
-# for filename in $(find . -name "*.*") 
-for filename in $(git ls-files) 
-do
-    sed -i "s/$original_author/$author/g" $filename
-    sed -i "s/$original_name/$name/g" $filename
-    sed -i "s/$original_urlname/$urlname/g" $filename
-    sed -i "s/$original_description/$description/g" $filename
-    echo "Renamed $filename"
-done
-
-mv project_name $name
-
-# This command runs only once on GHA!
-rm -rf .gitea/template.yml
-rm -rf project_name
-rm -rf project_name.Tests

.gitea/template.yml

@@ -1 +0,0 @@
-author: rochacbruno

.gitea/workflows/build_release.yml

@@ -4,6 +4,7 @@ permissions:
 
 env:
   SKIP_MAKE_SETUP_CHECK: 'true'
+  DOCKER_API_VERSION: '1.43'
 
 on:
   push:
@@ -41,7 +42,7 @@ jobs:
     - name: Check version match
       run: |
         REPOSITORY_NAME=$(echo "$GITHUB_REPOSITORY" | awk -F '/' '{print $2}' | tr '-' '_')
-        if [ "$(cat project_name/VERSION)" = "${GITHUB_REF_NAME}" ] ; then
+        if [ "$(cat ai_software_factory/VERSION)" = "${GITHUB_REF_NAME}" ] ; then
           echo "Version matches successfully!"
         else
           echo "Version must match!"
@@ -49,13 +50,17 @@ jobs:
         fi
     - name: Login to Gitea container registry
       uses: docker/login-action@v3
+      env:
+        DOCKER_API_VERSION: ${{ env.DOCKER_API_VERSION }}
       with:
         username: gitearobot
         password: ${{ secrets.PACKAGE_GITEA_PAT }}
         registry: git.disi.dev
     - name: Build and publish
+      env:
+        DOCKER_API_VERSION: ${{ env.DOCKER_API_VERSION }}
       run: |
         REPOSITORY_OWNER=$(echo "$GITHUB_REPOSITORY" | awk -F '/' '{print $1}' | tr '[:upper:]' '[:lower:]')
         REPOSITORY_NAME=$(echo "$GITHUB_REPOSITORY" | awk -F '/' '{print $2}' | tr '-' '_')
-        docker build -t "git.disi.dev/$REPOSITORY_OWNER/project_name:$(cat project_name/VERSION)" -f Containerfile ./
+        docker build -t "git.disi.dev/$REPOSITORY_OWNER/ai_software_factory:$(cat ai_software_factory/VERSION)" -f Containerfile ./
-        docker push "git.disi.dev/$REPOSITORY_OWNER/project_name:$(cat project_name/VERSION)"
+        docker push "git.disi.dev/$REPOSITORY_OWNER/ai_software_factory:$(cat ai_software_factory/VERSION)"

.gitea/workflows/rename_project.yml

@@ -1,48 +0,0 @@
-name: Rename the project from template
-
-on: [push]
-
-permissions: write-all
-
-jobs:
-  rename-project:
-    if: ${{ !endsWith (gitea.repository, 'Templates/Docker_Image') }}
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          # by default, it uses a depth of 1
-          # this fetches all history so that we can read each commit
-          fetch-depth: 0
-          ref: ${{ gitea.head_ref }}
-          
-      - run: echo "REPOSITORY_NAME=$(echo "$GITHUB_REPOSITORY" | awk -F '/' '{print $2}' | tr '-' '_')" >> $GITHUB_ENV
-        shell: bash
-
-      - run: echo "REPOSITORY_URLNAME=$(echo "$GITHUB_REPOSITORY" | awk -F '/' '{print $2}')" >> $GITHUB_ENV
-        shell: bash
-
-      - run: echo "REPOSITORY_OWNER=$(echo "$GITHUB_REPOSITORY" | awk -F '/' '{print $1}')" >> $GITHUB_ENV
-        shell: bash
-        
-      - name: Is this still a template
-        id: is_template
-        run: echo "::set-output name=is_template::$(ls .gitea/template.yml &> /dev/null && echo true || echo false)"
-
-      - name: Rename the project
-        if: steps.is_template.outputs.is_template == 'true'
-        run: |
-          echo "Renaming the project with -a(author) ${{ env.REPOSITORY_OWNER }} -n(name) ${{ env.REPOSITORY_NAME }} -u(urlname) ${{ env.REPOSITORY_URLNAME }}"
-          .gitea/rename_project.sh -a ${{ env.REPOSITORY_OWNER }} -n ${{ env.REPOSITORY_NAME }} -u ${{ env.REPOSITORY_URLNAME }} -d "Awesome ${{ env.REPOSITORY_NAME }} created by ${{ env.REPOSITORY_OWNER }}"
-
-      - name: Remove renaming workflow
-        if: steps.is_template.outputs.is_template == 'true'
-        run: |
-          rm .gitea/workflows/rename_project.yml
-          rm .gitea/rename_project.sh
-              
-      - uses: stefanzweifel/git-auto-commit-action@v4
-        with:
-          commit_message: "✅ Ready to clone and code."
-          # commit_options: '--amend --no-edit'
-          push_options: --force

.gitignore

@@ -0,0 +1,2 @@
+sqlite.db
+.nicegui/

CONTRIBUTING.md

@@ -1,15 +1,15 @@
 # How to develop on this project
 
-project_name welcomes contributions from the community.
+ai_software_factory welcomes contributions from the community.
 
 This instructions are for linux base systems. (Linux, MacOS, BSD, etc.)
 
 ## Setting up your own fork of this repo.
 
 - On gitea interface click on `Fork` button.
-- Clone your fork of this repo. `git clone git@git.disi.dev:YOUR_GIT_USERNAME/project_urlname.git`
+- Clone your fork of this repo. `git clone git@git.disi.dev:YOUR_GIT_USERNAME/ai-test.git`
-- Enter the directory `cd project_urlname`
+- Enter the directory `cd ai-test`
-- Add upstream repo `git remote add upstream https://git.disi.dev/author_name/project_urlname`
+- Add upstream repo `git remote add upstream https://git.disi.dev/Projects/ai-test`
 - initialize repository for use `make setup`
 
 ## Install the project in develop mode

Containerfile

@@ -1,6 +1,46 @@
-FROM alpine
+# AI Software Factory Dockerfile
+FROM python:3.11-slim
 
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# Set work directory
 WORKDIR /app
-COPY ./project_name/* /app
 
-CMD ["sh", "/app/hello_world.sh"]
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    git \
+    && update-ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install dependencies
+COPY ./ai_software_factory/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY ./ai_software_factory .
+
+# Set up environment file if it exists, otherwise use .env.example
+# RUN if [ -f .env ]; then \
+#         cat .env; \
+#     elif [ -f .env.example ]; then \
+#         cp .env.example .env; \
+#     fi
+
+# Initialize database tables (use SQLite by default, can be overridden by DB_POOL_SIZE env var)
+# RUN python database.py || true
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run application
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

HISTORY.md

@@ -5,6 +5,486 @@ Changelog
 (unreleased)
 ------------
 
+Fix
+~~~
+- Increase LLM timeouts, refs NOISSUE. [Simon Diesenreiter]
+
+
+0.9.14 (2026-04-11)
+-------------------
+
+Fix
+~~~
+- Add Ollama connection health details in UI, refs NOISSUE. [Simon
+  Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.13 (2026-04-11)
+-------------------
+
+Fix
+~~~
+- Fix internal server error, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.12 (2026-04-11)
+-------------------
+
+Fix
+~~~
+- Remove heuristic decision making fallbacks, refs NOISSUE. [Simon
+  Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.11 (2026-04-11)
+-------------------
+
+Fix
+~~~
+- Project association improvements, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.10 (2026-04-11)
+-------------------
+
+Fix
+~~~
+- More git integration fixes, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.9 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Add missing git binary, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.8 (2026-04-11)
+------------------
+
+Fix
+~~~
+- More file change fixes, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.7 (2026-04-11)
+------------------
+
+Fix
+~~~
+- More file generation improvements, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.6 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Repo onboarding fix, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.5 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Better code generation, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.4 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Add commit retry, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.3 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Better home assistant integration, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.2 (2026-04-11)
+------------------
+
+Fix
+~~~
+- UI improvements and prompt hardening, refs NOISSUE. [Simon
+  Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.1 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Better repo name generation, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.9.0 (2026-04-11)
+------------------
+- Feat: editable guardrails, refs NOISSUE. [Simon Diesenreiter]
+
+
+0.8.0 (2026-04-11)
+------------------
+- Feat: better dashboard reloading mechanism, refs NOISSUE. [Simon
+  Diesenreiter]
+- Feat: add explicit workflow steps and guardrail prompts, refs NOISSUE.
+  [Simon Diesenreiter]
+
+
+0.7.1 (2026-04-11)
+------------------
+
+Fix
+~~~
+- Add additional deletion confirmation, refs NOISSUE. [Simon
+  Diesenreiter]
+
+Other
+~~~~~
+
+
+0.7.0 (2026-04-10)
+------------------
+- Feat: gitea issue integration, refs NOISSUE. [Simon Diesenreiter]
+- Feat: better history data, refs NOISSUE. [Simon Diesenreiter]
+
+
+0.6.5 (2026-04-10)
+------------------
+
+Fix
+~~~
+- Better n8n workflow, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.6.4 (2026-04-10)
+------------------
+
+Fix
+~~~
+- Add Telegram helper functions, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.6.3 (2026-04-10)
+------------------
+
+Fix
+~~~
+- N8n workflow generation, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.6.2 (2026-04-10)
+------------------
+
+Fix
+~~~
+- Fix Quasar layout issues, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.6.1 (2026-04-10)
+------------------
+
+Fix
+~~~
+- Fix commit for version push, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+- Chore: add more health info for n8n, refs NOISSUE. [Simon
+  Diesenreiter]
+
+
+0.6.0 (2026-04-10)
+------------------
+- Feat(api): expose database target in health refs NOISSUE. [Simon
+  Diesenreiter]
+- Fix(db): prefer postgres config in production refs NOISSUE. [Simon
+  Diesenreiter]
+
+
+0.5.0 (2026-04-10)
+------------------
+- Feat(dashboard): expose repository urls refs NOISSUE. [Simon
+  Diesenreiter]
+- Feat(factory): serve dashboard at root and create project repos refs
+  NOISSUE. [Simon Diesenreiter]
+
+
+0.4.1 (2026-04-10)
+------------------
+- Fix(ci): pin docker api version for release builds refs NOISSUE.
+  [Simon Diesenreiter]
+
+
+0.4.0 (2026-04-10)
+------------------
+- Chore(git): ignore local sqlite database refs NOISSUE. [Simon
+  Diesenreiter]
+- Feat(factory): implement db-backed dashboard and workflow automation
+  refs NOISSUE. [Simon Diesenreiter]
+
+
+0.3.6 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Rename gitea workflow, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.5 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Some cleanup, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.4 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Fix database init, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.3 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Fix runtime errors, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.2 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Add back DB init endpoints, ref NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.1 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Fix broken Docker build, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.3.0 (2026-04-04)
+------------------
+- Feat: dashboard via NiceGUI, refs NOISSUE. [Simon Diesenreiter]
+
+
+0.2.2 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Add missing jijna2 reference, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.2.1 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Make dashbaord work, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.2.0 (2026-04-04)
+------------------
+- Feat: Add Python-native dashboard and main.py cleanup, refs NOISSUE.
+  [Simon Diesenreiter]
+
+
+0.1.8 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Broken python module references, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.1.7 (2026-04-04)
+------------------
+
+Fix
+~~~
+- More bugfixes, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.1.6 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Proper containerfile, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+- Chore: update Containerfile to start the app instead of hello world
+  refs NOISSUE. [Simon Diesenreiter]
+
+
+0.1.5 (2026-04-04)
+------------------
+
+Fix
+~~~
+- Bugfix in version generation, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+- Feat(ai-software-factory): add n8n setup agent and enhance
+  orchestration refs NOISSUE. [Simon Diesenreiter]
+
+
+0.1.4 (2026-04-02)
+------------------
+
+Fix
+~~~
+- Fix container build, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.1.3 (2026-04-02)
+------------------
+
+Fix
+~~~
+- Fix version increment logic, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.1.2 (2026-04-02)
+------------------
+
+Fix
+~~~
+- Test version increment logic, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.1.1 (2026-04-01)
+------------------
+
+Fix
+~~~
+- Broken CI build, refs NOISSUE. [Simon Diesenreiter]
+
+Other
+~~~~~
+
+
+0.1.0 (2026-04-01)
+------------------
+- Feat: initial release, refs NOISSUE. [Simon Diesenreiter]
+- ✅ Ready to clone and code. [simon]
+
+
+0.0.1 (2026-03-14)
+------------------
+
 Fix
 ~~~
 - Second initial commit refs NOISSUE. [Simon Diesenreiter]

Makefile

@@ -1,5 +1,7 @@
 .ONESHELL:
 
+DOCKER_API_VERSION ?= 1.43
+
 .PHONY: issetup
 issetup:
 	@[ -f .git/hooks/commit-msg ] || [ -z ${SKIP_MAKE_SETUP_CHECK+x} ] || (echo "You must run 'make setup' first to initialize the repo!" && exit 1)
@@ -17,26 +19,34 @@ help:             ## Show the help.
 
 .PHONY: fmt
 fmt: issetup             ## Format code using black & isort.
-	$(ENV_PREFIX)isort project_name/
+	$(ENV_PREFIX)isort ai-software-factory/
-	$(ENV_PREFIX)black -l 79 project_name/
+	$(ENV_PREFIX)black -l 79 ai-software-factory/
 	$(ENV_PREFIX)black -l 79 tests/
 
+.PHONY: test
+test: issetup           ## Run tests with pytest.
+	$(ENV_PREFIX)pytest ai-software-factory/tests/ -v --tb=short
+
+.PHONY: test-cov
+test-cov: issetup       ## Run tests with coverage report.
+	$(ENV_PREFIX)pytest ai-software-factory/tests/ -v --tb=short --cov=ai-software-factory --cov-report=html --cov-report=term-missing
+
 .PHONY: lint
 lint: issetup            ## Run pep8, black, mypy linters.
-	$(ENV_PREFIX)flake8 project_name/
+	$(ENV_PREFIX)flake8 ai-software-factory/
-	$(ENV_PREFIX)black -l 79 --check project_name/
+	$(ENV_PREFIX)black -l 79 --check ai-software-factory/
 	$(ENV_PREFIX)black -l 79 --check tests/
-	$(ENV_PREFIX)mypy --ignore-missing-imports project_name/
+	$(ENV_PREFIX)mypy --ignore-missing-imports ai-software-factory/
 
 .PHONY: release
 release: issetup         ## Create a new tag for release.
 	@./.gitea/conventional_commits/generate-version.sh
 
 .PHONY: build
-build: issetup         ## Create a new tag for release.
+build: issetup          ## Create a new tag for release.
-	@docker build -t project_name:$(cat project_name/VERSION) -f Containerfile .
+	@DOCKER_API_VERSION=$(DOCKER_API_VERSION) docker build -t ai-software-factory:$(cat ai_software_factory/VERSION) -f Containerfile .
 
 # This project has been generated from rochacbruno/python-project-template
-# __author__ = 'rochacbruno'
+#igest__ = 'rochacbruno'
 # __repo__ = https://github.com/rochacbruno/python-project-template
-# __sponsor__ = https://github.com/sponsors/rochacbruno/
+# __sponsor__ = https://github.com/sponsors/rochacbruno/

README.md

@@ -1,13 +1,250 @@
-# project_name
+# AI Software Factory
 
-Project description goes here.
+Automated software generation service powered by Ollama LLM. This service allows users to specify via Telegram what kind of software they would like, and an agent hosted in Ollama will create it iteratively, testing it while building out the source code and committing to gitea.
 
-## Usage
+## Features
+
+- **Telegram Integration**: Receive software requests via Telegram bot
+- **Ollama LLM**: Uses Ollama-hosted models for code generation
+- **Git Integration**: Creates a dedicated Gitea repository per generated project inside your organization
+- **Pull Requests**: Creates PRs for user review before merging
+- **Web UI**: Beautiful dashboard for monitoring project progress
+- **n8n Workflows**: Bridges Telegram with LLMs via n8n webhooks
+- **Comprehensive Testing**: Full test suite with pytest coverage
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────┐     ┌──────────┐     ┌─────────┐
+│   Telegram  │────▶│   n8n Webhook│────▶│ FastAPI  │────▶│  Ollama │
+└─────────────┘     └──────────────┘     └──────────┘     └─────────┘
+                                                                         │
+                                                                         ▼
+                                                                 ┌──────────────┐
+                                                                 │   Git/Gitea  │
+                                                                 └──────────────┘
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Docker and Docker Compose
+- Ollama running locally or on same network
+- Gitea instance with API token
+- n8n instance for Telegram webhook
+
+### Configuration
+
+Create a `.env` file in the project root:
 
 ```bash
-$ docker build -t <tagname> -f Containerfile .
+# Server
+HOST=0.0.0.0
+PORT=8000
+
+# Ollama
+OLLAMA_URL=http://localhost:11434
+OLLAMA_MODEL=llama3
+
+# Gitea
+# Host-only values such as git.disi.dev are normalized to https://git.disi.dev.
+GITEA_URL=https://gitea.yourserver.com
+GITEA_TOKEN=your_gitea_api_token
+GITEA_OWNER=ai-software-factory
+# Optional legacy fixed-repository mode. Leave empty to create one repo per project.
+GITEA_REPO=
+
+# Database
+# In production, provide PostgreSQL settings. They take precedence over the SQLite default.
+# Setting USE_SQLITE=false is still supported if you want to make the choice explicit.
+POSTGRES_HOST=postgres.yourserver.com
+POSTGRES_PORT=5432
+POSTGRES_USER=ai_software_factory
+POSTGRES_PASSWORD=change-me
+POSTGRES_DB=ai_software_factory
+
+# n8n
+N8N_WEBHOOK_URL=http://n8n.yourserver.com/webhook/telegram
+
+# Telegram
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token
+TELEGRAM_CHAT_ID=your_chat_id
+
+# Optional: Home Assistant integration.
+# Only the base URL and token are required in the environment.
+# Entity ids, thresholds, and queue behavior can be configured from the dashboard System tab and are stored in the database.
+HOME_ASSISTANT_URL=http://homeassistant.local:8123
+HOME_ASSISTANT_TOKEN=your_home_assistant_long_lived_token
 ```
 
+### Build and Run
+
+```bash
+# Build Docker image
+DOCKER_API_VERSION=1.43 docker build -t ai-software-factory -f Containerfile .
+
+# Run with Docker Compose
+docker-compose up -d
+```
+
+### Usage
+
+1. **Send a request via Telegram:**
+
+   ```
+   Build an internal task management app for our operations team.
+   It should support user authentication, task CRUD, notifications, and reporting.
+   Prefer FastAPI with PostgreSQL and a simple web dashboard.
+   ```
+
+   The backend now interprets free-form Telegram text with Ollama before generation.
+   If `TELEGRAM_CHAT_ID` is set, the Telegram-trigger workflow only reacts to messages from that specific chat.
+   If queueing is enabled from the dashboard System tab, Telegram prompts are stored in a durable queue and processed only when the configured Home Assistant battery and surplus thresholds are satisfied, unless you force processing via `/queue/process` or send `process_now=true`.
+
+2. **Monitor progress via Web UI:**
+
+   Open `http://yourserver:8000/` to see the dashboard and `http://yourserver:8000/api` for API metadata
+
+3. **Review PRs in Gitea:**
+
+   Check your gitea repository for generated PRs
+
+If you deploy the container with PostgreSQL environment variables set, the service now selects PostgreSQL automatically even though SQLite remains the default for local/test usage.
+
+The health tab now shows separate application, n8n, Gitea, and Home Assistant/queue diagnostics so misconfigured integrations are visible without checking container logs.
+
+The dashboard Health tab exposes operator controls for the prompt queue, including manual batch processing, forced processing, and retrying failed items.
+
+The dashboard System tab now also stores Home Assistant entity ids, queue toggles, thresholds, and batch settings in the database, so the environment only needs `HOME_ASSISTANT_URL` and `HOME_ASSISTANT_TOKEN` for that integration.
+
+Projects that show `uncommitted`, `local_only`, or `pushed_no_pr` delivery warnings in the dashboard can now be retried in place from the UI before resorting to purging orphan audit rows.
+
+Guardrail and system prompts are no longer environment-only in practice: the factory can persist DB-backed overrides for the editable LLM prompt set, expose them at `/llm/prompts`, and edit them from the dashboard System tab. Environment values still act as defaults and as the reset target.
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|------|------|-------|
+| `/` | GET | Dashboard |
+| `/api` | GET | API information |
+| `/health` | GET | Health check |
+| `/generate` | POST | Generate new software |
+| `/generate/text` | POST | Interpret free-form text and generate software |
+| `/status/{project_id}` | GET | Get project status |
+| `/projects` | GET | List all projects |
+
 ## Development
 
-Read the [CONTRIBUTING.md](CONTRIBUTING.md) file.
+### Makefile Targets
+
+```bash
+make help          # Show available targets
+make setup         # Initialize repository
+make fmt           # Format code
+make lint          # Run linters
+make test          # Run tests
+make test-cov      # Run tests with coverage report
+make release       # Create new release tag
+make build         # Build Docker image
+```
+
+### Running in Development
+
+```bash
+pip install -r requirements.txt
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+make test
+
+# Run tests with coverage report
+make test-cov
+
+# Run specific test file
+pytest tests/test_main.py -v
+
+# Run tests with verbose output
+pytest tests/ -v --tb=short
+```
+
+### Test Coverage
+
+View HTML coverage report:
+
+```bash
+make test-cov
+open htmlcov/index.html
+```
+
+### Test Structure
+
+```
+tests/
+├── conftest.py              # Pytest fixtures and configuration
+├── test_main.py             # Tests for main.py FastAPI app
+├── test_config.py           # Tests for config.py settings
+├── test_git_manager.py      # Tests for git operations
+├── test_ui_manager.py       # Tests for UI rendering
+├── test_gitea.py            # Tests for Gitea API integration
+├── test_telegram.py         # Tests for Telegram integration
+├── test_orchestrator.py     # Tests for agent orchestrator
+├── test_integration.py      # Integration tests for full workflow
+├── test_config_integration.py # Configuration integration tests
+├── test_agents_integration.py # Agent integration tests
+├── test_edge_cases.py       # Edge case tests
+└── test_postgres_integration.py # PostgreSQL integration tests
+```
+
+## Project Structure
+
+```
+ai-software-factory/
+├── main.py                 # FastAPI application
+├── config.py               # Configuration settings
+├── requirements.txt        # Python dependencies
+├── Containerfile           # Docker build file
+├── README.md               # This file
+├── Makefile                # Development utilities
+├── .env.example            # Environment template
+├── .gitignore              # Git ignore rules
+├── HISTORY.md              # Changelog
+├── pytest.ini              # Pytest configuration
+├── docker-compose.yml      # Multi-service orchestration
+├── .env                    # Environment variables (not in git)
+├── tests/                  # Test suite
+│   ├── __init__.py
+│   ├── conftest.py
+│   ├── test_*.py          # Test files
+│   └── pytest.ini
+├── agents/
+│   ├── __init__.py
+│   ├── orchestrator.py     # Main agent orchestrator
+│   ├── git_manager.py      # Git operations
+│   ├── ui_manager.py       # Web UI management
+│   ├── telegram.py         # Telegram integration
+│   └── gitea.py            # Gitea API client
+└── n8n/                    # n8n webhook configurations
+```
+
+## Security Notes
+
+- Never commit `.env` files to git
+- Use environment variables for sensitive data
+- Rotate Gitea API tokens regularly
+- Restrict Telegram bot permissions
+- Use HTTPS for Gitea and n8n endpoints
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

ai_software_factory/.env.example

@@ -0,0 +1,64 @@
+# AI Software Factory Environment Variables
+
+# Server
+HOST=0.0.0.0
+PORT=8000
+LOG_LEVEL=INFO
+
+# Ollama
+OLLAMA_URL=http://localhost:11434
+OLLAMA_MODEL=llama3
+LLM_GUARDRAIL_PROMPT=You are operating inside AI Software Factory. Follow supplied schemas exactly and treat service-provided tool outputs as authoritative.
+LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT=Never route work to archived projects and only reference issues that are explicit in the prompt or supplied tool outputs.
+LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT=Only summarize delivery facts that appear in the provided project context or tool outputs.
+LLM_PROJECT_NAMING_GUARDRAIL_PROMPT=Prefer clear product names and repository slugs that reflect the new request without colliding with tracked projects.
+LLM_PROJECT_NAMING_SYSTEM_PROMPT=Return JSON with project_name, repo_name, and rationale for new projects.
+LLM_PROJECT_ID_GUARDRAIL_PROMPT=Prefer short stable project ids and avoid collisions with existing project ids.
+LLM_PROJECT_ID_SYSTEM_PROMPT=Return JSON with project_id and rationale for new projects.
+LLM_TOOL_ALLOWLIST=gitea_project_catalog,gitea_project_state,gitea_project_issues,gitea_pull_requests
+LLM_TOOL_CONTEXT_LIMIT=5
+LLM_LIVE_TOOL_ALLOWLIST=gitea_lookup_issue,gitea_lookup_pull_request
+LLM_LIVE_TOOL_STAGE_ALLOWLIST=request_interpretation,change_summary
+LLM_LIVE_TOOL_STAGE_TOOL_MAP={"request_interpretation": ["gitea_lookup_issue", "gitea_lookup_pull_request"], "change_summary": []}
+LLM_MAX_TOOL_CALL_ROUNDS=1
+
+# Gitea
+# Configure Gitea API for your organization
+# Host-only values such as git.disi.dev are normalized to https://git.disi.dev automatically.
+GITEA_URL=https://gitea.yourserver.com
+GITEA_TOKEN=your_gitea_api_token
+GITEA_OWNER=your_organization_name
+GITEA_REPO= (optional legacy fixed repository mode; leave empty to create one repo per project)
+
+# n8n
+# n8n webhook for Telegram integration
+N8N_WEBHOOK_URL=http://n8n.yourserver.com/webhook/telegram
+# n8n API for automatic webhook configuration
+N8N_API_URL=http://n8n.yourserver.com
+N8N_USER=n8n_admin
+N8N_PASSWORD=your_secure_password
+
+# Telegram
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token
+TELEGRAM_CHAT_ID=your_chat_id
+
+# Home Assistant energy gate for queued Telegram prompts
+# Only the base URL and token are environment-backed.
+# Queue toggles, entity ids, thresholds, and batch sizing can be edited in the dashboard System tab and are stored in the database.
+HOME_ASSISTANT_URL=http://homeassistant.local:8123
+HOME_ASSISTANT_TOKEN=your_home_assistant_long_lived_token
+
+# PostgreSQL
+# In production, provide PostgreSQL settings below. They now take precedence over the SQLite default.
+# You can also set USE_SQLITE=false explicitly if you want the intent to be obvious.
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+POSTGRES_USER=ai_test
+POSTGRES_PASSWORD=your_secure_password
+POSTGRES_DB=ai_test
+
+# Database Connection Pool Settings
+DB_POOL_SIZE=10
+DB_MAX_OVERFLOW=20
+DB_POOL_RECYCLE=3600
+DB_POOL_TIMEOUT=30

ai_software_factory/.gitignore soft

@@ -0,0 +1,88 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Project specific
+.git/
+.gitignore
+.env
+.env.local
+.env.*.local
+ai-software-factory/
+n8n/
+ui/
+docs/
+tests/
+
+# Temporary files
+*.tmp
+*.temp
+*.log

ai_software_factory/.nicegui/storage-user-7d0ab1e4-7155-403b-846e-26833486feae.json

@@ -0,0 +1 @@
+{"dark_mode":false}

ai_software_factory/.nicegui/storage-user-83c198f2-6838-4d94-a576-9934514d723b.json

@@ -0,0 +1 @@
+{"dark_mode":false}

ai_software_factory/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to AI Software Factory
+
+Thank you for your interest in contributing to the AI Software Factory project!
+
+## Code of Conduct
+
+Please note that we have a Code of Conduct that all contributors are expected to follow.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues as the bug may have already been reported and fixed.
+
+When reporting a bug, include:
+
+- A clear description of the bug
+- Steps to reproduce the bug
+- Expected behavior
+- Actual behavior
+- Screenshots if applicable
+- Your environment details (OS, Python version, etc.)
+
+### Suggesting Features
+
+Feature suggestions are welcome! Please create an issue with:
+
+- A clear title and description
+- Use cases for the feature
+- Any relevant links or references
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a new branch (`git checkout -b feature/feature-name`)
+3. Make your changes
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin feature/feature-name`)
+6. Create a new Pull Request
+
+### Style Guide
+
+- Follow the existing code style
+- Add comments for complex logic
+- Write tests for new features
+- Update documentation as needed
+
+## Development Setup
+
+1. Clone the repository
+2. Create a virtual environment
+3. Install dependencies (`pip install -r requirements.txt`)
+4. Run tests (`make test`)
+5. Make your changes
+6. Run tests again to ensure nothing is broken
+
+## Commit Messages
+
+Follow the conventional commits format:
+
+```
+feat: add new feature
+fix: fix bug
+docs: update documentation
+style: format code
+refactor: refactor code
+test: add tests
+chore: update dependencies
+```
+
+## Questions?
+
+Feel free to open an issue or discussion for any questions.

ai_software_factory/HISTORY.md

@@ -0,0 +1,41 @@
+Changelog
+=========
+
+## [0.0.1] - 2026-03-14
+
+### Added
+- Initial commit with AI Software Factory service
+- FastAPI backend for software generation
+- Telegram integration via n8n webhook
+- Ollama LLM integration for code generation
+- Gitea API integration for commits and PRs
+- Web UI dashboard for monitoring progress
+- Docker and docker-compose configuration for Unraid
+- Environment configuration templates
+- Makefile with development utilities
+- PostgreSQL integration with connection pooling
+- Comprehensive audit trail functionality
+- User action tracking
+- System log monitoring
+- Database initialization and migration support
+- Full test suite with pytest coverage
+
+### Features
+- Automated software generation from Telegram requests
+- Iterative code generation with Ollama
+- Git commit automation
+- Pull request creation for user review
+- Real-time progress monitoring via web UI
+- n8n workflow integration
+- Complete audit trail for compliance and debugging
+- Connection pooling for database efficiency
+- Health check endpoints
+- Persistent volumes for git repos and n8n data
+
+### Infrastructure
+- Alpine-based Docker image
+- GPU support for Ollama
+- Persistent volumes for git repos and n8n data
+- Health check endpoints
+- PostgreSQL with connection pooling
+- Docker Compose for multi-service orchestration

ai_software_factory/Makefile

@@ -0,0 +1,28 @@
+.PHONY: help run-api run-frontend run-tests init-db clean
+
+help:
+	@echo "Available targets:"
+	@echo "  make run-api          - Run FastAPI app with NiceGUI frontend (default)"
+	@echo "  make run-tests        - Run pytest tests"
+	@echo "  make init-db          - Initialize database"
+	@echo "  make clean            - Remove container volumes"
+	@echo "  make rebuild          - Rebuild and run container"
+
+run-api:
+	@echo "Starting FastAPI app with NiceGUI frontend..."
+	@bash start.sh dev
+
+run-frontend:
+	@echo "NiceGUI is now integrated with FastAPI - use 'make run-api' to start everything together"
+
+run-tests:
+	pytest -v
+
+init-db:
+	@python -c "from main import app; from database import init_db; init_db()"
+
+clean:
+	@echo "Cleaning up..."
+	@docker-compose down -v
+
+rebuild: clean run-api

ai_software_factory/README.md

@@ -0,0 +1,273 @@
+# AI Software Factory
+
+Automated software generation service powered by Ollama LLM. This service allows users to specify via Telegram what kind of software they would like, and an agent hosted in Ollama will create it iteratively, testing it while building out the source code and committing to gitea.
+
+## Features
+
+- **Telegram Integration**: Receive software requests via Telegram bot
+- **Ollama LLM**: Uses Ollama-hosted models for code generation
+- **LLM Guardrails and Tools**: Centralized guardrail prompts plus mediated tool payloads for project, Gitea, PR, and issue context
+- **Git Integration**: Automatically commits code to gitea
+- **Pull Requests**: Creates PRs for user review before merging
+- **Web UI**: Beautiful dashboard for monitoring project progress
+- **n8n Workflows**: Bridges Telegram with LLMs via n8n webhooks
+- **Comprehensive Testing**: Full test suite with pytest coverage
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────┐     ┌──────────┐     ┌─────────┐
+│   Telegram  │────▶│   n8n Webhook│────▶│ FastAPI  │────▶│  Ollama │
+└─────────────┘     └──────────────┘     └──────────┘     └─────────┘
+                                                                         │
+                                                                         ▼
+                                                                 ┌──────────────┐
+                                                                 │   Git/Gitea  │
+                                                                 └──────────────┘
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Docker and Docker Compose
+- Ollama running locally or on same network
+- Gitea instance with API token
+- n8n instance for Telegram webhook
+
+### Configuration
+
+Create a `.env` file in the project root:
+
+```bash
+# Server
+HOST=0.0.0.0
+PORT=8000
+
+# Ollama
+OLLAMA_URL=http://localhost:11434
+OLLAMA_MODEL=llama3
+LLM_GUARDRAIL_PROMPT=You are operating inside AI Software Factory. Follow supplied schemas exactly and treat service-provided tool outputs as authoritative.
+LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT=Never route work to archived projects and only reference issues that are explicit in the prompt or supplied tool outputs.
+LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT=Only summarize delivery facts that appear in the provided project context or tool outputs.
+LLM_PROJECT_NAMING_GUARDRAIL_PROMPT=Prefer clear product names and repository slugs that reflect the new request without colliding with tracked projects.
+LLM_PROJECT_NAMING_SYSTEM_PROMPT=Return JSON with project_name, repo_name, and rationale for new projects.
+LLM_PROJECT_ID_GUARDRAIL_PROMPT=Prefer short stable project ids and avoid collisions with existing project ids.
+LLM_PROJECT_ID_SYSTEM_PROMPT=Return JSON with project_id and rationale for new projects.
+LLM_TOOL_ALLOWLIST=gitea_project_catalog,gitea_project_state,gitea_project_issues,gitea_pull_requests
+LLM_TOOL_CONTEXT_LIMIT=5
+LLM_LIVE_TOOL_ALLOWLIST=gitea_lookup_issue,gitea_lookup_pull_request
+LLM_LIVE_TOOL_STAGE_ALLOWLIST=request_interpretation,change_summary
+LLM_LIVE_TOOL_STAGE_TOOL_MAP={"request_interpretation": ["gitea_lookup_issue", "gitea_lookup_pull_request"], "change_summary": []}
+LLM_MAX_TOOL_CALL_ROUNDS=1
+
+# Gitea
+# Host-only values such as git.disi.dev are normalized to https://git.disi.dev.
+GITEA_URL=https://gitea.yourserver.com
+GITEA_TOKEN=your_gitea_api_token
+GITEA_OWNER=ai-software-factory
+GITEA_REPO=
+
+# n8n
+N8N_WEBHOOK_URL=http://n8n.yourserver.com/webhook/telegram
+
+# Telegram
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token
+TELEGRAM_CHAT_ID=your_chat_id
+
+# Optional: Home Assistant integration.
+# Only the base URL and token are required in the environment.
+# Entity ids, thresholds, and queue behavior can be configured from the dashboard System tab and are stored in the database.
+HOME_ASSISTANT_URL=http://homeassistant.local:8123
+HOME_ASSISTANT_TOKEN=your_home_assistant_long_lived_token
+```
+
+### Build and Run
+
+```bash
+# Build Docker image
+docker build -t ai-software-factory -f Containerfile .
+
+# Run with Docker Compose
+docker-compose up -d
+```
+
+### Usage
+
+1. **Send a request via Telegram:**
+
+   ```
+   Name: My Awesome App
+   Description: A web application for managing tasks
+   Features: user authentication, task CRUD, notifications
+   ```
+
+   If queueing is enabled from the dashboard System tab, Telegram prompts are queued durably and processed only when Home Assistant reports the configured battery and surplus thresholds. Operators can override the gate via `/queue/process` or by sending `process_now=true` to `/generate/text`.
+
+The dashboard System tab stores Home Assistant entity ids, queue toggles, thresholds, and batch settings in the database, so the environment only needs `HOME_ASSISTANT_URL` and `HOME_ASSISTANT_TOKEN` for that integration.
+
+2. **Monitor progress via Web UI:**
+
+   Open `http://yourserver:8000` to see real-time progress
+
+3. **Review PRs in Gitea:**
+
+   Check your gitea repository for generated PRs
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|------|------|-------|
+| `/` | GET | API information |
+| `/health` | GET | Health check |
+| `/generate` | POST | Generate new software |
+| `/status/{project_id}` | GET | Get project status |
+| `/projects` | GET | List all projects |
+
+## LLM Guardrails and Tool Access
+
+External LLM calls are now routed through a centralized client that applies:
+
+- A global guardrail prompt for every outbound model request
+- Stage-specific guardrails for request interpretation and change summaries
+- Service-mediated tool outputs that expose tracked Gitea/project state without giving the model raw credentials
+
+Current mediated tools include:
+
+- `gitea_project_catalog`: active tracked projects and repository mappings
+- `gitea_project_state`: current repository, PR, and linked-issue state for the project in scope
+- `gitea_project_issues`: tracked open issues for the relevant repository
+- `gitea_pull_requests`: tracked pull requests for the relevant repository
+
+The service also supports a bounded live tool-call loop for selected lookups. When enabled, the model may request one live call such as `gitea_lookup_issue` or `gitea_lookup_pull_request`, the service executes it against Gitea, and the final model response is generated from the returned result. This remains mediated by the service, so the model never receives raw credentials.
+
+Live tool access is stage-aware. `LLM_LIVE_TOOL_ALLOWLIST` controls which live tools exist globally, while `LLM_LIVE_TOOL_STAGE_ALLOWLIST` controls which LLM stages may use them. If you need per-stage subsets, `LLM_LIVE_TOOL_STAGE_TOOL_MAP` accepts a JSON object mapping each stage to the exact tools it may use. For example, you can allow issue and PR lookups during `request_interpretation` while keeping `change_summary` fully read-only.
+
+When the interpreter decides a prompt starts a new project, the service can run a dedicated `project_naming` LLM stage before generation. `LLM_PROJECT_NAMING_SYSTEM_PROMPT` and `LLM_PROJECT_NAMING_GUARDRAIL_PROMPT` let you steer how project titles and repository slugs are chosen. The interpreter now checks tracked project repositories plus live Gitea repository names when available, so if the model suggests a colliding repo slug the service will automatically move to the next available slug.
+
+New project creation can also run a dedicated `project_id_naming` stage. `LLM_PROJECT_ID_SYSTEM_PROMPT` and `LLM_PROJECT_ID_GUARDRAIL_PROMPT` control how stable project ids are chosen, and the service will append deterministic numeric suffixes when an id is already taken instead of always falling back to a random UUID-based id.
+
+Runtime visibility for the active guardrails, mediated tools, live tools, and model configuration is available at `/llm/runtime` and in the dashboard System tab.
+
+Operational visibility for the Gitea integration, Home Assistant energy gate, and queued prompt counts is available in the dashboard Health tab, plus `/gitea/health`, `/home-assistant/health`, and `/queue`.
+
+The dashboard Health tab also includes operator controls for manually processing queued Telegram prompts, force-processing them when needed, and retrying failed items.
+
+Editable guardrail and system prompts are persisted in the database as overrides on top of the environment defaults. The current merged values are available at `/llm/prompts`, and the dashboard System tab can edit or reset them without restarting the service.
+
+These tool payloads are appended to the model prompt as authoritative JSON generated by the service, so the LLM can reason over live project and Gitea context while remaining constrained by the configured guardrails.
+
+## Development
+
+### Makefile Targets
+
+```bash
+make help          # Show available targets
+make setup         # Initialize repository
+make fmt           # Format code
+make lint          # Run linters
+make test          # Run tests
+make test-cov      # Run tests with coverage report
+make release       # Create new release tag
+make build         # Build Docker image
+```
+
+### Running in Development
+
+```bash
+pip install -r requirements.txt
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+make test
+
+# Run tests with coverage report
+make test-cov
+
+# Run specific test file
+pytest tests/test_main.py -v
+
+# Run tests with verbose output
+pytest tests/ -v --tb=short
+```
+
+### Test Coverage
+
+View HTML coverage report:
+
+```bash
+make test-cov
+open htmlcov/index.html
+```
+
+### Test Structure
+
+```
+tests/
+├── conftest.py              # Pytest fixtures and configuration
+├── test_main.py             # Tests for main.py FastAPI app
+├── test_config.py           # Tests for config.py settings
+├── test_git_manager.py      # Tests for git operations
+├── test_ui_manager.py       # Tests for UI rendering
+├── test_gitea.py            # Tests for Gitea API integration
+├── test_telegram.py         # Tests for Telegram integration
+├── test_orchestrator.py     # Tests for agent orchestrator
+├── test_integration.py      # Integration tests for full workflow
+├── test_config_integration.py # Configuration integration tests
+├── test_agents_integration.py # Agent integration tests
+├── test_edge_cases.py       # Edge case tests
+└── test_postgres_integration.py # PostgreSQL integration tests
+```
+
+## Project Structure
+
+```
+ai-software-factory/
+├── main.py                 # FastAPI application
+├── config.py               # Configuration settings
+├── requirements.txt        # Python dependencies
+├── Containerfile           # Docker build file
+├── README.md               # This file
+├── Makefile                # Development utilities
+├── .env.example            # Environment template
+├── .gitignore              # Git ignore rules
+├── HISTORY.md              # Changelog
+├── pytest.ini              # Pytest configuration
+├── docker-compose.yml      # Multi-service orchestration
+├── .env                    # Environment variables (not in git)
+├── tests/                  # Test suite
+│   ├── __init__.py
+│   ├── conftest.py
+│   ├── test_*.py          # Test files
+│   └── pytest.ini
+├── agents/
+│   ├── __init__.py
+│   ├── orchestrator.py     # Main agent orchestrator
+│   ├── git_manager.py      # Git operations
+│   ├── ui_manager.py       # Web UI management
+│   ├── telegram.py         # Telegram integration
+│   └── gitea.py            # Gitea API client
+└── n8n/                    # n8n webhook configurations
+```
+
+## Security Notes
+
+- Never commit `.env` files to git
+- Use environment variables for sensitive data
+- Rotate Gitea API tokens regularly
+- Restrict Telegram bot permissions
+- Use HTTPS for Gitea and n8n endpoints
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

ai_software_factory/VERSION

@@ -0,0 +1 @@
+0.9.15

ai_software_factory/__init__.py

@@ -0,0 +1,3 @@
+"""AI Software Factory - Automated software generation service."""
+
+__version__ = "0.0.1"

ai_software_factory/agents/__init__.py

@@ -0,0 +1,17 @@
+"""AI Software Factory agents."""
+
+from .orchestrator import AgentOrchestrator
+from .git_manager import GitManager
+from .ui_manager import UIManager
+from .telegram import TelegramHandler
+from .gitea import GiteaAPI
+from .database_manager import DatabaseManager
+
+__all__ = [
+    "AgentOrchestrator",
+    "GitManager",
+    "UIManager",
+    "TelegramHandler",
+    "GiteaAPI",
+    "DatabaseManager"
+]

ai_software_factory/agents/change_summary.py

@@ -0,0 +1,125 @@
+"""Generate concise chat-friendly summaries of software generation results."""
+
+from __future__ import annotations
+
+try:
+    from ..config import settings
+    from .llm_service import LLMServiceClient
+except ImportError:
+    from config import settings
+    from agents.llm_service import LLMServiceClient
+
+
+class ChangeSummaryGenerator:
+    """Create a readable overview of generated changes for chat responses."""
+
+    def __init__(self, ollama_url: str | None = None, model: str | None = None):
+        self.ollama_url = (ollama_url or settings.ollama_url).rstrip('/')
+        self.model = model or settings.OLLAMA_MODEL
+        self.llm_client = LLMServiceClient(ollama_url=self.ollama_url, model=self.model)
+
+    async def summarize(self, context: dict) -> str:
+        """Summarize project changes with Ollama, or fall back to a deterministic overview."""
+        summary, _trace = await self.summarize_with_trace(context)
+        return summary
+
+    async def summarize_with_trace(self, context: dict) -> tuple[str, dict]:
+        """Summarize project changes with Ollama, or fall back to a deterministic overview."""
+        prompt = self._prompt(context)
+        system_prompt = (
+            'You write concise but informative mobile chat summaries of software delivery work. '
+            'Write 3 to 5 sentences. Mention the application goal, main delivered pieces, '
+            'technical direction, and what the user should expect next. Avoid markdown bullets.'
+        )
+        content, trace = await self.llm_client.chat_with_trace(
+            stage='change_summary',
+            system_prompt=system_prompt,
+            user_prompt=prompt,
+            tool_context_input={
+                'project_id': context.get('project_id'),
+                'project_name': context.get('name'),
+                'repository': context.get('repository'),
+                'repository_url': context.get('repository_url'),
+                'pull_request': context.get('pull_request'),
+                'pull_request_url': context.get('pull_request_url'),
+                'pull_request_state': context.get('pull_request_state'),
+                'related_issue': context.get('related_issue'),
+                'issues': [context.get('related_issue')] if context.get('related_issue') else [],
+            },
+        )
+        if content:
+            return content.strip(), trace
+
+        fallback = self._fallback(context)
+        return fallback, {
+            'stage': 'change_summary',
+            'provider': 'fallback',
+            'model': self.model,
+            'system_prompt': system_prompt,
+            'user_prompt': prompt,
+            'assistant_response': fallback,
+            'raw_response': {'fallback': 'deterministic', 'llm_trace': trace.get('raw_response') if isinstance(trace, dict) else None},
+            'guardrails': trace.get('guardrails') if isinstance(trace, dict) else [],
+            'tool_context': trace.get('tool_context') if isinstance(trace, dict) else [],
+            'fallback_used': True,
+        }
+
+    def _prompt(self, context: dict) -> str:
+        features = ', '.join(context.get('features') or []) or 'No explicit features recorded'
+        tech_stack = ', '.join(context.get('tech_stack') or []) or 'No explicit tech stack recorded'
+        changed_files = ', '.join(context.get('changed_files') or []) or 'No files recorded'
+        logs = ' | '.join((context.get('logs') or [])[:4]) or 'No log excerpts'
+        return (
+            f"Project name: {context.get('name', 'Unknown project')}\n"
+            f"Description: {context.get('description', '')}\n"
+            f"Features: {features}\n"
+            f"Tech stack: {tech_stack}\n"
+            f"Changed files: {changed_files}\n"
+            f"Repository: {context.get('repository_url') or 'No repository URL'}\n"
+            f"Pull request: {context.get('pull_request_url') or 'No pull request URL'}\n"
+            f"Pull request state: {context.get('pull_request_state') or 'No pull request state'}\n"
+            f"Status message: {context.get('message') or ''}\n"
+            f"Log excerpts: {logs}\n"
+            "Write a broad but phone-friendly summary of what was done."
+        )
+
+    def _fallback(self, context: dict) -> str:
+        name = context.get('name', 'The project')
+        description = context.get('description') or 'a software request'
+        changed_files = context.get('changed_files') or []
+        features = context.get('features') or []
+        tech_stack = context.get('tech_stack') or []
+        repo_url = context.get('repository_url')
+        repo_status = context.get('repository_status')
+        pr_url = context.get('pull_request_url')
+        pr_state = context.get('pull_request_state')
+
+        first_sentence = f"{name} was generated from your request for {description}."
+        feature_sentence = (
+            f"The delivery focused on {', '.join(features[:3])}."
+            if features else
+            "The delivery focused on turning the request into an initial runnable application skeleton."
+        )
+        tech_sentence = (
+            f"The generated implementation currently targets {', '.join(tech_stack[:3])}."
+            if tech_stack else
+            "The implementation was created with the current default stack configured for the factory."
+        )
+        file_sentence = (
+            f"Key artifacts were updated across {len(changed_files)} files, including {', '.join(changed_files[:3])}."
+            if changed_files else
+            "The service completed the generation flow, but no changed file list was returned."
+        )
+        if repo_url:
+            repo_sentence = f"The resulting project is tracked at {repo_url}."
+        elif repo_status in {'pending', 'skipped', 'error'}:
+            repo_sentence = "Repository provisioning was not confirmed, so review the Gitea status in the dashboard before assuming a remote repo exists."
+        else:
+            repo_sentence = "The project is ready for further review in the dashboard."
+        if pr_url and pr_state == 'open':
+            pr_sentence = f"An open pull request is ready for review at {pr_url}, and later prompts will continue updating that same PR until it is merged."
+        elif pr_url:
+            pr_sentence = f"The latest pull request is available at {pr_url}."
+        else:
+            pr_sentence = "No pull request link was recorded for this delivery."
+        return ' '.join([first_sentence, feature_sentence, tech_sentence, file_sentence, repo_sentence, pr_sentence])

ai_software_factory/agents/git_manager.py

@@ -0,0 +1,190 @@
+"""Git manager for project operations."""
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+try:
+    from ..config import settings
+except ImportError:
+    from config import settings
+
+
+class GitManager:
+    """Manages git operations for the project."""
+    
+    def __init__(self, project_id: str, project_dir: str | None = None):
+        if not project_id:
+            raise ValueError("project_id cannot be empty or None")
+        self.project_id = project_id
+        if project_dir:
+            resolved = Path(project_dir).expanduser().resolve()
+        else:
+            project_path = Path(project_id)
+            if project_path.is_absolute() or len(project_path.parts) > 1:
+                resolved = project_path.expanduser().resolve()
+            else:
+                base_root = settings.projects_root
+                if base_root.name != "test-project":
+                    base_root = base_root / "test-project"
+                resolved = (base_root / project_id).resolve()
+        self.project_dir = str(resolved)
+
+    def is_git_available(self) -> bool:
+        """Return whether the git executable is available in the current environment."""
+        return shutil.which('git') is not None
+
+    def _ensure_git_available(self) -> None:
+        """Raise a clear error when git is not installed in the runtime environment."""
+        if not self.is_git_available():
+            raise RuntimeError('git executable is not available in PATH')
+
+    def _run(self, args: list[str], env: dict | None = None, check: bool = True) -> subprocess.CompletedProcess:
+        """Run a git command in the project directory."""
+        self._ensure_git_available()
+        return subprocess.run(
+            args,
+            check=check,
+            capture_output=True,
+            text=True,
+            cwd=self.project_dir,
+            env=env,
+        )
+
+    def has_repo(self) -> bool:
+        """Return whether the project directory already contains a git repository."""
+        return Path(self.project_dir, '.git').exists()
+    
+    def init_repo(self):
+        """Initialize git repository."""
+        os.makedirs(self.project_dir, exist_ok=True)
+        self._run(["git", "init", "-b", "main"])
+        self._run(["git", "config", "user.name", "AI Software Factory"])
+        self._run(["git", "config", "user.email", "factory@local.invalid"])
+    
+    def add_files(self, paths: list[str]):
+        """Add files to git staging."""
+        self._run(["git", "add"] + paths)
+
+    def checkout_branch(self, branch_name: str, create: bool = False, start_point: str | None = None) -> None:
+        """Switch to a branch, optionally creating it from a start point."""
+        if create:
+            args = ["git", "checkout", "-B", branch_name]
+            if start_point:
+                args.append(start_point)
+            self._run(args)
+            return
+        self._run(["git", "checkout", branch_name])
+
+    def branch_exists(self, branch_name: str) -> bool:
+        """Return whether a local branch exists."""
+        result = self._run(["git", "show-ref", "--verify", f"refs/heads/{branch_name}"], check=False)
+        return result.returncode == 0
+    
+    def commit(self, message: str) -> str:
+        """Create a git commit."""
+        self._run(["git", "commit", "-m", message])
+        return self.current_head()
+
+    def create_empty_commit(self, message: str) -> str:
+        """Create an empty commit."""
+        self._run(["git", "commit", "--allow-empty", "-m", message])
+        return self.current_head()
+    
+    def push(self, remote: str = "origin", branch: str = "main"):
+        """Push changes to remote."""
+        self._run(["git", "push", "-u", remote, branch])
+
+    def ensure_remote(self, remote: str, url: str) -> None:
+        """Create or update a remote URL."""
+        result = self._run(["git", "remote", "get-url", remote], check=False)
+        if result.returncode == 0:
+            self._run(["git", "remote", "set-url", remote, url])
+        else:
+            self._run(["git", "remote", "add", remote, url])
+
+    def push_with_credentials(
+        self,
+        remote_url: str,
+        username: str,
+        password: str,
+        remote: str = "origin",
+        branch: str = "main",
+    ) -> None:
+        """Push to a remote over HTTPS using an askpass helper."""
+        os.makedirs(self.project_dir, exist_ok=True)
+        self.ensure_remote(remote, remote_url)
+        helper_contents = "#!/bin/sh\ncase \"$1\" in\n  *Username*) printf '%s\\n' \"$GIT_ASKPASS_USERNAME\" ;;\n  *) printf '%s\\n' \"$GIT_ASKPASS_PASSWORD\" ;;\nesac\n"
+        helper_path: str | None = None
+        try:
+            with tempfile.NamedTemporaryFile('w', delete=False, dir=self.project_dir, prefix='git-askpass-', suffix='.sh') as helper_file:
+                helper_file.write(helper_contents)
+                helper_path = helper_file.name
+            os.chmod(helper_path, 0o700)
+            env = os.environ.copy()
+            env.update(
+                {
+                    "GIT_TERMINAL_PROMPT": "0",
+                    "GIT_ASKPASS": helper_path,
+                    "GIT_ASKPASS_USERNAME": username,
+                    "GIT_ASKPASS_PASSWORD": password,
+                }
+            )
+            self._run(["git", "push", "-u", remote, branch], env=env)
+        finally:
+            if helper_path:
+                Path(helper_path).unlink(missing_ok=True)
+    
+    def create_branch(self, branch_name: str):
+        """Create and switch to a new branch."""
+        self._run(["git", "checkout", "-b", branch_name])
+
+    def revert_commit(self, commit_hash: str, no_edit: bool = True) -> str:
+        """Revert a commit and return the new HEAD."""
+        args = ["git", "revert"]
+        if no_edit:
+            args.append("--no-edit")
+        args.append(commit_hash)
+        self._run(args)
+        return self.current_head()
+    
+    def create_pr(
+        self,
+        title: str,
+        body: str,
+        base: str = "main",
+        head: Optional[str] = None
+    ) -> dict:
+        """Create a pull request via gitea API."""
+        # This would integrate with gitea API
+        # For now, return placeholder
+        return {
+            "title": title,
+            "body": body,
+            "base": base,
+            "head": head or f"ai-gen-{self.project_id}"
+        }
+    
+    def get_status(self) -> str:
+        """Get git status."""
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            cwd=self.project_dir,
+        )
+        return result.stdout.strip()
+
+    def current_head(self) -> str:
+        """Return the current commit hash."""
+        return self._run(["git", "rev-parse", "HEAD"]).stdout.strip()
+
+    def current_head_or_none(self) -> str | None:
+        """Return the current commit hash when the repository already has commits."""
+        result = self._run(["git", "rev-parse", "HEAD"], check=False)
+        if result.returncode != 0:
+            return None
+        return result.stdout.strip() or None

ai_software_factory/agents/gitea.py

@@ -0,0 +1,448 @@
+"""Gitea API integration for repository and pull request operations."""
+
+import os
+import urllib.error
+import urllib.request
+import json
+from urllib.parse import urlparse
+
+
+def _normalize_base_url(base_url: str) -> str:
+    """Normalize host-only service addresses into valid absolute URLs."""
+    normalized = (base_url or '').strip().rstrip('/')
+    if not normalized:
+        return ''
+    if '://' not in normalized:
+        normalized = f'https://{normalized}'
+    parsed = urlparse(normalized)
+    if not parsed.scheme or not parsed.netloc:
+        return ''
+    return normalized
+
+
+class GiteaAPI:
+    """Gitea API client for repository operations."""
+
+    def __init__(self, token: str, base_url: str, owner: str | None = None, repo: str | None = None):
+        self.token = token
+        self.base_url = _normalize_base_url(base_url)
+        self.owner = owner
+        self.repo = repo
+        self.headers = {
+            "Authorization": f"token {token}",
+            "Content-Type": "application/json",
+        }
+
+    def get_config(self) -> dict:
+        """Load configuration from environment."""
+        base_url = os.getenv("GITEA_URL", "https://gitea.local")
+        token = os.getenv("GITEA_TOKEN", "")
+        owner = os.getenv("GITEA_OWNER", "ai-test")
+        repo = os.getenv("GITEA_REPO", "")
+        return {
+            "base_url": _normalize_base_url(base_url),
+            "token": token,
+            "owner": owner,
+            "repo": repo,
+            "supports_project_repos": not bool(repo),
+        }
+
+    def get_auth_headers(self) -> dict:
+        """Get authentication headers."""
+        return {
+            "Authorization": f"token {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    def _api_url(self, path: str) -> str:
+        """Build a Gitea API URL from a relative path."""
+        return f"{self.base_url}/api/v1/{path.lstrip('/')}"
+
+    def _normalize_pull_request_head(self, head: str | None, owner: str | None = None) -> str | None:
+        """Return a Gitea-compatible head ref for pull request creation."""
+        normalized = (head or '').strip()
+        if not normalized:
+            return None
+        if ':' in normalized:
+            return normalized
+        effective_owner = (owner or self.owner or '').strip()
+        if not effective_owner:
+            return normalized
+        return f"{effective_owner}:{normalized}"
+
+    def build_repo_git_url(self, owner: str | None = None, repo: str | None = None) -> str | None:
+        """Build the clone URL for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo:
+            return None
+        return f"{self.base_url}/{_owner}/{_repo}.git"
+
+    def build_commit_url(self, commit_hash: str, owner: str | None = None, repo: str | None = None) -> str | None:
+        """Build a browser URL for a commit."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo or not commit_hash:
+            return None
+        return f"{self.base_url}/{_owner}/{_repo}/commit/{commit_hash}"
+
+    def build_compare_url(self, base_ref: str, head_ref: str, owner: str | None = None, repo: str | None = None) -> str | None:
+        """Build a browser URL for a compare view."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo or not base_ref or not head_ref:
+            return None
+        return f"{self.base_url}/{_owner}/{_repo}/compare/{base_ref}...{head_ref}"
+
+    def build_pull_request_url(self, pr_number: int, owner: str | None = None, repo: str | None = None) -> str | None:
+        """Build a browser URL for a pull request."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo or not pr_number:
+            return None
+        return f"{self.base_url}/{_owner}/{_repo}/pulls/{pr_number}"
+
+    async def _request(self, method: str, path: str, payload: dict | None = None) -> dict:
+        """Perform a Gitea API request and normalize the response."""
+        try:
+            import aiohttp
+
+            async with aiohttp.ClientSession() as session:
+                async with session.request(
+                    method,
+                    self._api_url(path),
+                    headers=self.get_auth_headers(),
+                    json=payload,
+                ) as resp:
+                    if resp.status in (200, 201):
+                        return await resp.json()
+                    return {"error": await resp.text(), "status_code": resp.status}
+        except Exception as e:
+            return {"error": str(e)}
+
+    def _request_sync(self, method: str, path: str, payload: dict | None = None) -> dict:
+        """Perform a synchronous Gitea API request."""
+        try:
+            if not self.base_url:
+                return {'error': 'Gitea base URL is not configured or is invalid'}
+            request = urllib.request.Request(
+                self._api_url(path),
+                headers=self.get_auth_headers(),
+                method=method.upper(),
+            )
+            if payload is not None:
+                request.data = json.dumps(payload).encode('utf-8')
+            with urllib.request.urlopen(request) as response:
+                body = response.read().decode('utf-8')
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as exc:
+            try:
+                body = exc.read().decode('utf-8')
+            except Exception:
+                body = str(exc)
+            return {'error': body, 'status_code': exc.code}
+        except Exception as exc:
+            return {'error': str(exc)}
+
+    def build_project_repo_name(self, project_id: str, project_name: str | None = None) -> str:
+        """Build a repository name for a generated project."""
+        preferred = (project_name or project_id or "project").strip().lower().replace(" ", "-")
+        sanitized = "".join(ch if ch.isalnum() or ch in {"-", "_"} else "-" for ch in preferred)
+        while "--" in sanitized:
+            sanitized = sanitized.replace("--", "-")
+        return sanitized.strip("-") or project_id
+
+    async def create_repo(
+        self,
+        repo_name: str,
+        owner: str | None = None,
+        description: str | None = None,
+        private: bool = False,
+        auto_init: bool = True,
+    ) -> dict:
+        """Create a repository inside the configured organization."""
+        _owner = owner or self.owner
+        if not _owner:
+            return {"error": "Owner or organization is required"}
+
+        payload = {
+            "name": repo_name,
+            "description": description or f"AI-generated project repository for {repo_name}",
+            "private": private,
+            "auto_init": auto_init,
+            "default_branch": "main",
+        }
+        result = await self._request("POST", f"orgs/{_owner}/repos", payload)
+        if result.get("status_code") == 409:
+            existing = await self.get_repo_info(owner=_owner, repo=repo_name)
+            if not existing.get("error"):
+                existing["status"] = "exists"
+                return existing
+        if not result.get("error"):
+            result.setdefault("status", "created")
+        return result
+
+    async def delete_repo(self, owner: str | None = None, repo: str | None = None) -> dict:
+        """Delete a repository from the configured organization/user."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo:
+            return {'error': 'Owner and repository name are required'}
+        result = await self._request('DELETE', f'repos/{_owner}/{_repo}')
+        if not result.get('error'):
+            result.setdefault('status', 'deleted')
+        return result
+
+    def delete_repo_sync(self, owner: str | None = None, repo: str | None = None) -> dict:
+        """Synchronously delete a repository from the configured organization/user."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        if not _owner or not _repo:
+            return {'error': 'Owner and repository name are required'}
+        result = self._request_sync('DELETE', f'repos/{_owner}/{_repo}')
+        if not result.get('error'):
+            result.setdefault('status', 'deleted')
+        return result
+
+    async def get_current_user(self) -> dict:
+        """Get the user associated with the configured token."""
+        return await self._request("GET", "user")
+
+    def get_current_user_sync(self) -> dict:
+        """Synchronously get the user associated with the configured token."""
+        return self._request_sync("GET", "user")
+
+    async def create_branch(self, branch: str, base: str = "main", owner: str | None = None, repo: str | None = None):
+        """Create a new branch."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request(
+            "POST",
+            f"repos/{_owner}/{_repo}/branches",
+            {"new_branch_name": branch, "old_ref_name": base},
+        )
+
+    async def create_pull_request(
+        self,
+        title: str,
+        body: str,
+        owner: str,
+        repo: str,
+        base: str = "main",
+        head: str | None = None,
+    ) -> dict:
+        """Create a pull request."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        normalized_head = self._normalize_pull_request_head(head, _owner)
+        payload = {
+            "title": title,
+            "body": body,
+            "base": base,
+            "head": normalized_head or f"{_owner}:{_owner}-{_repo}-ai-gen-{hash(title) % 10000}",
+        }
+        return await self._request("POST", f"repos/{_owner}/{_repo}/pulls", payload)
+
+    def create_pull_request_sync(
+        self,
+        title: str,
+        body: str,
+        owner: str,
+        repo: str,
+        base: str = "main",
+        head: str | None = None,
+    ) -> dict:
+        """Synchronously create a pull request."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        normalized_head = self._normalize_pull_request_head(head, _owner)
+        payload = {
+            "title": title,
+            "body": body,
+            "base": base,
+            "head": normalized_head or f"{_owner}:{_owner}-{_repo}-ai-gen-{hash(title) % 10000}",
+        }
+        return self._request_sync("POST", f"repos/{_owner}/{_repo}/pulls", payload)
+
+    async def list_pull_requests(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        state: str = 'open',
+    ) -> dict | list:
+        """List pull requests for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/pulls?state={state}")
+
+    def list_pull_requests_sync(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        state: str = 'open',
+    ) -> dict | list:
+        """Synchronously list pull requests for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/pulls?state={state}")
+
+    async def list_repositories(self, owner: str | None = None) -> dict | list:
+        """List repositories within the configured organization."""
+        _owner = owner or self.owner
+        return await self._request("GET", f"orgs/{_owner}/repos")
+
+    def list_repositories_sync(self, owner: str | None = None) -> dict | list:
+        """Synchronously list repositories within the configured organization."""
+        _owner = owner or self.owner
+        return self._request_sync("GET", f"orgs/{_owner}/repos")
+
+    async def list_branches(self, owner: str | None = None, repo: str | None = None) -> dict | list:
+        """List repository branches."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/branches")
+
+    def list_branches_sync(self, owner: str | None = None, repo: str | None = None) -> dict | list:
+        """Synchronously list repository branches."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/branches")
+
+    async def list_issues(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        state: str = 'open',
+    ) -> dict | list:
+        """List repository issues, excluding pull requests at the consumer layer."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/issues?state={state}")
+
+    def list_issues_sync(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        state: str = 'open',
+    ) -> dict | list:
+        """Synchronously list repository issues."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/issues?state={state}")
+
+    async def get_issue(self, issue_number: int, owner: str | None = None, repo: str | None = None) -> dict:
+        """Return one repository issue by number."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/issues/{issue_number}")
+
+    def get_issue_sync(self, issue_number: int, owner: str | None = None, repo: str | None = None) -> dict:
+        """Synchronously return one repository issue by number."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/issues/{issue_number}")
+
+    async def list_repo_commits(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        limit: int = 25,
+        branch: str | None = None,
+    ) -> dict | list:
+        """List recent commits for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        branch_query = f"&sha={branch}" if branch else ""
+        return await self._request("GET", f"repos/{_owner}/{_repo}/commits?limit={limit}{branch_query}")
+
+    def list_repo_commits_sync(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+        limit: int = 25,
+        branch: str | None = None,
+    ) -> dict | list:
+        """Synchronously list recent commits for a repository."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        branch_query = f"&sha={branch}" if branch else ""
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/commits?limit={limit}{branch_query}")
+
+    async def get_commit(
+        self,
+        commit_hash: str,
+        owner: str | None = None,
+        repo: str | None = None,
+    ) -> dict:
+        """Return one commit by hash."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/git/commits/{commit_hash}")
+
+    def get_commit_sync(
+        self,
+        commit_hash: str,
+        owner: str | None = None,
+        repo: str | None = None,
+    ) -> dict:
+        """Synchronously return one commit by hash."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/git/commits/{commit_hash}")
+
+    async def get_pull_request(self, pr_number: int, owner: str | None = None, repo: str | None = None) -> dict:
+        """Return one pull request by number."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return await self._request("GET", f"repos/{_owner}/{_repo}/pulls/{pr_number}")
+
+    def get_pull_request_sync(self, pr_number: int, owner: str | None = None, repo: str | None = None) -> dict:
+        """Synchronously return one pull request by number."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}/pulls/{pr_number}")
+
+    async def push_commit(
+        self,
+        branch: str,
+        files: list[dict],
+        message: str,
+        owner: str | None = None,
+        repo: str | None = None,
+    ) -> dict:
+        """Push files to a branch.
+
+        In production, this would use gitea's API or git push.
+        For now, this remains simulated.
+        """
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+
+        return {
+            "status": "simulated",
+            "branch": branch,
+            "message": message,
+            "files": files,
+            "owner": _owner,
+            "repo": _repo,
+        }
+
+    async def get_repo_info(self, owner: str | None = None, repo: str | None = None) -> dict:
+        """Get repository information."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+
+        if not _repo:
+            return {"error": "Repository name required for org operations"}
+
+        return await self._request("GET", f"repos/{_owner}/{_repo}")
+
+    def get_repo_info_sync(self, owner: str | None = None, repo: str | None = None) -> dict:
+        """Synchronously get repository information."""
+        _owner = owner or self.owner
+        _repo = repo or self.repo
+
+        if not _repo:
+            return {"error": "Repository name required for org operations"}
+
+        return self._request_sync("GET", f"repos/{_owner}/{_repo}")

ai_software_factory/agents/home_assistant.py

@@ -0,0 +1,162 @@
+"""Home Assistant integration for energy-gated queue processing."""
+
+from __future__ import annotations
+
+try:
+    from ..config import settings
+except ImportError:
+    from config import settings
+
+
+class HomeAssistantAgent:
+    """Query Home Assistant for queue-processing eligibility and health."""
+
+    def __init__(self, base_url: str | None = None, token: str | None = None):
+        self.base_url = (base_url or settings.home_assistant_url).rstrip('/')
+        self.token = token or settings.home_assistant_token
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            'Authorization': f'Bearer {self.token}',
+            'Content-Type': 'application/json',
+        }
+
+    def _state_url(self, entity_id: str) -> str:
+        return f'{self.base_url}/api/states/{entity_id}'
+
+    async def _get_state(self, entity_id: str) -> dict:
+        if not self.base_url:
+            return {'error': 'Home Assistant URL is not configured'}
+        if not self.token:
+            return {'error': 'Home Assistant token is not configured'}
+        if not entity_id:
+            return {'error': 'Home Assistant entity id is not configured'}
+        try:
+            import aiohttp
+
+            async with aiohttp.ClientSession() as session:
+                async with session.get(self._state_url(entity_id), headers=self._headers()) as resp:
+                    payload = await resp.json(content_type=None)
+                    if 200 <= resp.status < 300:
+                        return payload if isinstance(payload, dict) else {'value': payload}
+                    return {'error': payload, 'status_code': resp.status}
+        except Exception as exc:
+            return {'error': str(exc)}
+
+    def _get_state_sync(self, entity_id: str) -> dict:
+        if not self.base_url:
+            return {'error': 'Home Assistant URL is not configured'}
+        if not self.token:
+            return {'error': 'Home Assistant token is not configured'}
+        if not entity_id:
+            return {'error': 'Home Assistant entity id is not configured'}
+        try:
+            import json
+            import urllib.error
+            import urllib.request
+
+            request = urllib.request.Request(self._state_url(entity_id), headers=self._headers(), method='GET')
+            with urllib.request.urlopen(request) as response:
+                body = response.read().decode('utf-8')
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as exc:
+            try:
+                body = exc.read().decode('utf-8')
+            except Exception:
+                body = str(exc)
+            return {'error': body, 'status_code': exc.code}
+        except Exception as exc:
+            return {'error': str(exc)}
+
+    @staticmethod
+    def _coerce_float(payload: dict) -> float | None:
+        raw = payload.get('state') if isinstance(payload, dict) else None
+        try:
+            return float(raw)
+        except Exception:
+            return None
+
+    async def queue_gate_status(self, force: bool = False) -> dict:
+        """Return whether queued prompts may be processed now."""
+        if force or settings.prompt_queue_force_process:
+            return {
+                'status': 'success',
+                'allowed': True,
+                'forced': True,
+                'reason': 'Queue override is enabled',
+            }
+        battery = await self._get_state(settings.home_assistant_battery_entity_id)
+        surplus = await self._get_state(settings.home_assistant_surplus_entity_id)
+        battery_value = self._coerce_float(battery)
+        surplus_value = self._coerce_float(surplus)
+        checks = []
+        if battery.get('error'):
+            checks.append({'name': 'battery', 'ok': False, 'message': str(battery.get('error')), 'entity_id': settings.home_assistant_battery_entity_id})
+        else:
+            checks.append({'name': 'battery', 'ok': battery_value is not None and battery_value >= settings.home_assistant_battery_full_threshold, 'message': f'{battery_value}%', 'entity_id': settings.home_assistant_battery_entity_id})
+        if surplus.get('error'):
+            checks.append({'name': 'surplus', 'ok': False, 'message': str(surplus.get('error')), 'entity_id': settings.home_assistant_surplus_entity_id})
+        else:
+            checks.append({'name': 'surplus', 'ok': surplus_value is not None and surplus_value >= settings.home_assistant_surplus_threshold_watts, 'message': f'{surplus_value} W', 'entity_id': settings.home_assistant_surplus_entity_id})
+        allowed = all(check['ok'] for check in checks)
+        return {
+            'status': 'success' if allowed else 'blocked',
+            'allowed': allowed,
+            'forced': False,
+            'checks': checks,
+            'battery_level': battery_value,
+            'surplus_watts': surplus_value,
+            'thresholds': {
+                'battery_full_percent': settings.home_assistant_battery_full_threshold,
+                'surplus_watts': settings.home_assistant_surplus_threshold_watts,
+            },
+            'reason': 'Energy gate open' if allowed else 'Battery or surplus threshold not met',
+        }
+
+    def health_check_sync(self) -> dict:
+        """Return current Home Assistant connectivity and queue gate diagnostics."""
+        if not self.base_url:
+            return {
+                'status': 'error',
+                'message': 'Home Assistant URL is not configured.',
+                'base_url': '',
+                'configured': False,
+                'checks': [],
+            }
+        if not self.token:
+            return {
+                'status': 'error',
+                'message': 'Home Assistant token is not configured.',
+                'base_url': self.base_url,
+                'configured': False,
+                'checks': [],
+            }
+        battery = self._get_state_sync(settings.home_assistant_battery_entity_id)
+        surplus = self._get_state_sync(settings.home_assistant_surplus_entity_id)
+        checks = []
+        for name, entity_id, payload in (
+            ('battery', settings.home_assistant_battery_entity_id, battery),
+            ('surplus', settings.home_assistant_surplus_entity_id, surplus),
+        ):
+            checks.append(
+                {
+                    'name': name,
+                    'entity_id': entity_id,
+                    'ok': not bool(payload.get('error')),
+                    'message': str(payload.get('error') or payload.get('state') or 'ok'),
+                    'status_code': payload.get('status_code'),
+                    'url': self._state_url(entity_id) if entity_id else self.base_url,
+                }
+            )
+        return {
+            'status': 'success' if all(check['ok'] for check in checks) else 'error',
+            'message': 'Home Assistant connectivity is healthy.' if all(check['ok'] for check in checks) else 'Home Assistant checks failed.',
+            'base_url': self.base_url,
+            'configured': True,
+            'checks': checks,
+            'queue_gate': {
+                'battery_full_percent': settings.home_assistant_battery_full_threshold,
+                'surplus_watts': settings.home_assistant_surplus_threshold_watts,
+                'force_process': settings.prompt_queue_force_process,
+            },
+        }

ai_software_factory/agents/llm_service.py

@@ -0,0 +1,535 @@
+"""Centralized LLM client with guardrails and mediated tool context."""
+
+from __future__ import annotations
+
+import json
+from urllib import error as urllib_error
+from urllib import request as urllib_request
+
+try:
+    from .gitea import GiteaAPI
+except ImportError:
+    from gitea import GiteaAPI
+
+try:
+    from ..config import settings
+except ImportError:
+    from config import settings
+
+
+class LLMToolbox:
+    """Build named tool payloads that can be shared with external LLM providers."""
+
+    SUPPORTED_LIVE_TOOL_STAGES = ('request_interpretation', 'change_summary', 'generation_plan', 'project_naming', 'project_id_naming')
+
+    def build_tool_context(self, stage: str, context: dict | None = None) -> list[dict]:
+        """Return the mediated tool payloads allowed for this LLM request."""
+        context = context or {}
+        allowed = set(settings.llm_tool_allowlist)
+        limit = settings.llm_tool_context_limit
+        tool_context: list[dict] = []
+
+        if 'gitea_project_catalog' in allowed:
+            projects = context.get('projects') or []
+            if projects:
+                tool_context.append(
+                    {
+                        'name': 'gitea_project_catalog',
+                        'description': 'Tracked active projects and their repository mappings inside the factory.',
+                        'payload': projects[:limit],
+                    }
+                )
+
+        if 'gitea_project_state' in allowed:
+            state_payload = {
+                'project_id': context.get('project_id'),
+                'project_name': context.get('project_name') or context.get('name'),
+                'repository': context.get('repository'),
+                'repository_url': context.get('repository_url'),
+                'pull_request': context.get('pull_request'),
+                'pull_request_url': context.get('pull_request_url'),
+                'pull_request_state': context.get('pull_request_state'),
+                'related_issue': context.get('related_issue'),
+            }
+            if any(value for value in state_payload.values()):
+                tool_context.append(
+                    {
+                        'name': 'gitea_project_state',
+                        'description': 'Current repository and pull-request state for the project being discussed.',
+                        'payload': state_payload,
+                    }
+                )
+
+        if 'gitea_project_issues' in allowed:
+            issues = context.get('open_issues') or context.get('issues') or []
+            if issues:
+                tool_context.append(
+                    {
+                        'name': 'gitea_project_issues',
+                        'description': 'Open tracked Gitea issues for the relevant project repository.',
+                        'payload': issues[:limit],
+                    }
+                )
+
+        if 'gitea_pull_requests' in allowed:
+            pull_requests = context.get('pull_requests') or []
+            if pull_requests:
+                tool_context.append(
+                    {
+                        'name': 'gitea_pull_requests',
+                        'description': 'Tracked pull requests associated with the relevant project repository.',
+                        'payload': pull_requests[:limit],
+                    }
+                )
+
+        return tool_context
+
+    def build_live_tool_specs(self, stage: str, context: dict | None = None) -> list[dict]:
+        """Return live tool-call specs that the model may request explicitly."""
+        _context = context or {}
+        specs = []
+        allowed = set(settings.llm_live_tools_for_stage(stage))
+        if 'gitea_lookup_issue' in allowed:
+            specs.append(
+                {
+                    'name': 'gitea_lookup_issue',
+                    'description': 'Fetch one live Gitea issue by issue number for a tracked repository.',
+                    'arguments': {
+                        'project_id': 'optional tracked project id',
+                        'owner': 'optional repository owner override',
+                        'repo': 'optional repository name override',
+                        'issue_number': 'required integer issue number',
+                    },
+                }
+            )
+        if 'gitea_lookup_pull_request' in allowed:
+            specs.append(
+                {
+                    'name': 'gitea_lookup_pull_request',
+                    'description': 'Fetch one live Gitea pull request by PR number for a tracked repository.',
+                    'arguments': {
+                        'project_id': 'optional tracked project id',
+                        'owner': 'optional repository owner override',
+                        'repo': 'optional repository name override',
+                        'pr_number': 'required integer pull request number',
+                    },
+                }
+            )
+        return specs
+
+
+class LLMLiveToolExecutor:
+    """Resolve bounded live tool requests on behalf of the model."""
+
+    def __init__(self):
+        self.gitea_api = None
+        if settings.gitea_url and settings.gitea_token:
+            self.gitea_api = GiteaAPI(
+                token=settings.GITEA_TOKEN,
+                base_url=settings.GITEA_URL,
+                owner=settings.GITEA_OWNER,
+                repo=settings.GITEA_REPO or '',
+            )
+
+    async def execute(self, tool_name: str, arguments: dict, context: dict | None = None) -> dict:
+        """Execute one live tool request and normalize the result."""
+        if tool_name not in set(settings.llm_live_tool_allowlist):
+            return {'error': f'Tool {tool_name} is not enabled'}
+        if self.gitea_api is None:
+            return {'error': 'Gitea live tool execution is not configured'}
+        resolved = self._resolve_repository(arguments=arguments, context=context or {})
+        if resolved.get('error'):
+            return resolved
+        owner = resolved['owner']
+        repo = resolved['repo']
+
+        if tool_name == 'gitea_lookup_issue':
+            issue_number = arguments.get('issue_number')
+            if issue_number is None:
+                return {'error': 'issue_number is required'}
+            return await self.gitea_api.get_issue(issue_number=int(issue_number), owner=owner, repo=repo)
+
+        if tool_name == 'gitea_lookup_pull_request':
+            pr_number = arguments.get('pr_number')
+            if pr_number is None:
+                return {'error': 'pr_number is required'}
+            return await self.gitea_api.get_pull_request(pr_number=int(pr_number), owner=owner, repo=repo)
+
+        return {'error': f'Unsupported tool {tool_name}'}
+
+    def _resolve_repository(self, arguments: dict, context: dict) -> dict:
+        """Resolve repository owner/name from explicit args or tracked project context."""
+        owner = arguments.get('owner')
+        repo = arguments.get('repo')
+        if owner and repo:
+            return {'owner': owner, 'repo': repo}
+        project_id = arguments.get('project_id')
+        if project_id:
+            for project in context.get('projects', []):
+                if project.get('project_id') == project_id:
+                    repository = project.get('repository') or {}
+                    if repository.get('owner') and repository.get('name'):
+                        return {'owner': repository['owner'], 'repo': repository['name']}
+            state = context.get('repository') or {}
+            if context.get('project_id') == project_id and state.get('owner') and state.get('name'):
+                return {'owner': state['owner'], 'repo': state['name']}
+        repository = context.get('repository') or {}
+        if repository.get('owner') and repository.get('name'):
+            return {'owner': repository['owner'], 'repo': repository['name']}
+        return {'error': 'Could not resolve repository for tool request'}
+
+
+class LLMServiceClient:
+    """Call the configured LLM provider with consistent guardrails and tool payloads."""
+
+    def __init__(self, ollama_url: str | None = None, model: str | None = None):
+        self.ollama_url = (ollama_url or settings.ollama_url).rstrip('/')
+        self.model = model or settings.OLLAMA_MODEL
+        self.request_timeout_seconds = settings.llm_request_timeout_seconds
+        self.toolbox = LLMToolbox()
+        self.live_tool_executor = LLMLiveToolExecutor()
+
+    async def chat_with_trace(
+        self,
+        *,
+        stage: str,
+        system_prompt: str,
+        user_prompt: str,
+        tool_context_input: dict | None = None,
+        expect_json: bool = False,
+    ) -> tuple[str | None, dict]:
+        """Invoke the configured LLM and return both content and a structured trace."""
+        effective_system_prompt = self._compose_system_prompt(stage, system_prompt)
+        tool_context = self.toolbox.build_tool_context(stage=stage, context=tool_context_input)
+        live_tool_specs = self.toolbox.build_live_tool_specs(stage=stage, context=tool_context_input)
+        effective_user_prompt = self._compose_user_prompt(user_prompt, tool_context, live_tool_specs)
+        raw_responses: list[dict] = []
+        executed_tool_calls: list[dict] = []
+        current_user_prompt = effective_user_prompt
+        max_rounds = settings.llm_max_tool_call_rounds
+
+        for round_index in range(max_rounds + 1):
+            content, payload, error = await self._send_chat_request(
+                system_prompt=effective_system_prompt,
+                user_prompt=current_user_prompt,
+                expect_json=expect_json,
+            )
+            raw_responses.append(payload)
+            if content:
+                tool_request = self._extract_tool_request(content)
+                if tool_request and round_index < max_rounds:
+                    tool_name = tool_request.get('name')
+                    tool_arguments = tool_request.get('arguments') or {}
+                    tool_result = await self.live_tool_executor.execute(tool_name, tool_arguments, tool_context_input)
+                    executed_tool_calls.append(
+                        {
+                            'name': tool_name,
+                            'arguments': tool_arguments,
+                            'result': tool_result,
+                        }
+                    )
+                    current_user_prompt = self._compose_follow_up_prompt(user_prompt, tool_context, live_tool_specs, executed_tool_calls)
+                    continue
+                return content, {
+                    'stage': stage,
+                    'provider': 'ollama',
+                    'model': self.model,
+                    'system_prompt': effective_system_prompt,
+                    'user_prompt': current_user_prompt,
+                    'assistant_response': content,
+                    'raw_response': {
+                        'provider_response': raw_responses[-1],
+                        'provider_responses': raw_responses,
+                        'tool_context': tool_context,
+                        'live_tool_specs': live_tool_specs,
+                        'executed_tool_calls': executed_tool_calls,
+                    },
+                    'raw_responses': raw_responses,
+                    'fallback_used': False,
+                    'guardrails': self._guardrail_sections(stage),
+                    'tool_context': tool_context,
+                    'live_tool_specs': live_tool_specs,
+                    'executed_tool_calls': executed_tool_calls,
+                }
+            if error:
+                break
+
+        return None, {
+            'stage': stage,
+            'provider': 'ollama',
+            'model': self.model,
+            'system_prompt': effective_system_prompt,
+            'user_prompt': current_user_prompt,
+            'assistant_response': '',
+            'raw_response': {
+                'provider_response': raw_responses[-1] if raw_responses else {'error': 'No response'},
+                'provider_responses': raw_responses,
+                'tool_context': tool_context,
+                'live_tool_specs': live_tool_specs,
+                'executed_tool_calls': executed_tool_calls,
+            },
+            'raw_responses': raw_responses,
+            'fallback_used': True,
+            'guardrails': self._guardrail_sections(stage),
+            'tool_context': tool_context,
+            'live_tool_specs': live_tool_specs,
+            'executed_tool_calls': executed_tool_calls,
+        }
+
+    async def _send_chat_request(self, *, system_prompt: str, user_prompt: str, expect_json: bool) -> tuple[str | None, dict, str | None]:
+        """Send one outbound chat request to the configured model provider."""
+        request_payload = {
+            'model': self.model,
+            'stream': False,
+            'messages': [
+                {'role': 'system', 'content': system_prompt},
+                {'role': 'user', 'content': user_prompt},
+            ],
+        }
+        if expect_json:
+            request_payload['format'] = 'json'
+        try:
+            import aiohttp
+
+            async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=self.request_timeout_seconds)) as session:
+                async with session.post(f'{self.ollama_url}/api/chat', json=request_payload) as resp:
+                    payload = await resp.json()
+                    if 200 <= resp.status < 300:
+                        return (payload.get('message') or {}).get('content', ''), payload, None
+                    return None, payload, str(payload.get('error') or payload)
+        except Exception as exc:
+            if exc.__class__.__name__ == 'TimeoutError':
+                message = f'LLM request timed out after {self.request_timeout_seconds} seconds'
+                return None, {'error': message}, message
+            return None, {'error': str(exc)}, str(exc)
+
+    @staticmethod
+    def extract_error_message(trace: dict | None) -> str | None:
+        """Extract the most useful provider error message from a trace payload."""
+        if not isinstance(trace, dict):
+            return None
+        raw_response = trace.get('raw_response') if isinstance(trace.get('raw_response'), dict) else {}
+        provider_response = raw_response.get('provider_response') if isinstance(raw_response.get('provider_response'), dict) else {}
+        candidate_errors = [
+            provider_response.get('error'),
+            raw_response.get('error'),
+            trace.get('error'),
+        ]
+        raw_responses = trace.get('raw_responses') if isinstance(trace.get('raw_responses'), list) else []
+        for payload in reversed(raw_responses):
+            if isinstance(payload, dict) and payload.get('error'):
+                candidate_errors.append(payload.get('error'))
+        for candidate in candidate_errors:
+            if candidate:
+                return str(candidate).strip()
+        return None
+
+    def _compose_system_prompt(self, stage: str, stage_prompt: str) -> str:
+        """Merge the stage prompt with configured guardrails."""
+        sections = [stage_prompt.strip()] + self._guardrail_sections(stage)
+        return '\n\n'.join(section for section in sections if section)
+
+    def _guardrail_sections(self, stage: str) -> list[str]:
+        """Return all configured guardrail sections for one LLM stage."""
+        sections = []
+        if settings.llm_guardrail_prompt:
+            sections.append(f'Global guardrails:\n{settings.llm_guardrail_prompt}')
+        stage_specific = {
+            'request_interpretation': settings.llm_request_interpreter_guardrail_prompt,
+            'change_summary': settings.llm_change_summary_guardrail_prompt,
+            'project_naming': settings.llm_project_naming_guardrail_prompt,
+            'project_id_naming': settings.llm_project_id_guardrail_prompt,
+        }.get(stage)
+        if stage_specific:
+            sections.append(f'Stage-specific guardrails:\n{stage_specific}')
+        return sections
+
+    def _compose_user_prompt(self, prompt: str, tool_context: list[dict], live_tool_specs: list[dict] | None = None) -> str:
+        """Append tool payloads and live tool-call specs to the outbound user prompt."""
+        live_tool_specs = live_tool_specs if live_tool_specs is not None else []
+        sections = [prompt]
+        if not tool_context:
+            pass
+        else:
+            sections.append(
+                'Service-mediated tool outputs are available below. Treat them as authoritative read-only data supplied by the factory:\n'
+                f'{json.dumps(tool_context, indent=2, sort_keys=True)}'
+            )
+        if live_tool_specs:
+            sections.append(
+                'If you need additional live repository data, you may request exactly one tool call by responding with JSON shaped as '
+                '{"tool_request": {"name": "<tool name>", "arguments": {...}}}. '
+                'After tool results are returned, respond with the final answer instead of another tool request.\n'
+                f'Available live tools:\n{json.dumps(live_tool_specs, indent=2, sort_keys=True)}'
+            )
+        return '\n\n'.join(section for section in sections if section)
+
+    def _compose_follow_up_prompt(self, original_prompt: str, tool_context: list[dict], live_tool_specs: list[dict], executed_tool_calls: list[dict]) -> str:
+        """Build the follow-up user prompt after executing one or more live tool requests."""
+        sections = [self._compose_user_prompt(original_prompt, tool_context, live_tool_specs)]
+        sections.append(
+            'The service executed the requested live tool call(s). Use the tool result(s) below to produce the final answer. Do not request another tool call.\n'
+            f'{json.dumps(executed_tool_calls, indent=2, sort_keys=True)}'
+        )
+        return '\n\n'.join(sections)
+
+    def _extract_tool_request(self, content: str) -> dict | None:
+        """Return a normalized tool request when the model explicitly asks for one."""
+        try:
+            parsed = json.loads(content)
+        except Exception:
+            return None
+        if not isinstance(parsed, dict):
+            return None
+        tool_request = parsed.get('tool_request')
+        if not isinstance(tool_request, dict) or not tool_request.get('name'):
+            return None
+        return {
+            'name': str(tool_request.get('name')).strip(),
+            'arguments': tool_request.get('arguments') or {},
+        }
+
+    def get_runtime_configuration(self) -> dict:
+        """Return the active LLM runtime config, guardrails, and tool exposure."""
+        live_tool_stages = {
+            stage: settings.llm_live_tools_for_stage(stage)
+            for stage in self.toolbox.SUPPORTED_LIVE_TOOL_STAGES
+        }
+        return {
+            'provider': 'ollama',
+            'ollama_url': self.ollama_url,
+            'model': self.model,
+            'guardrails': {
+                'global': settings.llm_guardrail_prompt,
+                'request_interpretation': settings.llm_request_interpreter_guardrail_prompt,
+                'change_summary': settings.llm_change_summary_guardrail_prompt,
+                'project_naming': settings.llm_project_naming_guardrail_prompt,
+                'project_id_naming': settings.llm_project_id_guardrail_prompt,
+            },
+            'system_prompts': {
+                'project_naming': settings.llm_project_naming_system_prompt,
+                'project_id_naming': settings.llm_project_id_system_prompt,
+            },
+            'mediated_tools': settings.llm_tool_allowlist,
+            'live_tools': settings.llm_live_tool_allowlist,
+            'live_tool_stage_allowlist': settings.llm_live_tool_stage_allowlist,
+            'live_tool_stage_tool_map': settings.llm_live_tool_stage_tool_map,
+            'live_tools_by_stage': live_tool_stages,
+            'tool_context_limit': settings.llm_tool_context_limit,
+            'max_tool_call_rounds': settings.llm_max_tool_call_rounds,
+            'gitea_live_tools_configured': bool(settings.gitea_url and settings.gitea_token),
+        }
+
+    def health_check_sync(self) -> dict:
+        """Synchronously check Ollama reachability and configured model availability."""
+        if not self.ollama_url:
+            return {
+                'status': 'error',
+                'message': 'OLLAMA_URL is not configured.',
+                'ollama_url': 'Not configured',
+                'model': self.model,
+                'checks': [],
+                'suggestion': 'Set OLLAMA_URL to the reachable Ollama base URL.',
+            }
+
+        tags_url = f'{self.ollama_url}/api/tags'
+        try:
+            req = urllib_request.Request(tags_url, headers={'User-Agent': 'AI-Software-Factory'}, method='GET')
+            with urllib_request.urlopen(req, timeout=5) as resp:
+                raw_body = resp.read().decode('utf-8')
+                payload = json.loads(raw_body) if raw_body else {}
+        except urllib_error.HTTPError as exc:
+            body = exc.read().decode('utf-8') if exc.fp else ''
+            message = body or str(exc)
+            return {
+                'status': 'error',
+                'message': f'Ollama returned HTTP {exc.code}: {message}',
+                'ollama_url': self.ollama_url,
+                'model': self.model,
+                'checks': [
+                    {
+                        'name': 'api_tags',
+                        'ok': False,
+                        'status_code': exc.code,
+                        'url': tags_url,
+                        'message': message,
+                    }
+                ],
+                'suggestion': 'Verify OLLAMA_URL points to the Ollama service and that the API is reachable.',
+            }
+        except Exception as exc:
+            return {
+                'status': 'error',
+                'message': f'Unable to reach Ollama: {exc}',
+                'ollama_url': self.ollama_url,
+                'model': self.model,
+                'checks': [
+                    {
+                        'name': 'api_tags',
+                        'ok': False,
+                        'status_code': None,
+                        'url': tags_url,
+                        'message': str(exc),
+                    }
+                ],
+                'suggestion': 'Verify OLLAMA_URL resolves from the running factory process and that Ollama is listening on that address.',
+            }
+
+        models = payload.get('models') if isinstance(payload, dict) else []
+        model_names: list[str] = []
+        if isinstance(models, list):
+            for model_entry in models:
+                if not isinstance(model_entry, dict):
+                    continue
+                name = str(model_entry.get('name') or model_entry.get('model') or '').strip()
+                if name:
+                    model_names.append(name)
+
+        requested = (self.model or '').strip()
+        requested_base = requested.split(':', 1)[0]
+        model_available = any(
+            name == requested or name.startswith(f'{requested}:') or name.split(':', 1)[0] == requested_base
+            for name in model_names
+        )
+        checks = [
+            {
+                'name': 'api_tags',
+                'ok': True,
+                'status_code': 200,
+                'url': tags_url,
+                'message': f'Loaded {len(model_names)} model entries.',
+            },
+            {
+                'name': 'configured_model',
+                'ok': model_available,
+                'status_code': None,
+                'url': None,
+                'message': (
+                    f'Configured model {requested} is available.'
+                    if model_available else
+                    f'Configured model {requested} was not found in Ollama tags.'
+                ),
+            },
+        ]
+        if model_available:
+            return {
+                'status': 'success',
+                'message': f'Ollama is reachable and model {requested} is available.',
+                'ollama_url': self.ollama_url,
+                'model': requested,
+                'model_available': True,
+                'model_count': len(model_names),
+                'models': model_names[:10],
+                'checks': checks,
+            }
+        return {
+            'status': 'error',
+            'message': f'Ollama is reachable, but model {requested} is not available.',
+            'ollama_url': self.ollama_url,
+            'model': requested,
+            'model_available': False,
+            'model_count': len(model_names),
+            'models': model_names[:10],
+            'checks': checks,
+            'suggestion': f'Pull or configure the model {requested}, or update OLLAMA_MODEL to a model that exists in Ollama.',
+        }

ai_software_factory/agents/n8n_setup.py

@@ -0,0 +1,551 @@
+"""n8n setup agent for automatic webhook configuration."""
+
+import json
+from urllib import error as urllib_error
+from urllib import request as urllib_request
+from typing import Optional
+
+try:
+    from ..config import settings
+except ImportError:
+    from config import settings
+
+
+class N8NSetupAgent:
+    """Automatically configures n8n webhooks and workflows using API token authentication."""
+    
+    def __init__(self, api_url: str, webhook_token: str):
+        """Initialize n8n setup agent.
+        
+        Args:
+            api_url: n8n API URL (e.g., http://n8n.yourserver.com)
+            webhook_token: n8n webhook token for API access (more secure than username/password)
+            
+        Note: Set the webhook token in n8n via Settings > Credentials > Webhook
+              This token is used for all API requests instead of Basic Auth
+        """
+        self.api_url = api_url.rstrip("/")
+        self.webhook_token = webhook_token
+        self.session = None
+
+    def _api_path(self, path: str) -> str:
+        """Build a full n8n API URL for a given endpoint path."""
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        trimmed = path.lstrip("/")
+        if trimmed.startswith("api/"):
+            return f"{self.api_url}/{trimmed}"
+        return f"{self.api_url}/api/v1/{trimmed}"
+    
+    def get_auth_headers(self) -> dict:
+        """Get authentication headers for n8n API using webhook token."""
+        headers = {
+            "n8n-no-credentials": "true",
+            "Content-Type": "application/json",
+            "User-Agent": "AI-Software-Factory"
+        }
+        if self.webhook_token:
+            headers["X-N8N-API-KEY"] = self.webhook_token
+        return headers
+
+    def _extract_message(self, payload: object) -> str:
+        """Extract a useful message from an n8n response payload."""
+        if isinstance(payload, dict):
+            for key in ("message", "error", "reason", "hint", "text"):
+                value = payload.get(key)
+                if value:
+                    return str(value)
+            if payload:
+                return json.dumps(payload)
+        if payload is None:
+            return "No response body"
+        return str(payload)
+
+    def _normalize_success(self, method: str, url: str, status_code: int, payload: object) -> dict:
+        """Normalize a successful n8n API response."""
+        if isinstance(payload, dict):
+            response = dict(payload)
+            response.setdefault("status_code", status_code)
+            response.setdefault("url", url)
+            response.setdefault("method", method)
+            return response
+        return {"data": payload, "status_code": status_code, "url": url, "method": method}
+
+    def _normalize_error(self, method: str, url: str, status_code: int | None, payload: object) -> dict:
+        """Normalize an error response with enough detail for diagnostics."""
+        message = self._extract_message(payload)
+        prefix = f"{method} {url}"
+        if status_code is not None:
+            return {
+                "error": f"{prefix} returned {status_code}: {message}",
+                "message": message,
+                "status_code": status_code,
+                "url": url,
+                "method": method,
+                "payload": payload,
+            }
+        return {
+            "error": f"{prefix} failed: {message}",
+            "message": message,
+            "status_code": None,
+            "url": url,
+            "method": method,
+            "payload": payload,
+        }
+
+    def _health_check_row(self, name: str, result: dict) -> dict:
+        """Convert a raw request result into a UI/API-friendly health check row."""
+        return {
+            "name": name,
+            "ok": not bool(result.get("error")),
+            "url": result.get("url"),
+            "method": result.get("method", "GET"),
+            "status_code": result.get("status_code"),
+            "message": result.get("message") or ("ok" if not result.get("error") else result.get("error")),
+        }
+
+    def _health_suggestion(self, checks: list[dict]) -> str | None:
+        """Return a suggestion based on failed n8n health checks."""
+        status_codes = {check.get("status_code") for check in checks if check.get("status_code") is not None}
+        if status_codes and status_codes.issubset({404}):
+            return "Verify N8N_API_URL points to the base n8n URL, for example http://host:5678, not /api/v1 or a webhook URL."
+        if status_codes & {401, 403}:
+            return "Check the configured n8n API key or authentication method."
+        return "Verify the n8n URL, API key, and that the n8n API is reachable from this container."
+
+    def _build_health_result(self, healthz_result: dict, workflows_result: dict) -> dict:
+        """Build a consolidated health result from the performed checks."""
+        checks = [
+            self._health_check_row("healthz", healthz_result),
+            self._health_check_row("workflows", workflows_result),
+        ]
+
+        if not healthz_result.get("error"):
+            return {
+                "status": "ok",
+                "message": "n8n is reachable via /healthz.",
+                "api_url": self.api_url,
+                "auth_configured": bool(self.webhook_token),
+                "checked_via": "healthz",
+                "checks": checks,
+            }
+
+        if not workflows_result.get("error"):
+            workflows = workflows_result.get("data")
+            workflow_count = len(workflows) if isinstance(workflows, list) else None
+            return {
+                "status": "ok",
+                "message": "n8n is reachable via the workflows API, but /healthz is unavailable.",
+                "api_url": self.api_url,
+                "auth_configured": bool(self.webhook_token),
+                "checked_via": "workflows",
+                "workflow_count": workflow_count,
+                "checks": checks,
+            }
+
+        suggestion = self._health_suggestion(checks)
+        return {
+            "status": "error",
+            "error": "n8n health checks failed",
+            "message": "n8n health checks failed.",
+            "api_url": self.api_url,
+            "auth_configured": bool(self.webhook_token),
+            "checked_via": "none",
+            "checks": checks,
+            "suggestion": suggestion,
+        }
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict:
+        """Send a request to n8n and normalize the response."""
+        import aiohttp
+
+        headers = kwargs.pop("headers", None) or self.get_auth_headers()
+        url = self._api_path(path)
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.request(method, url, headers=headers, **kwargs) as resp:
+                    content_type = resp.headers.get("Content-Type", "")
+                    if "application/json" in content_type:
+                        payload = await resp.json()
+                    else:
+                        payload = {"text": await resp.text()}
+
+                    if 200 <= resp.status < 300:
+                        return self._normalize_success(method, url, resp.status, payload)
+
+                    return self._normalize_error(method, url, resp.status, payload)
+        except Exception as e:
+            return self._normalize_error(method, url, None, {"message": str(e)})
+
+    def _request_sync(self, method: str, path: str, **kwargs) -> dict:
+        """Send a synchronous request to n8n for dashboard health snapshots."""
+        headers = kwargs.pop("headers", None) or self.get_auth_headers()
+        payload = kwargs.pop("json", None)
+        timeout = kwargs.pop("timeout", 5)
+        url = self._api_path(path)
+        data = None
+        if payload is not None:
+            data = json.dumps(payload).encode("utf-8")
+        req = urllib_request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib_request.urlopen(req, timeout=timeout) as resp:
+                raw_body = resp.read().decode("utf-8")
+                content_type = resp.headers.get("Content-Type", "")
+                if "application/json" in content_type and raw_body:
+                    parsed = json.loads(raw_body)
+                elif raw_body:
+                    parsed = {"text": raw_body}
+                else:
+                    parsed = {}
+                return self._normalize_success(method, url, resp.status, parsed)
+        except urllib_error.HTTPError as exc:
+            raw_body = exc.read().decode("utf-8") if exc.fp else ""
+            try:
+                parsed = json.loads(raw_body) if raw_body else {}
+            except json.JSONDecodeError:
+                parsed = {"text": raw_body} if raw_body else {}
+            return self._normalize_error(method, url, exc.code, parsed)
+        except Exception as exc:
+            return self._normalize_error(method, url, None, {"message": str(exc)})
+    
+    async def get_workflow(self, workflow_name: str) -> Optional[dict]:
+        """Get a workflow by name."""
+        workflows = await self.list_workflows()
+        if isinstance(workflows, dict) and workflows.get("error"):
+            return workflows
+        for workflow in workflows:
+            if workflow.get("name") == workflow_name:
+                return workflow
+        return None
+    
+    async def create_workflow(self, workflow_json: dict) -> dict:
+        """Create or update a workflow."""
+        return await self._request("POST", "workflows", json=self._workflow_payload(workflow_json))
+
+    def _workflow_payload(self, workflow_json: dict) -> dict:
+        """Return a workflow payload without server-managed read-only fields."""
+        payload = dict(workflow_json)
+        payload.pop("active", None)
+        payload.pop("id", None)
+        payload.pop("createdAt", None)
+        payload.pop("updatedAt", None)
+        payload.pop("versionId", None)
+        return payload
+
+    async def _update_workflow_via_put(self, workflow_id: str, workflow_json: dict) -> dict:
+        """Fallback update path for n8n instances that only support PUT."""
+        return await self._request("PUT", f"workflows/{workflow_id}", json=self._workflow_payload(workflow_json))
+
+    async def update_workflow(self, workflow_id: str, workflow_json: dict) -> dict:
+        """Update an existing workflow."""
+        result = await self._request("PATCH", f"workflows/{workflow_id}", json=self._workflow_payload(workflow_json))
+        if result.get("status_code") == 405:
+            fallback = await self._update_workflow_via_put(workflow_id, workflow_json)
+            if not fallback.get("error") and isinstance(fallback, dict):
+                fallback.setdefault("method", "PUT")
+            return fallback
+        return result
+    
+    async def enable_workflow(self, workflow_id: str) -> dict:
+        """Enable a workflow."""
+        result = await self._request("POST", f"workflows/{workflow_id}/activate")
+        if result.get("error"):
+            fallback = await self._request("PATCH", f"workflows/{workflow_id}", json={"active": True})
+            if fallback.get("error"):
+                if fallback.get("status_code") == 405:
+                    put_fallback = await self._request("PUT", f"workflows/{workflow_id}", json={"active": True})
+                    if put_fallback.get("error"):
+                        return put_fallback
+                    return {"success": True, "id": workflow_id, "method": "put"}
+                return fallback
+            return {"success": True, "id": workflow_id, "method": "patch"}
+        return {"success": True, "id": workflow_id, "method": "activate"}
+    
+    async def list_workflows(self) -> list:
+        """List all workflows."""
+        result = await self._request("GET", "workflows")
+        if result.get("error"):
+            return result
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict):
+            for key in ("data", "workflows"):
+                value = result.get(key)
+                if isinstance(value, list):
+                    return value
+        return []
+
+    def build_telegram_workflow(self, webhook_path: str, backend_url: str, allowed_chat_id: str | None = None) -> dict:
+        """Build the Telegram-to-backend workflow definition."""
+        normalized_path = webhook_path.strip().strip("/") or "telegram"
+        allowed_chat = json.dumps(str(allowed_chat_id)) if allowed_chat_id else "''"
+        return {
+            "name": "Telegram to AI Software Factory",
+            "settings": {"executionOrder": "v1"},
+            "nodes": [
+                {
+                    "id": "webhook-node",
+                    "name": "Telegram Webhook",
+                    "type": "n8n-nodes-base.webhook",
+                    "typeVersion": 2,
+                    "position": [-520, 120],
+                    "parameters": {
+                        "httpMethod": "POST",
+                        "path": normalized_path,
+                        "responseMode": "responseNode",
+                        "options": {},
+                    },
+                },
+                {
+                    "id": "parse-node",
+                    "name": "Prepare Freeform Request",
+                    "type": "n8n-nodes-base.code",
+                    "typeVersion": 2,
+                    "position": [-200, 120],
+                    "parameters": {
+                        "language": "javaScript",
+                        "jsCode": f"const allowedChatId = {allowed_chat};\nconst body = $json.body ?? $json;\nconst message = body.message ?? body;\nconst text = String(message.text ?? '').trim();\nconst chatId = String(message.chat?.id ?? '');\nif (allowedChatId && chatId !== allowedChatId) {{\n  return [{{ json: {{ ignored: true, message: `Ignoring message from chat ${{chatId}}`, prompt_text: text, source: 'telegram', chat_id: chatId, chat_type: message.chat?.type ?? null }} }}];\n}}\nreturn [{{ json: {{ prompt_text: text, source: 'telegram', chat_id: chatId, chat_type: message.chat?.type ?? null }} }}];",
+                    },
+                },
+                {
+                    "id": "api-node",
+                    "name": "AI Software Factory API",
+                    "type": "n8n-nodes-base.httpRequest",
+                    "typeVersion": 4.2,
+                    "position": [120, 120],
+                    "parameters": {
+                        "method": "POST",
+                        "url": backend_url,
+                        "sendBody": True,
+                        "specifyBody": "json",
+                        "jsonBody": "={{ $json }}",
+                        "options": {"response": {"response": {"fullResponse": False}}},
+                    },
+                },
+                {
+                    "id": "response-node",
+                    "name": "Respond to Telegram Webhook",
+                    "type": "n8n-nodes-base.respondToWebhook",
+                    "typeVersion": 1.2,
+                    "position": [420, 120],
+                    "parameters": {
+                        "respondWith": "json",
+                        "responseBody": "={{ $json }}",
+                    },
+                },
+            ],
+            "connections": {
+                "Telegram Webhook": {"main": [[{"node": "Prepare Freeform Request", "type": "main", "index": 0}]]},
+                "Prepare Freeform Request": {"main": [[{"node": "AI Software Factory API", "type": "main", "index": 0}]]},
+                "AI Software Factory API": {"main": [[{"node": "Respond to Telegram Webhook", "type": "main", "index": 0}]]},
+            },
+        }
+
+    def build_telegram_trigger_workflow(
+        self,
+        backend_url: str,
+        credential_name: str,
+        allowed_chat_id: str | None = None,
+    ) -> dict:
+        """Build a production Telegram Trigger based workflow."""
+        allowed_chat = json.dumps(str(allowed_chat_id)) if allowed_chat_id else "''"
+        return {
+            "name": "Telegram to AI Software Factory",
+            "settings": {"executionOrder": "v1"},
+            "nodes": [
+                {
+                    "id": "telegram-trigger-node",
+                    "name": "Telegram Trigger",
+                    "type": "n8n-nodes-base.telegramTrigger",
+                    "typeVersion": 1,
+                    "position": [-520, 120],
+                    "parameters": {"updates": ["message", "channel_post"]},
+                    "credentials": {"telegramApi": {"name": credential_name}},
+                },
+                {
+                    "id": "filter-node",
+                    "name": "Prepare Freeform Request",
+                    "type": "n8n-nodes-base.code",
+                    "typeVersion": 2,
+                    "position": [-180, 120],
+                    "parameters": {
+                        "language": "javaScript",
+                        "jsCode": f"const allowedChatId = {allowed_chat};\nconst message = $json.message ?? $json.channel_post ?? $json;\nconst text = String(message.text ?? '').trim();\nconst chatId = String(message.chat?.id ?? '');\nif (!text) return [];\nif (allowedChatId && chatId !== allowedChatId) return [];\nreturn [{{ json: {{ prompt_text: text, source: 'telegram', chat_id: chatId, chat_type: message.chat?.type ?? null }} }}];",
+                    },
+                },
+                {
+                    "id": "api-node",
+                    "name": "AI Software Factory API",
+                    "type": "n8n-nodes-base.httpRequest",
+                    "typeVersion": 4.2,
+                    "position": [120, 120],
+                    "parameters": {
+                        "method": "POST",
+                        "url": backend_url,
+                        "sendBody": True,
+                        "specifyBody": "json",
+                        "jsonBody": "={{ $json }}",
+                        "options": {"response": {"response": {"fullResponse": False}}},
+                    },
+                },
+                {
+                    "id": "reply-node",
+                    "name": "Send Telegram Update",
+                    "type": "n8n-nodes-base.telegram",
+                    "typeVersion": 1,
+                    "position": [420, 120],
+                    "parameters": {
+                        "resource": "message",
+                        "operation": "sendMessage",
+                        "chatId": "={{ ($('Telegram Trigger').item.json.message ?? $('Telegram Trigger').item.json.channel_post).chat.id }}",
+                        "text": "={{ $json.summary_message || $json.data?.summary_message || $json.message || 'Software generation request accepted' }}",
+                    },
+                    "credentials": {"telegramApi": {"name": credential_name}},
+                },
+            ],
+            "connections": {
+                "Telegram Trigger": {"main": [[{"node": "Prepare Freeform Request", "type": "main", "index": 0}]]},
+                "Prepare Freeform Request": {"main": [[{"node": "AI Software Factory API", "type": "main", "index": 0}]]},
+                "AI Software Factory API": {"main": [[{"node": "Send Telegram Update", "type": "main", "index": 0}]]},
+            },
+        }
+
+    async def list_credentials(self) -> list:
+        """List n8n credentials."""
+        result = await self._request("GET", "credentials")
+        if result.get("error"):
+            return []
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict):
+            for key in ("data", "credentials"):
+                value = result.get(key)
+                if isinstance(value, list):
+                    return value
+        return []
+
+    async def get_credential(self, credential_name: str, credential_type: str = "telegramApi") -> Optional[dict]:
+        """Get an existing credential by name and type."""
+        credentials = await self.list_credentials()
+        for credential in credentials:
+            if credential.get("name") == credential_name and credential.get("type") == credential_type:
+                return credential
+        return None
+
+    async def create_credential(self, name: str, credential_type: str, data: dict) -> dict:
+        """Create an n8n credential."""
+        payload = {"name": name, "type": credential_type, "data": data}
+        return await self._request("POST", "credentials", json=payload)
+
+    async def ensure_telegram_credential(self, bot_token: str, credential_name: str) -> dict:
+        """Ensure a Telegram credential exists for the workflow trigger."""
+        existing = await self.get_credential(credential_name)
+        if existing:
+            return existing
+        return await self.create_credential(
+            name=credential_name,
+            credential_type="telegramApi",
+            data={"accessToken": bot_token},
+        )
+    
+    async def setup_telegram_workflow(self, webhook_path: str) -> dict:
+        """Setup the Telegram webhook workflow in n8n.
+        
+        Args:
+            webhook_path: The webhook path (e.g., /webhook/telegram)
+            
+        Returns:
+            Result of setup operation
+        """
+        return await self.setup(
+            webhook_path=webhook_path,
+            backend_url=f"{settings.backend_public_url}/generate/text",
+            force_update=False,
+        )
+    
+    async def health_check(self) -> dict:
+        """Check n8n API health."""
+        result = await self._request("GET", f"{self.api_url}/healthz")
+        fallback = await self._request("GET", "workflows")
+        return self._build_health_result(result, fallback)
+
+    def health_check_sync(self) -> dict:
+        """Synchronously check n8n API health for UI rendering."""
+        result = self._request_sync("GET", f"{self.api_url}/healthz")
+        fallback = self._request_sync("GET", "workflows")
+        return self._build_health_result(result, fallback)
+    
+    async def setup(
+        self,
+        webhook_path: str = "telegram",
+        backend_url: str | None = None,
+        force_update: bool = False,
+        use_telegram_trigger: bool | None = None,
+        telegram_bot_token: str | None = None,
+        telegram_credential_name: str | None = None,
+    ) -> dict:
+        """Setup n8n webhooks automatically."""
+        # First, verify n8n is accessible
+        health = await self.health_check()
+        if health.get("error"):
+            return {
+                "status": "error",
+                "message": health.get("message") or health.get("error"),
+                "health": health,
+                "checks": health.get("checks", []),
+                "suggestion": health.get("suggestion"),
+            }
+        
+        effective_backend_url = backend_url or f"{settings.backend_public_url}/generate/text"
+        effective_bot_token = telegram_bot_token or settings.telegram_bot_token
+        effective_credential_name = telegram_credential_name or settings.n8n_telegram_credential_name
+        trigger_mode = use_telegram_trigger if use_telegram_trigger is not None else bool(effective_bot_token)
+
+        if trigger_mode:
+            credential = await self.ensure_telegram_credential(effective_bot_token, effective_credential_name)
+            if credential.get("error"):
+                return {"status": "error", "message": credential["error"], "details": credential}
+            workflow = self.build_telegram_trigger_workflow(
+                backend_url=effective_backend_url,
+                credential_name=effective_credential_name,
+                allowed_chat_id=settings.telegram_chat_id,
+            )
+        else:
+            workflow = self.build_telegram_workflow(
+                webhook_path=webhook_path,
+                backend_url=effective_backend_url,
+                allowed_chat_id=settings.telegram_chat_id,
+            )
+
+        existing = await self.get_workflow(workflow["name"])
+        if isinstance(existing, dict) and existing.get("error"):
+            return {"status": "error", "message": existing["error"], "details": existing}
+
+        workflow_id = None
+        if existing and existing.get("id"):
+            workflow_id = str(existing["id"])
+            if force_update:
+                result = await self.update_workflow(workflow_id, workflow)
+            else:
+                result = existing
+        else:
+            result = await self.create_workflow(workflow)
+            workflow_id = str(result.get("id", "")) if isinstance(result, dict) else None
+
+        if isinstance(result, dict) and result.get("error"):
+            return {"status": "error", "message": result["error"], "details": result}
+
+        workflow_id = workflow_id or str(result.get("id", ""))
+        enable_result = await self.enable_workflow(workflow_id)
+        if enable_result.get("error"):
+            return {"status": "error", "message": enable_result["error"], "workflow": result, "details": enable_result}
+
+        return {
+            "status": "success",
+            "message": f'Workflow "{workflow["name"]}" is active',
+            "workflow_id": workflow_id,
+            "workflow_name": workflow["name"],
+            "webhook_path": webhook_path.strip().strip("/") or "telegram",
+            "backend_url": effective_backend_url,
+            "trigger_mode": "telegram" if trigger_mode else "webhook",
+        }

ai_software_factory/agents/prompt_workflow.py

@@ -0,0 +1,127 @@
+"""Helpers for prompt-level repository workflows such as undoing a prompt."""
+
+from __future__ import annotations
+
+import subprocess
+
+try:
+    from ..config import settings
+    from .database_manager import DatabaseManager
+    from .git_manager import GitManager
+    from .gitea import GiteaAPI
+except ImportError:
+    from config import settings
+    from agents.database_manager import DatabaseManager
+    from agents.git_manager import GitManager
+    from agents.gitea import GiteaAPI
+
+
+class PromptWorkflowManager:
+    """Coordinate prompt-level repository actions against git and Gitea."""
+
+    def __init__(self, db):
+        self.db_manager = DatabaseManager(db)
+        self.gitea_api = GiteaAPI(
+            token=settings.GITEA_TOKEN,
+            base_url=settings.GITEA_URL,
+            owner=settings.GITEA_OWNER,
+            repo=settings.GITEA_REPO or '',
+        )
+
+    async def undo_prompt(self, project_id: str, prompt_id: int) -> dict:
+        """Revert the commit associated with a prompt and push the revert to the PR branch."""
+        history = self.db_manager.get_project_by_id(project_id)
+        if history is None:
+            return {'status': 'error', 'message': 'Project not found'}
+
+        correlations = self.db_manager.get_prompt_change_correlations(project_id=project_id, limit=500)
+        correlation = next((item for item in correlations if item.get('prompt_id') == prompt_id), None)
+        if correlation is None:
+            return {'status': 'error', 'message': 'Prompt not found for project'}
+        if correlation.get('revert'):
+            return {'status': 'ignored', 'message': 'Prompt has already been reverted', 'revert': correlation['revert']}
+
+        original_commit = next(
+            (commit for commit in correlation.get('commits', []) if commit.get('remote_status') != 'reverted' and commit.get('commit_hash')),
+            None,
+        )
+        if original_commit is None:
+            return {'status': 'error', 'message': 'No reversible commit was recorded for this prompt'}
+
+        branch = original_commit.get('branch') or f'ai/{project_id}'
+        project_root = settings.projects_root / project_id
+        git_manager = GitManager(project_id, project_dir=str(project_root))
+        if not git_manager.has_repo():
+            return {'status': 'error', 'message': 'Local project repository is not available for undo'}
+
+        try:
+            git_manager.checkout_branch(branch)
+            previous_head = git_manager.current_head_or_none()
+            revert_commit_hash = git_manager.revert_commit(original_commit['commit_hash'])
+        except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+            return {'status': 'error', 'message': f'Unable to revert prompt commit: {exc}'}
+
+        repository = self.db_manager.get_project_audit_data(project_id).get('repository') or {}
+        commit_url = None
+        compare_url = None
+        if (
+            repository.get('mode') == 'project'
+            and repository.get('status') in {'created', 'exists', 'ready'}
+            and settings.gitea_token
+            and repository.get('owner')
+            and repository.get('name')
+        ):
+            try:
+                user_info = await self.gitea_api.get_current_user()
+                username = user_info.get('login') if isinstance(user_info, dict) else None
+                if username and not user_info.get('error'):
+                    remote_url = repository.get('clone_url') or self.gitea_api.build_repo_git_url(repository.get('owner'), repository.get('name'))
+                    if remote_url:
+                        git_manager.push_with_credentials(
+                            remote_url=remote_url,
+                            username=username,
+                            password=settings.gitea_token,
+                            branch=branch,
+                        )
+                        commit_url = self.gitea_api.build_commit_url(revert_commit_hash, repository.get('owner'), repository.get('name'))
+                        if previous_head:
+                            compare_url = self.gitea_api.build_compare_url(previous_head, revert_commit_hash, repository.get('owner'), repository.get('name'))
+            except (RuntimeError, subprocess.CalledProcessError, FileNotFoundError):
+                pass
+
+        self.db_manager.log_commit(
+            project_id=project_id,
+            commit_message=f'Revert prompt {prompt_id}',
+            actor='dashboard',
+            actor_type='user',
+            history_id=history.id,
+            prompt_id=prompt_id,
+            commit_hash=revert_commit_hash,
+            changed_files=original_commit.get('changed_files', []),
+            branch=branch,
+            commit_url=commit_url,
+            compare_url=compare_url,
+            remote_status='reverted',
+        )
+        self.db_manager.log_prompt_revert(
+            project_id=project_id,
+            prompt_id=prompt_id,
+            reverted_commit_hash=original_commit['commit_hash'],
+            revert_commit_hash=revert_commit_hash,
+            actor='dashboard',
+            commit_url=commit_url,
+        )
+        self.db_manager.log_system_event(
+            component='git',
+            level='INFO',
+            message=f'Reverted prompt {prompt_id} for project {project_id}',
+        )
+        return {
+            'status': 'success',
+            'project_id': project_id,
+            'prompt_id': prompt_id,
+            'reverted_commit_hash': original_commit['commit_hash'],
+            'revert_commit_hash': revert_commit_hash,
+            'commit_url': commit_url,
+            'compare_url': compare_url,
+        }

ai_software_factory/agents/request_interpreter.py

@@ -0,0 +1,385 @@
+"""Interpret free-form software requests into structured generation input."""
+
+from __future__ import annotations
+
+import json
+import re
+
+try:
+    from ..config import settings
+    from .gitea import GiteaAPI
+    from .llm_service import LLMServiceClient
+except ImportError:
+    from config import settings
+    from agents.gitea import GiteaAPI
+    from agents.llm_service import LLMServiceClient
+
+
+class RequestInterpreter:
+    """Use Ollama to turn free-form text into a structured software request."""
+
+    REQUEST_PREFIX_WORDS = {
+        'a', 'an', 'app', 'application', 'build', 'create', 'dashboard', 'develop', 'design', 'for', 'generate',
+        'internal', 'make', 'me', 'modern', 'need', 'new', 'our', 'platform', 'please', 'project', 'service',
+        'simple', 'site', 'start', 'system', 'the', 'tool', 'us', 'want', 'web', 'website', 'with',
+    }
+
+    REPO_NOISE_WORDS = REQUEST_PREFIX_WORDS | {'and', 'from', 'into', 'on', 'that', 'this', 'to'}
+    GENERIC_PROJECT_NAME_WORDS = {
+        'app', 'application', 'harness', 'platform', 'project', 'purpose', 'service', 'solution', 'suite', 'system', 'test', 'tool',
+    }
+
+    def __init__(self, ollama_url: str | None = None, model: str | None = None):
+        self.ollama_url = (ollama_url or settings.ollama_url).rstrip('/')
+        self.model = model or settings.OLLAMA_MODEL
+        self.llm_client = LLMServiceClient(ollama_url=self.ollama_url, model=self.model)
+        self.gitea_api = None
+        if settings.gitea_url and settings.gitea_token:
+            self.gitea_api = GiteaAPI(
+                token=settings.GITEA_TOKEN,
+                base_url=settings.GITEA_URL,
+                owner=settings.GITEA_OWNER,
+                repo=settings.GITEA_REPO or '',
+            )
+
+    async def interpret(self, prompt_text: str, context: dict | None = None) -> dict:
+        """Interpret free-form text into the request shape expected by the orchestrator."""
+        interpreted, _trace = await self.interpret_with_trace(prompt_text, context=context)
+        return interpreted
+
+    async def interpret_with_trace(self, prompt_text: str, context: dict | None = None) -> tuple[dict, dict]:
+        """Interpret free-form text into the request shape expected by the orchestrator."""
+        normalized = prompt_text.strip()
+        if not normalized:
+            raise ValueError('Prompt text cannot be empty')
+
+        compact_context = self._build_compact_context(context or {})
+
+        system_prompt = (
+            'You route Telegram software prompts. '
+            'Decide whether the prompt starts a new project or continues an existing tracked project. '
+            'When continuing, identify the best matching project_id from the provided context and the issue number if one is mentioned or implied by recent chat history. '
+            'Return only JSON with keys request and routing. '
+            'request must contain name, description, features, tech_stack. '
+            'routing must contain intent, project_id, project_name, issue_number, confidence, and reasoning_summary. '
+            'Use the provided project catalog and recent chat history. '
+            'If the user says things like also, continue, work on this, that issue, or follow-up wording, prefer continuation of the most relevant recent project. '
+            'If the user explicitly asks for a new project, set intent to new_project.'
+        )
+        user_prompt = normalized
+        if compact_context:
+            user_prompt = (
+                f"Conversation context:\n{json.dumps(compact_context, indent=2)}\n\n"
+                f"User prompt:\n{normalized}"
+            )
+
+        content, trace = await self.llm_client.chat_with_trace(
+            stage='request_interpretation',
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            tool_context_input={
+                'projects': compact_context.get('projects', []),
+                'open_issues': [
+                    issue
+                    for project in compact_context.get('projects', [])
+                    for issue in project.get('open_issues', [])
+                ],
+                'recent_chat_history': compact_context.get('recent_chat_history', []),
+            },
+            expect_json=True,
+        )
+        if not content:
+            detail = self.llm_client.extract_error_message(trace)
+            if detail:
+                raise RuntimeError(f'LLM request interpretation failed: {detail}')
+            raise RuntimeError('LLM request interpretation did not return a usable response.')
+
+        try:
+            parsed = json.loads(content)
+        except Exception as exc:
+            raise RuntimeError('LLM request interpretation did not return valid JSON.') from exc
+
+        interpreted = self._normalize_interpreted_request(parsed)
+        routing = self._normalize_routing(parsed.get('routing'), interpreted, compact_context)
+        if routing.get('intent') == 'continue_project' and routing.get('project_name'):
+            interpreted['name'] = routing['project_name']
+        naming_trace = None
+        if routing.get('intent') == 'new_project':
+            interpreted, routing, naming_trace = await self._refine_new_project_identity(
+                prompt_text=normalized,
+                interpreted=interpreted,
+                routing=routing,
+                context=compact_context,
+            )
+        trace['routing'] = routing
+        trace['context_excerpt'] = compact_context
+        if naming_trace is not None:
+            trace['project_naming'] = naming_trace
+        return interpreted, trace
+
+    async def _refine_new_project_identity(
+        self,
+        *,
+        prompt_text: str,
+        interpreted: dict,
+        routing: dict,
+        context: dict,
+    ) -> tuple[dict, dict, dict | None]:
+        """Refine project and repository naming for genuinely new work."""
+        constraints = await self._collect_project_identity_constraints(context)
+        user_prompt = (
+            f"Original user prompt:\n{prompt_text}\n\n"
+            f"Draft structured request:\n{json.dumps(interpreted, indent=2)}\n\n"
+            f"Tracked project names to avoid reusing unless the user clearly wants them:\n{json.dumps(sorted(constraints['project_names']))}\n\n"
+            f"Repository slugs already reserved in tracked projects or Gitea:\n{json.dumps(sorted(constraints['repo_names']))}\n\n"
+            "Suggest the best project display name and repository slug for this new project."
+        )
+        content, trace = await self.llm_client.chat_with_trace(
+            stage='project_naming',
+            system_prompt=settings.llm_project_naming_system_prompt,
+            user_prompt=user_prompt,
+            tool_context_input={
+                'projects': context.get('projects', []),
+            },
+            expect_json=True,
+        )
+        if not content:
+            detail = self.llm_client.extract_error_message(trace)
+            if detail:
+                raise RuntimeError(f'LLM project naming failed: {detail}')
+            raise RuntimeError('LLM project naming did not return a usable response.')
+
+        try:
+            parsed = json.loads(content)
+        except Exception as exc:
+            raise RuntimeError('LLM project naming did not return valid JSON.') from exc
+
+        project_name, repo_name = self._normalize_project_identity(parsed)
+        repo_name = self._ensure_unique_repo_name(repo_name, constraints['repo_names'])
+        interpreted['name'] = project_name
+        routing['project_name'] = project_name
+        routing['repo_name'] = repo_name
+        return interpreted, routing, trace
+
+    async def _collect_project_identity_constraints(self, context: dict) -> dict[str, set[str]]:
+        """Collect reserved project names and repository slugs from tracked state and Gitea."""
+        project_names: set[str] = set()
+        repo_names: set[str] = set()
+        for project in context.get('projects', []):
+            if project.get('name'):
+                project_names.add(str(project.get('name')).strip())
+            repository = project.get('repository') or {}
+            if repository.get('name'):
+                repo_names.add(str(repository.get('name')).strip())
+        repo_names.update(await self._load_remote_repo_names())
+        return {
+            'project_names': project_names,
+            'repo_names': repo_names,
+        }
+
+    async def _load_remote_repo_names(self) -> set[str]:
+        """Load current Gitea repository names when live credentials are available."""
+        if settings.gitea_repo:
+            return {settings.gitea_repo}
+        if self.gitea_api is None or not settings.gitea_owner:
+            return set()
+        repos = await self.gitea_api.list_repositories(owner=settings.gitea_owner)
+        if not isinstance(repos, list):
+            return set()
+        return {str(repo.get('name')).strip() for repo in repos if repo.get('name')}
+
+    def _normalize_interpreted_request(self, interpreted: dict) -> dict:
+        """Normalize LLM output into the required request shape."""
+        request_payload = interpreted.get('request') if isinstance(interpreted.get('request'), dict) else interpreted
+        if not isinstance(request_payload, dict):
+            raise RuntimeError('LLM request interpretation did not include a request object.')
+        name = str(request_payload.get('name') or '').strip()
+        description = str(request_payload.get('description') or '').strip()
+        if not name:
+            raise RuntimeError('LLM request interpretation did not provide a project name.')
+        if not description:
+            raise RuntimeError('LLM request interpretation did not provide a project description.')
+        features = self._normalize_list(request_payload.get('features'))
+        tech_stack = self._normalize_list(request_payload.get('tech_stack'))
+        return {
+            'name': name[:255],
+            'description': description[:255],
+            'features': features,
+            'tech_stack': tech_stack,
+        }
+
+    def _build_compact_context(self, context: dict) -> dict:
+        """Reduce interpreter context to the fields that help routing."""
+        projects = []
+        for project in context.get('projects', [])[:10]:
+            issues = []
+            for issue in project.get('open_issues', [])[:5]:
+                issues.append({'number': issue.get('number'), 'title': issue.get('title'), 'state': issue.get('state')})
+            projects.append(
+                {
+                    'project_id': project.get('project_id'),
+                    'name': project.get('name'),
+                    'description': project.get('description'),
+                    'repository': project.get('repository'),
+                    'open_pull_request': bool(project.get('open_pull_request')),
+                    'open_issues': issues,
+                }
+            )
+        return {
+            'chat_id': context.get('chat_id'),
+            'recent_chat_history': context.get('recent_chat_history', [])[:8],
+            'projects': projects,
+        }
+
+    def _normalize_routing(self, routing: dict | None, interpreted: dict, context: dict) -> dict:
+        """Normalize routing metadata returned by the LLM."""
+        routing = routing or {}
+        intent = str(routing.get('intent') or '').strip()
+        if intent not in {'new_project', 'continue_project'}:
+            raise RuntimeError('LLM request interpretation did not provide a valid routing intent.')
+        project_id = routing.get('project_id')
+        project_name = routing.get('project_name')
+        issue_number = routing.get('issue_number')
+        if issue_number in ('', None):
+            issue_number = None
+        elif isinstance(issue_number, str) and issue_number.isdigit():
+            issue_number = int(issue_number)
+        matched_project = None
+        if intent == 'continue_project':
+            for project in context.get('projects', []):
+                if project_id and project.get('project_id') == project_id:
+                    matched_project = project
+                    break
+                if project_name and project.get('name') == project_name:
+                    matched_project = project
+                    break
+        elif project_id:
+            matched_project = next(
+                (project for project in context.get('projects', []) if project.get('project_id') == project_id),
+                None,
+            )
+        if intent == 'continue_project' and matched_project is None:
+            raise RuntimeError('LLM selected continue_project without identifying a tracked project from prompt history.')
+        if intent == 'new_project' and matched_project is not None:
+            raise RuntimeError('LLM selected new_project while also pointing at an existing tracked project.')
+        normalized = {
+            'intent': intent,
+            'project_id': matched_project.get('project_id') if matched_project else project_id,
+            'project_name': matched_project.get('name') if matched_project else (project_name or interpreted.get('name')),
+            'repo_name': str(routing.get('repo_name') or '').strip() or None if intent == 'new_project' else None,
+            'issue_number': issue_number,
+            'confidence': routing.get('confidence') or 'medium',
+            'reasoning_summary': routing.get('reasoning_summary') or '',
+        }
+        return normalized
+
+    def _normalize_list(self, value) -> list[str]:
+        if isinstance(value, list):
+            return [str(item).strip() for item in value if str(item).strip()]
+        if isinstance(value, str) and value.strip():
+            return [item.strip() for item in value.split(',') if item.strip()]
+        return []
+
+    def _humanize_name(self, raw_name: str) -> str:
+        """Normalize a candidate project name into a readable title."""
+        cleaned = re.sub(r'[^A-Za-z0-9\s-]+', ' ', raw_name).strip(' -')
+        cleaned = re.sub(r'\s+', ' ', cleaned)
+        cleaned = self._trim_request_prefix(cleaned)
+        special_upper = {'api', 'crm', 'erp', 'cms', 'hr', 'it', 'ui', 'qa'}
+        words = []
+        for word in cleaned.split()[:6]:
+            lowered = word.lower()
+            words.append(lowered.upper() if lowered in special_upper else lowered.capitalize())
+        return ' '.join(words) or 'Generated Project'
+
+    def _trim_request_prefix(self, candidate: str) -> str:
+        """Remove leading request phrasing from model-produced names and slugs."""
+        tokens = [token for token in re.split(r'[-\s]+', candidate or '') if token]
+        while tokens and tokens[0].lower() in self.REQUEST_PREFIX_WORDS:
+            tokens.pop(0)
+        trimmed = ' '.join(tokens).strip()
+        return trimmed or candidate.strip()
+
+    def _derive_repo_name(self, project_name: str) -> str:
+        """Derive a repository slug from a human-readable project name."""
+        preferred_name = self._trim_request_prefix((project_name or 'project').strip())
+        preferred = preferred_name.lower().replace(' ', '-')
+        sanitized = ''.join(ch if ch.isalnum() or ch in {'-', '_'} else '-' for ch in preferred)
+        while '--' in sanitized:
+            sanitized = sanitized.replace('--', '-')
+        return sanitized.strip('-') or 'project'
+
+    def _should_use_repo_name_candidate(self, candidate: str, project_name: str) -> bool:
+        """Return whether a model-proposed repo slug is concise enough to trust directly."""
+        cleaned = self._trim_request_prefix(re.sub(r'[^A-Za-z0-9\s_-]+', ' ', candidate or '').strip())
+        if not cleaned:
+            return False
+        candidate_tokens = [token.lower() for token in re.split(r'[-\s_]+', cleaned) if token]
+        if not candidate_tokens:
+            return False
+        if len(candidate_tokens) > 6:
+            return False
+        noise_count = sum(1 for token in candidate_tokens if token in self.REPO_NOISE_WORDS)
+        if noise_count >= 2:
+            return False
+        if len('-'.join(candidate_tokens)) > 40:
+            return False
+        project_tokens = {
+            token.lower()
+            for token in re.split(r'[-\s_]+', project_name or '')
+            if token and token.lower() not in self.REPO_NOISE_WORDS
+        }
+        if project_tokens:
+            overlap = sum(1 for token in candidate_tokens if token in project_tokens)
+            if overlap == 0:
+                return False
+        return True
+
+    def _should_use_project_name_candidate(self, candidate: str, fallback_name: str) -> bool:
+        """Return whether a model-proposed project title is concrete enough to trust."""
+        cleaned = self._trim_request_prefix(re.sub(r'[^A-Za-z0-9\s-]+', ' ', candidate or '').strip())
+        if not cleaned:
+            return False
+        candidate_tokens = [token.lower() for token in re.split(r'[-\s]+', cleaned) if token]
+        if not candidate_tokens:
+            return False
+        if len(candidate_tokens) == 1 and candidate_tokens[0] in self.GENERIC_PROJECT_NAME_WORDS:
+            return False
+        if all(token in self.GENERIC_PROJECT_NAME_WORDS for token in candidate_tokens):
+            return False
+        fallback_tokens = {
+            token.lower() for token in re.split(r'[-\s]+', fallback_name or '') if token and token.lower() not in self.REPO_NOISE_WORDS
+        }
+        if fallback_tokens and len(candidate_tokens) <= 2:
+            overlap = sum(1 for token in candidate_tokens if token in fallback_tokens)
+            if overlap == 0 and any(token in self.GENERIC_PROJECT_NAME_WORDS for token in candidate_tokens):
+                return False
+        return True
+
+    def _ensure_unique_repo_name(self, repo_name: str, reserved_names: set[str]) -> str:
+        """Choose a repository slug that does not collide with tracked or remote repositories."""
+        base_name = self._derive_repo_name(repo_name)
+        if base_name not in reserved_names:
+            return base_name
+        suffix = 2
+        while f'{base_name}-{suffix}' in reserved_names:
+            suffix += 1
+        return f'{base_name}-{suffix}'
+
+    def _normalize_project_identity(self, payload: dict) -> tuple[str, str]:
+        """Validate model-proposed project and repository naming."""
+        project_candidate = str(payload.get('project_name') or payload.get('name') or '').strip()
+        repo_candidate = str(payload.get('repo_name') or '').strip()
+        if not project_candidate:
+            raise RuntimeError('LLM project naming did not provide a project name.')
+        if not repo_candidate:
+            raise RuntimeError('LLM project naming did not provide a repository slug.')
+        if not self._should_use_project_name_candidate(project_candidate, project_candidate):
+            raise RuntimeError('LLM project naming returned an unusable project name.')
+        if not self._should_use_repo_name_candidate(repo_candidate, project_candidate):
+            raise RuntimeError('LLM project naming returned an unusable repository slug.')
+        return self._humanize_name(project_candidate), self._derive_repo_name(repo_candidate)
+
+    def _extract_issue_number(self, prompt_text: str) -> int | None:
+        match = re.search(r'(?:#|issue\s+)(\d+)', prompt_text, flags=re.IGNORECASE)
+        return int(match.group(1)) if match else None

ai_software_factory/agents/telegram.py

@@ -0,0 +1,202 @@
+"""Telegram bot integration for n8n webhook."""
+
+import asyncio
+from typing import Optional
+
+
+class TelegramHandler:
+    """Handles Telegram messages via n8n webhook."""
+    
+    def __init__(self, webhook_url: str):
+        self.webhook_url = webhook_url
+        self.api_url = "https://api.telegram.org/bot"
+
+    def build_prompt_guide_message(self, backend_url: str | None = None) -> str:
+        """Build a Telegram message explaining the expected prompt format."""
+        lines = [
+            "AI Software Factory is listening in this chat.",
+            "",
+            "You can send free-form software requests in normal language.",
+            "",
+            "Example:",
+            "Build an internal inventory portal for our warehouse team.",
+            "It should support role-based login, stock dashboards, and purchase orders.",
+            "Prefer FastAPI, PostgreSQL, and a simple web UI.",
+            "",
+            "The backend will interpret the request and turn it into a structured project plan.",
+        ]
+        if backend_url:
+            lines.extend(["", f"Backend target: {backend_url}"])
+        return "\n".join(lines)
+
+    async def send_message(self, bot_token: str, chat_id: str | int, text: str) -> dict:
+        """Send a direct Telegram message using the configured bot."""
+        if not bot_token:
+            return {"status": "error", "message": "Telegram bot token is not configured"}
+        if chat_id in (None, ""):
+            return {"status": "error", "message": "Telegram chat id is not configured"}
+
+        api_endpoint = f"{self.api_url}{bot_token}/sendMessage"
+
+        try:
+            import aiohttp
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    api_endpoint,
+                    json={
+                        "chat_id": str(chat_id),
+                        "text": text,
+                    },
+                ) as resp:
+                    payload = await resp.json()
+                    if 200 <= resp.status < 300 and payload.get("ok"):
+                        return {
+                            "status": "success",
+                            "message": "Telegram prompt guide sent successfully",
+                            "payload": payload,
+                        }
+                    description = payload.get("description") or payload.get("message") or str(payload)
+                    return {
+                        "status": "error",
+                        "message": f"Telegram API returned {resp.status}: {description}",
+                        "payload": payload,
+                    }
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+    
+    async def handle_message(self, message_data: dict) -> dict:
+        """Handle incoming Telegram message."""
+        text = message_data.get("text", "")
+        chat_id = message_data.get("chat", {}).get("id", "")
+        
+        # Extract software request from message
+        request = self._parse_request(text)
+        
+        if request:
+            # Forward to backend API
+            async def fetch_software():
+                try:
+                    import aiohttp
+                    async with aiohttp.ClientSession() as session:
+                        async with session.post(
+                            "http://localhost:8000/generate",
+                            json=request
+                        ) as resp:
+                            return await resp.json()
+                except Exception as e:
+                    return {"error": str(e)}
+            
+            result = await fetch_software()
+            return {
+                "status": "success",
+                "data": result,
+                "response": self._format_response(result)
+            }
+        else:
+            return {
+                "status": "error",
+                "message": "Could not parse software request"
+            }
+    
+    def _parse_request(self, text: str) -> Optional[dict]:
+        """Parse software request from user message."""
+        # Simple parser - in production, use LLM to extract
+        request = {
+            "name": None,
+            "description": None,
+            "features": []
+        }
+        
+        lines = text.split("\n")
+        
+        # Parse name
+        name_idx = -1
+        for i, line in enumerate(lines):
+            line_stripped = line.strip()
+            if line_stripped.lower().startswith("name:"):
+                request["name"] = line_stripped.split(":", 1)[1].strip()
+                name_idx = i
+                break
+        
+        if not request["name"]:
+            return None
+        
+        # Parse description (everything after name until features section)
+        # First, find where features section starts
+        features_idx = -1
+        for i in range(name_idx + 1, len(lines)):
+            line_stripped = lines[i].strip()
+            if line_stripped.lower().startswith("features:"):
+                features_idx = i
+                break
+        
+        if features_idx > name_idx:
+            # Description is between name and features
+            request["description"] = "\n".join(lines[name_idx + 1:features_idx]).strip()
+        else:
+            # Description is everything after name
+            request["description"] = "\n".join(lines[name_idx + 1:]).strip()
+        
+        # Strip description prefix if present
+        if request["description"]:
+            request["description"] = request["description"].strip()
+            if request["description"].lower().startswith("description:"):
+                request["description"] = request["description"][len("description:") + 1:].strip()
+        
+        # Parse features
+        if features_idx > 0:
+            features_line = lines[features_idx]
+            # Parse inline features after "Features:"
+            if ":" in features_line:
+                inline_part = features_line.split(":", 1)[1].strip()
+                
+                # Skip if it starts with dash (it's a multiline list marker)
+                if inline_part and not inline_part.startswith("-"):
+                    # Remove any leading dashes or asterisks
+                    if inline_part.startswith("-"):
+                        inline_part = inline_part[1:].strip()
+                    elif inline_part.startswith("*"):
+                        inline_part = inline_part[1:].strip()
+                    
+                    if inline_part:
+                        # Split by comma for inline features
+                        request["features"].extend([f.strip() for f in inline_part.split(",") if f.strip()])
+            
+            # Parse multiline features (dash lines after features:)
+            for line in lines[features_idx + 1:]:
+                line_stripped = line.strip()
+                if not line_stripped:
+                    continue
+                if line_stripped.startswith("-"):
+                    feature_text = line_stripped[1:].strip()
+                    if feature_text:
+                        request["features"].append(feature_text)
+                elif line_stripped.startswith("*"):
+                    feature_text = line_stripped[1:].strip()
+                    if feature_text:
+                        request["features"].append(feature_text)
+                elif ":" in line_stripped:
+                    # Non-feature line with colon
+                    break
+        
+        # MUST have features
+        if not request["features"]:
+            return None
+        
+        return request
+    
+    def _format_response(self, result: dict) -> dict:
+        """Format response for Telegram."""
+        status = result.get("status", "error")
+        message = result.get("message", result.get("detail", ""))
+        progress = result.get("progress", 0)
+        
+        response_data = {
+            "status": status,
+            "message": message,
+            "progress": progress,
+            "project_name": result.get("name", "N/A"),
+            "logs": result.get("logs", [])
+        }
+        
+        return response_data

ai_software_factory/agents/ui_manager.py

@@ -0,0 +1,429 @@
+"""UI manager for web dashboard with audit trail display."""
+
+import html
+import json
+from typing import Optional, List
+
+
+class UIManager:
+    """Manages UI data and updates with audit trail display."""
+    
+    def __init__(self, project_id: str):
+        """Initialize UI manager."""
+        self.project_id = project_id
+        self.ui_data = {
+            "project_id": project_id,
+            "status": "initialized",
+            "progress": 0,
+            "message": "Ready",
+            "snapshots": [],
+            "features": []
+        }
+    
+    def update_status(self, status: str, progress: int, message: str) -> None:
+        """Update UI status."""
+        self.ui_data["status"] = status
+        self.ui_data["progress"] = progress
+        self.ui_data["message"] = message
+    
+    def add_snapshot(self, data: str, created_at: Optional[str] = None) -> None:
+        """Add a snapshot of UI data."""
+        snapshot = {
+            "data": data,
+            "created_at": created_at or self._get_current_timestamp()
+        }
+        self.ui_data.setdefault("snapshots", []).append(snapshot)
+    
+    def add_feature(self, feature: str) -> None:
+        """Add a feature tag."""
+        self.ui_data.setdefault("features", []).append(feature)
+    
+    def _get_current_timestamp(self) -> str:
+        """Get current timestamp in ISO format."""
+        from datetime import datetime
+        return datetime.now().isoformat()
+    
+    def get_ui_data(self) -> dict:
+        """Get current UI data."""
+        return self.ui_data
+    
+    def _escape_html(self, text: str) -> str:
+        """Escape HTML special characters for safe display."""
+        if text is None:
+            return ""
+        return html.escape(str(text), quote=True)
+    
+    def render_dashboard(self, audit_trail: Optional[List[dict]] = None, 
+                         actions: Optional[List[dict]] = None, 
+                         logs: Optional[List[dict]] = None) -> str:
+        """Render dashboard HTML with audit trail and history display."""
+        
+        # Format logs for display
+        logs_html = ""
+        if logs:
+            for log in logs:
+                level = log.get("level", "INFO")
+                message = self._escape_html(log.get("message", ""))
+                timestamp = self._escape_html(log.get("timestamp", ""))
+                
+                if level == "ERROR":
+                    level_class = "error"
+                else:
+                    level_class = "info"
+                
+                logs_html += f"""
+                <div class="log-item">
+                    <span class="timestamp">{timestamp}</span>
+                    <span class="log-level {level_class}">[{level}]</span>
+                    <span>{message}</span>
+                </div>"""
+        
+        # Format audit trail for display
+        audit_html = ""
+        if audit_trail:
+            for audit in audit_trail:
+                action = audit.get("action", "")
+                actor = self._escape_html(audit.get("actor", ""))
+                timestamp = self._escape_html(audit.get("timestamp", ""))
+                details = self._escape_html(audit.get("details", ""))
+                metadata = audit.get("metadata", {})
+                action_type = audit.get("action_type", "")
+                
+                # Color classes for action types
+                action_color = action_type.lower() if action_type else "neutral"
+                
+                audit_html += f"""
+                <div class="audit-item">
+                    <div class="audit-header">
+                        <span class="audit-action {action_color}">
+                            {self._escape_html(action)}
+                        </span>
+                        <span class="audit-actor">{actor}</span>
+                        <span class="audit-time">{timestamp}</span>
+                    </div>
+                    <div class="audit-details">{details}</div>
+                    {f'<div class="audit-metadata">{json.dumps(metadata)}</div>' if metadata else ''}
+                </div>
+"""
+        
+        # Format actions for display
+        actions_html = ""
+        if actions:
+            for action in actions:
+                action_type = action.get("action_type", "")
+                description = self._escape_html(action.get("description", ""))
+                actor_name = self._escape_html(action.get("actor_name", ""))
+                actor_type = action.get("actor_type", "")
+                timestamp = self._escape_html(action.get("timestamp", ""))
+                
+                actions_html += f"""
+                <div class="action-item">
+                    <div class="action-type">{self._escape_html(action_type)}</div>
+                    <div class="action-description">{description}</div>
+                    <div class="action-actor">{actor_type}: {actor_name}</div>
+                    <div class="action-time">{timestamp}</div>
+                </div>"""
+        
+        # Format snapshots for display
+        snapshots_html = ""
+        snapshots = self.ui_data.get("snapshots", [])
+        if snapshots:
+            for snapshot in snapshots:
+                data = snapshot.get("data", "")
+                created_at = snapshot.get("created_at", "")
+                snapshots_html += f"""
+                <div class="snapshot-item">
+                    <div class="snapshot-time">{created_at}</div>
+                    <pre class="snapshot-data">{data}</pre>
+                </div>"""
+        
+        # Build features HTML
+        features_html = ""
+        features = self.ui_data.get("features", [])
+        if features:
+            feature_tags = []
+            for feat in features:
+                feature_tags.append(f'<span class="feature-tag">{self._escape_html(feat)}</span>')
+            features_html = f'<div class="features">{"".join(feature_tags)}</div>'
+        
+        # Build project header HTML
+        project_id_escaped = self._escape_html(self.ui_data.get('project_id', 'Project'))
+        status = self.ui_data.get('status', 'initialized')
+        
+        # Determine empty state message
+        empty_state_message = ""
+        if not audit_trail and not actions and not snapshots_html:
+            empty_state_message = 'No audit trail entries available'
+        
+        return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AI Software Factory Dashboard</title>
+    <style>
+        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            min-height: 100vh;
+            padding: 2rem;
+        }}
+        .container {{
+            max-width: 1200px;
+            margin: 0 auto;
+            background: white;
+            border-radius: 16px;
+            padding: 2rem;
+            box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+        }}
+        h1 {{
+            color: #333;
+            margin-bottom: 1.5rem;
+            font-size: 2rem;
+        }}
+        h2 {{
+            color: #444;
+            margin: 2rem 0 1rem;
+            font-size: 1.5rem;
+            border-bottom: 2px solid #667eea;
+            padding-bottom: 0.5rem;
+        }}
+        .project {{
+            background: #f8f9fa;
+            border-radius: 12px;
+            padding: 1.5rem;
+            margin-bottom: 1rem;
+        }}
+        .project-header {{
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 1rem;
+        }}
+        .project-name {{
+            font-size: 1.25rem;
+            font-weight: bold;
+            color: #333;
+        }}
+        .status-badge {{
+            padding: 0.5rem 1rem;
+            border-radius: 20px;
+            font-weight: bold;
+            font-size: 0.85rem;
+        }}
+        .status-badge.running {{ background: #fff3cd; color: #856404; }}
+        .status-badge.completed {{ background: #d4edda; color: #155724; }}
+        .status-badge.error {{ background: #f8d7da; color: #721c24; }}
+        .status-badge.initialized {{ background: #e2e3e5; color: #383d41; }}
+        .progress-bar {{
+            width: 100%;
+            height: 24px;
+            background: #e9ecef;
+            border-radius: 12px;
+            overflow: hidden;
+            margin: 1rem 0;
+        }}
+        .progress-fill {{
+            height: 100%;
+            background: linear-gradient(90deg, #667eea, #764ba2);
+            transition: width 0.5s ease;
+        }}
+        .message {{
+            color: #495057;
+            margin: 0.5rem 0;
+        }}
+        .logs {{
+            background: #f8f9fa;
+            border-radius: 8px;
+            padding: 1rem;
+            max-height: 200px;
+            overflow-y: auto;
+            font-family: monospace;
+            font-size: 0.85rem;
+        }}
+        .log-item {{
+            padding: 0.25rem 0;
+            border-bottom: 1px solid #e9ecef;
+        }}
+        .log-item:last-child {{ border-bottom: none; }}
+        .timestamp {{
+            color: #6c757d;
+            font-size: 0.8rem;
+        }}
+        .log-level {{
+            font-weight: bold;
+            margin-right: 0.5rem;
+        }}
+        .log-level.info {{ color: #28a745; }}
+        .log-level.error {{ color: #dc3545; }}
+        .features {{
+            margin-top: 1rem;
+            display: flex;
+            flex-wrap: wrap;
+            gap: 0.5rem;
+        }}
+        .feature-tag {{
+            background: #e7f3ff;
+            color: #0066cc;
+            padding: 0.25rem 0.75rem;
+            border-radius: 12px;
+            font-size: 0.85rem;
+        }}
+        .audit-section {{
+            background: #f8f9fa;
+            border-radius: 12px;
+            padding: 1.5rem;
+            margin-top: 1rem;
+        }}
+        .audit-item {{
+            background: white;
+            border: 1px solid #dee2e6;
+            border-radius: 8px;
+            padding: 1rem;
+            margin-bottom: 0.5rem;
+        }}
+        .audit-header {{
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 0.5rem;
+            flex-wrap: wrap;
+            gap: 0.5rem;
+        }}
+        .audit-action {{
+            padding: 0.25rem 0.75rem;
+            border-radius: 12px;
+            font-size: 0.85rem;
+            font-weight: bold;
+        }}
+        .audit-action.CREATE {{ background: #d4edda; color: #155724; }}
+        .audit-action.UPDATE {{ background: #cce5ff; color: #004085; }}
+        .audit-action.DELETE {{ background: #f8d7da; color: #721c24; }}
+        .audit-action.PROMPT {{ background: #d1ecf1; color: #0c5460; }}
+        .audit-action.COMMIT {{ background: #fff3cd; color: #856404; }}
+        .audit-action.PR_CREATED {{ background: #d4edda; color: #155724; }}
+        .audit-action.neutral {{ background: #e9ecef; color: #495057; }}
+        .audit-actor {{
+            background: #e9ecef;
+            padding: 0.25rem 0.75rem;
+            border-radius: 12px;
+            font-size: 0.8rem;
+        }}
+        .audit-time {{
+            color: #6c757d;
+            font-size: 0.8rem;
+        }}
+        .audit-details {{
+            color: #495057;
+            font-size: 0.9rem;
+            font-weight: bold;
+            text-transform: uppercase;
+        }}
+        .audit-metadata {{
+            background: #f1f3f5;
+            padding: 0.5rem;
+            border-radius: 4px;
+            font-size: 0.75rem;
+            font-family: monospace;
+            margin-top: 0.5rem;
+            max-height: 100px;
+            overflow-y: auto;
+        }}
+        .action-item {{
+            background: white;
+            border: 1px solid #dee2e6;
+            border-radius: 8px;
+            padding: 1rem;
+            margin-bottom: 0.5rem;
+        }}
+        .action-type {{
+            font-weight: bold;
+            color: #667eea;
+            font-size: 0.9rem;
+        }}
+        .action-description {{
+            color: #495057;
+            margin: 0.5rem 0;
+        }}
+        .action-actor {{
+            color: #6c757d;
+            font-size: 0.8rem;
+        }}
+        .snapshot-section {{
+            background: #f8f9fa;
+            border-radius: 12px;
+            padding: 1.5rem;
+            margin-top: 1rem;
+        }}
+        .snapshot-item {{
+            background: white;
+            border: 1px solid #dee2e6;
+            border-radius: 8px;
+            padding: 1rem;
+            margin-bottom: 0.5rem;
+        }}
+        .snapshot-time {{
+            color: #6c757d;
+            font-size: 0.8rem;
+            margin-bottom: 0.5rem;
+        }}
+        .snapshot-data {{
+            background: #f8f9fa;
+            padding: 0.5rem;
+            border-radius: 4px;
+            font-family: monospace;
+            font-size: 0.75rem;
+            max-height: 200px;
+            overflow-y: auto;
+            white-space: pre-wrap;
+            word-break: break-all;
+        }}
+        .empty-state {{
+            text-align: center;
+            color: #6c757d;
+            padding: 2rem;
+        }}
+        @media (max-width: 768px) {{
+            .container {{
+                padding: 1rem;
+            }}
+            h1 {{
+                font-size: 1.5rem;
+            }}
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>AI Software Factory Dashboard</h1>
+        
+        <div class="project">
+            <div class="project-header">
+                <span class="project-name">{project_id_escaped}</span>
+                <span class="status-badge {status}">
+                    {status.upper()}
+                </span>
+            </div>
+            
+            <div class="progress-bar">
+                <div class="progress-fill" style="width: {self.ui_data.get('progress', 0)}%;"></div>
+            </div>
+            
+            <div class="message">{self._escape_html(self.ui_data.get('message', 'No message'))}</div>
+            
+            {f'<div class="logs" id="logs">{logs_html}</div>' if logs else '<div class="empty-state">No logs available</div>'}
+            
+            {features_html}
+        </div>
+        
+        {f'<div class="audit-section"><h2>Audit Trail</h2>{audit_html}</div>' if audit_html else ''}
+        
+        {f'<div class="action-section"><h2>User Actions</h2>{actions_html}</div>' if actions_html else ''}
+        
+        {f'<div class="snapshot-section"><h2>UI Snapshots</h2>{snapshots_html}</div>' if snapshots_html else ''}
+        
+        {empty_state_message}
+    </div>
+</body>
+</html>"""

ai_software_factory/alembic.ini

@@ -0,0 +1,37 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+path_separator = os
+sqlalchemy.url = sqlite:////tmp/ai_software_factory_test.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers = console
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s

ai_software_factory/alembic/env.py

@@ -0,0 +1,50 @@
+"""Alembic environment for AI Software Factory."""
+
+from __future__ import annotations
+
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+try:
+    from ai_software_factory.models import Base
+except ImportError:
+    from models import Base
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in offline mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(url=url, target_metadata=target_metadata, literal_binds=True, compare_type=True)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in online mode."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

ai_software_factory/alembic/script.py.mako

@@ -0,0 +1,17 @@
+"""${message}"""
+
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+from alembic import op
+import sqlalchemy as sa
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

ai_software_factory/alembic/versions/20260410_01_initial_schema.py

@@ -0,0 +1,164 @@
+"""initial schema
+
+Revision ID: 20260410_01
+Revises: 
+Create Date: 2026-04-10 00:00:00
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "20260410_01"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "agent_actions",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("agent_name", sa.String(length=100), nullable=False),
+        sa.Column("action_type", sa.String(length=100), nullable=False),
+        sa.Column("success", sa.Boolean(), nullable=True),
+        sa.Column("message", sa.String(length=500), nullable=True),
+        sa.Column("timestamp", sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "audit_trail",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("component", sa.String(length=50), nullable=True),
+        sa.Column("log_level", sa.String(length=50), nullable=True),
+        sa.Column("message", sa.String(length=500), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.Column("project_id", sa.String(length=255), nullable=True),
+        sa.Column("action", sa.String(length=100), nullable=True),
+        sa.Column("actor", sa.String(length=100), nullable=True),
+        sa.Column("action_type", sa.String(length=50), nullable=True),
+        sa.Column("details", sa.Text(), nullable=True),
+        sa.Column("metadata_json", sa.JSON(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "project_history",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("project_id", sa.String(length=255), nullable=False),
+        sa.Column("project_name", sa.String(length=255), nullable=True),
+        sa.Column("features", sa.Text(), nullable=True),
+        sa.Column("description", sa.String(length=255), nullable=True),
+        sa.Column("status", sa.String(length=50), nullable=True),
+        sa.Column("progress", sa.Integer(), nullable=True),
+        sa.Column("message", sa.String(length=500), nullable=True),
+        sa.Column("current_step", sa.String(length=255), nullable=True),
+        sa.Column("total_steps", sa.Integer(), nullable=True),
+        sa.Column("current_step_description", sa.String(length=1024), nullable=True),
+        sa.Column("current_step_details", sa.Text(), nullable=True),
+        sa.Column("error_message", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.Column("started_at", sa.DateTime(), nullable=True),
+        sa.Column("updated_at", sa.DateTime(), nullable=True),
+        sa.Column("completed_at", sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "system_logs",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("component", sa.String(length=50), nullable=False),
+        sa.Column("log_level", sa.String(length=50), nullable=True),
+        sa.Column("log_message", sa.String(length=500), nullable=False),
+        sa.Column("user_agent", sa.String(length=255), nullable=True),
+        sa.Column("ip_address", sa.String(length=45), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "project_logs",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("log_level", sa.String(length=50), nullable=True),
+        sa.Column("log_message", sa.String(length=500), nullable=False),
+        sa.Column("timestamp", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "prompt_code_links",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("project_id", sa.String(length=255), nullable=False),
+        sa.Column("prompt_audit_id", sa.Integer(), nullable=False),
+        sa.Column("code_change_audit_id", sa.Integer(), nullable=False),
+        sa.Column("file_path", sa.String(length=500), nullable=True),
+        sa.Column("change_type", sa.String(length=50), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "pull_request_data",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("pr_number", sa.Integer(), nullable=False),
+        sa.Column("pr_title", sa.String(length=500), nullable=False),
+        sa.Column("pr_body", sa.Text(), nullable=True),
+        sa.Column("pr_state", sa.String(length=50), nullable=False),
+        sa.Column("pr_url", sa.String(length=500), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "pull_requests",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("pr_number", sa.Integer(), nullable=False),
+        sa.Column("pr_title", sa.String(length=500), nullable=False),
+        sa.Column("pr_body", sa.Text(), nullable=True),
+        sa.Column("base", sa.String(length=255), nullable=False),
+        sa.Column("user", sa.String(length=255), nullable=False),
+        sa.Column("pr_url", sa.String(length=500), nullable=False),
+        sa.Column("merged", sa.Boolean(), nullable=True),
+        sa.Column("merged_at", sa.DateTime(), nullable=True),
+        sa.Column("pr_state", sa.String(length=50), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "ui_snapshots",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=False),
+        sa.Column("snapshot_data", sa.JSON(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_table(
+        "user_actions",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("history_id", sa.Integer(), nullable=True),
+        sa.Column("user_id", sa.String(length=100), nullable=True),
+        sa.Column("action_type", sa.String(length=100), nullable=True),
+        sa.Column("actor_type", sa.String(length=50), nullable=True),
+        sa.Column("actor_name", sa.String(length=100), nullable=True),
+        sa.Column("action_description", sa.String(length=500), nullable=True),
+        sa.Column("action_data", sa.JSON(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["history_id"], ["project_history.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("user_actions")
+    op.drop_table("ui_snapshots")
+    op.drop_table("pull_requests")
+    op.drop_table("pull_request_data")
+    op.drop_table("prompt_code_links")
+    op.drop_table("project_logs")
+    op.drop_table("system_logs")
+    op.drop_table("project_history")
+    op.drop_table("audit_trail")
+    op.drop_table("agent_actions")

ai_software_factory/config.py

@@ -0,0 +1,660 @@
+"""Configuration settings for AI Software Factory."""
+
+import json
+import os
+from typing import Optional
+from pathlib import Path
+from urllib.parse import urlparse
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _normalize_service_url(value: str, default_scheme: str = "https") -> str:
+    """Normalize service URLs so host-only values still become valid absolute URLs."""
+    normalized = (value or "").strip().rstrip("/")
+    if not normalized:
+        return ""
+    if "://" not in normalized:
+        normalized = f"{default_scheme}://{normalized}"
+    parsed = urlparse(normalized)
+    if not parsed.scheme or not parsed.netloc:
+        return ""
+    return normalized
+
+
+EDITABLE_LLM_PROMPTS: dict[str, dict[str, str]] = {
+    'LLM_GUARDRAIL_PROMPT': {
+        'label': 'Global Guardrails',
+        'category': 'guardrail',
+        'description': 'Applied to every outbound external LLM call.',
+    },
+    'LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT': {
+        'label': 'Request Interpretation Guardrails',
+        'category': 'guardrail',
+        'description': 'Constrains project routing and continuation selection.',
+    },
+    'LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT': {
+        'label': 'Change Summary Guardrails',
+        'category': 'guardrail',
+        'description': 'Constrains factual delivery summaries.',
+    },
+    'LLM_PROJECT_NAMING_GUARDRAIL_PROMPT': {
+        'label': 'Project Naming Guardrails',
+        'category': 'guardrail',
+        'description': 'Constrains project display names and repo slugs.',
+    },
+    'LLM_PROJECT_NAMING_SYSTEM_PROMPT': {
+        'label': 'Project Naming System Prompt',
+        'category': 'system_prompt',
+        'description': 'Guides the dedicated new-project naming stage.',
+    },
+    'LLM_PROJECT_ID_GUARDRAIL_PROMPT': {
+        'label': 'Project ID Guardrails',
+        'category': 'guardrail',
+        'description': 'Constrains stable project id generation.',
+    },
+    'LLM_PROJECT_ID_SYSTEM_PROMPT': {
+        'label': 'Project ID System Prompt',
+        'category': 'system_prompt',
+        'description': 'Guides the dedicated project id naming stage.',
+    },
+}
+
+EDITABLE_RUNTIME_SETTINGS: dict[str, dict[str, str]] = {
+    'HOME_ASSISTANT_BATTERY_ENTITY_ID': {
+        'label': 'Battery Entity ID',
+        'category': 'home_assistant',
+        'description': 'Home Assistant entity used for battery state-of-charge gating.',
+        'value_type': 'string',
+    },
+    'HOME_ASSISTANT_SURPLUS_ENTITY_ID': {
+        'label': 'Surplus Power Entity ID',
+        'category': 'home_assistant',
+        'description': 'Home Assistant entity used for export or surplus power gating.',
+        'value_type': 'string',
+    },
+    'HOME_ASSISTANT_BATTERY_FULL_THRESHOLD': {
+        'label': 'Battery Full Threshold',
+        'category': 'home_assistant',
+        'description': 'Minimum battery percentage required before queued prompts may run.',
+        'value_type': 'float',
+    },
+    'HOME_ASSISTANT_SURPLUS_THRESHOLD_WATTS': {
+        'label': 'Surplus Threshold Watts',
+        'category': 'home_assistant',
+        'description': 'Minimum surplus/export power required before queued prompts may run.',
+        'value_type': 'float',
+    },
+    'PROMPT_QUEUE_ENABLED': {
+        'label': 'Queue Telegram Prompts',
+        'category': 'prompt_queue',
+        'description': 'When enabled, Telegram prompts are queued and gated instead of processed immediately.',
+        'value_type': 'boolean',
+    },
+    'PROMPT_QUEUE_AUTO_PROCESS': {
+        'label': 'Auto Process Queue',
+        'category': 'prompt_queue',
+        'description': 'Let the background worker drain the queue automatically when the gate is open.',
+        'value_type': 'boolean',
+    },
+    'PROMPT_QUEUE_FORCE_PROCESS': {
+        'label': 'Force Queue Processing',
+        'category': 'prompt_queue',
+        'description': 'Bypass the Home Assistant energy gate for queued prompts.',
+        'value_type': 'boolean',
+    },
+    'PROMPT_QUEUE_POLL_INTERVAL_SECONDS': {
+        'label': 'Queue Poll Interval Seconds',
+        'category': 'prompt_queue',
+        'description': 'Polling interval for the background queue worker.',
+        'value_type': 'integer',
+    },
+    'PROMPT_QUEUE_MAX_BATCH_SIZE': {
+        'label': 'Queue Max Batch Size',
+        'category': 'prompt_queue',
+        'description': 'Maximum number of queued prompts processed in one batch.',
+        'value_type': 'integer',
+    },
+}
+
+
+def _get_persisted_llm_prompt_override(env_key: str) -> str | None:
+    """Load one persisted LLM prompt override from the database when available."""
+    if env_key not in EDITABLE_LLM_PROMPTS:
+        return None
+    try:
+        try:
+            from .database import get_db_sync
+            from .agents.database_manager import DatabaseManager
+        except ImportError:
+            from database import get_db_sync
+            from agents.database_manager import DatabaseManager
+
+        db = get_db_sync()
+        if db is None:
+            return None
+        try:
+            return DatabaseManager(db).get_llm_prompt_override(env_key)
+        finally:
+            db.close()
+    except Exception:
+        return None
+
+
+def _resolve_llm_prompt_value(env_key: str, fallback: str) -> str:
+    """Resolve one editable prompt from DB override first, then environment/defaults."""
+    override = _get_persisted_llm_prompt_override(env_key)
+    if override is not None:
+        return override.strip()
+    return (fallback or '').strip()
+
+
+def _get_persisted_runtime_setting_override(key: str):
+    """Load one persisted runtime-setting override from the database when available."""
+    if key not in EDITABLE_RUNTIME_SETTINGS:
+        return None
+    try:
+        try:
+            from .database import get_db_sync
+            from .agents.database_manager import DatabaseManager
+        except ImportError:
+            from database import get_db_sync
+            from agents.database_manager import DatabaseManager
+
+        db = get_db_sync()
+        if db is None:
+            return None
+        try:
+            return DatabaseManager(db).get_runtime_setting_override(key)
+        finally:
+            db.close()
+    except Exception:
+        return None
+
+
+def _coerce_runtime_setting_value(key: str, value, fallback):
+    """Coerce a persisted runtime setting override into the expected scalar type."""
+    value_type = EDITABLE_RUNTIME_SETTINGS.get(key, {}).get('value_type')
+    if value is None:
+        return fallback
+    if value_type == 'boolean':
+        if isinstance(value, bool):
+            return value
+        normalized = str(value).strip().lower()
+        if normalized in {'1', 'true', 'yes', 'on'}:
+            return True
+        if normalized in {'0', 'false', 'no', 'off'}:
+            return False
+        return bool(fallback)
+    if value_type == 'integer':
+        try:
+            return int(value)
+        except Exception:
+            return int(fallback)
+    if value_type == 'float':
+        try:
+            return float(value)
+        except Exception:
+            return float(fallback)
+    return str(value).strip()
+
+
+def _resolve_runtime_setting_value(key: str, fallback):
+    """Resolve one editable runtime setting from DB override first, then environment/defaults."""
+    override = _get_persisted_runtime_setting_override(key)
+    return _coerce_runtime_setting_value(key, override, fallback)
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Server settings
+    HOST: str = "0.0.0.0"
+    PORT: int = 8000
+    LOG_LEVEL: str = "INFO"
+
+    # Ollama settings computed from environment
+    OLLAMA_URL: str = "http://ollama:11434"
+    OLLAMA_MODEL: str = "llama3"
+    LLM_REQUEST_TIMEOUT_SECONDS: int = 240
+    LLM_GUARDRAIL_PROMPT: str = (
+        "You are operating inside AI Software Factory. Follow the requested schema exactly, "
+        "treat provided tool outputs as authoritative, and do not invent repositories, issues, pull requests, or delivery facts."
+    )
+    LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT: str = (
+        "For routing and request interpretation: never select archived projects, prefer tracked project IDs from tool outputs, and only reference issues that are explicit in the prompt or available tool data."
+    )
+    LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT: str = (
+        "For summaries: only describe facts present in the provided context and tool outputs. Never claim a repository, commit, or pull request exists unless it is present in the supplied data."
+    )
+    LLM_PROJECT_NAMING_GUARDRAIL_PROMPT: str = (
+        "For project naming: prefer clear, product-like names and repository slugs that match the user's concrete deliverable. Avoid abstract or instructional words such as purpose, project, system, app, tool, platform, solution, new, create, or test unless the request truly centers on that exact noun. Base the name on the actual artifact or workflow being built, and avoid copying sentence fragments from the prompt. Avoid reusing tracked project identities unless the request is clearly asking for an existing project."
+    )
+    LLM_PROJECT_NAMING_SYSTEM_PROMPT: str = (
+        "You name newly requested software projects. Return only JSON with keys project_name, repo_name, and rationale. Project names should be concise human-readable titles based on the real product, artifact, or workflow being created. Repo names should be lowercase kebab-case slugs derived from that title. Never return generic names like purpose, project, system, app, tool, platform, solution, harness, or test by themselves, and never return a repo_name that is a copied sentence fragment from the prompt. Prefer 2 to 4 specific words when possible."
+    )
+    LLM_PROJECT_ID_GUARDRAIL_PROMPT: str = (
+        "For project ids: produce short stable slugs for newly created projects. Avoid collisions with known project ids and keep ids lowercase with hyphens."
+    )
+    LLM_PROJECT_ID_SYSTEM_PROMPT: str = (
+        "You derive stable project ids for new projects. Return only JSON with keys project_id and rationale. project_id must be a short lowercase kebab-case slug without spaces."
+    )
+    LLM_TOOL_ALLOWLIST: str = "gitea_project_catalog,gitea_project_state,gitea_project_issues,gitea_pull_requests"
+    LLM_TOOL_CONTEXT_LIMIT: int = 5
+    LLM_LIVE_TOOL_ALLOWLIST: str = "gitea_lookup_issue,gitea_lookup_pull_request"
+    LLM_LIVE_TOOL_STAGE_ALLOWLIST: str = "request_interpretation,change_summary"
+    LLM_LIVE_TOOL_STAGE_TOOL_MAP: str = ""
+    LLM_MAX_TOOL_CALL_ROUNDS: int = 1
+
+    # Gitea settings
+    GITEA_URL: str = "https://gitea.yourserver.com"
+    GITEA_TOKEN: str = ""
+    GITEA_OWNER: str = "ai-software-factory"
+    GITEA_REPO: str = ""
+
+    # n8n settings
+    N8N_WEBHOOK_URL: str = ""
+    N8N_API_URL: str = ""
+    N8N_API_KEY: str = ""
+    N8N_TELEGRAM_CREDENTIAL_NAME: str = "AI Software Factory Telegram"
+    N8N_USER: str = ""
+    N8N_PASSWORD: str = ""
+
+    # Runtime integration settings
+    BACKEND_PUBLIC_URL: str = "http://localhost:8000"
+    PROJECTS_ROOT: str = ""
+
+    # Telegram settings
+    TELEGRAM_BOT_TOKEN: str = ""
+    TELEGRAM_CHAT_ID: str = ""
+
+    # Home Assistant and prompt queue settings
+    HOME_ASSISTANT_URL: str = ""
+    HOME_ASSISTANT_TOKEN: str = ""
+    HOME_ASSISTANT_BATTERY_ENTITY_ID: str = ""
+    HOME_ASSISTANT_SURPLUS_ENTITY_ID: str = ""
+    HOME_ASSISTANT_BATTERY_FULL_THRESHOLD: float = 95.0
+    HOME_ASSISTANT_SURPLUS_THRESHOLD_WATTS: float = 100.0
+    PROMPT_QUEUE_ENABLED: bool = False
+    PROMPT_QUEUE_AUTO_PROCESS: bool = True
+    PROMPT_QUEUE_FORCE_PROCESS: bool = False
+    PROMPT_QUEUE_POLL_INTERVAL_SECONDS: int = 60
+    PROMPT_QUEUE_MAX_BATCH_SIZE: int = 1
+
+    # PostgreSQL settings
+    POSTGRES_HOST: str = "localhost"
+    POSTGRES_PORT: int = 5432
+    POSTGRES_USER: str = "postgres"
+    POSTGRES_PASSWORD: str = ""
+    POSTGRES_DB: str = "ai_software_factory"
+    POSTGRES_TEST_DB: str = "ai_software_factory_test"
+    POSTGRES_URL: Optional[str] = None  # Optional direct PostgreSQL connection URL
+
+    # SQLite settings for testing
+    USE_SQLITE: bool = True  # Enable SQLite by default for testing
+    SQLITE_DB_PATH: str = "sqlite.db"
+
+    # Database connection pool settings (only for PostgreSQL)
+    DB_POOL_SIZE: int = 10
+    DB_MAX_OVERFLOW: int = 20
+    DB_POOL_RECYCLE: int = 3600
+    DB_POOL_TIMEOUT: int = 30
+
+    @property
+    def postgres_url(self) -> str:
+        """Get PostgreSQL URL with trimmed whitespace."""
+        return (self.POSTGRES_URL or "").strip()
+
+    @property
+    def postgres_env_configured(self) -> bool:
+        """Whether PostgreSQL was explicitly configured via environment variables."""
+        if self.postgres_url:
+            return True
+        postgres_env_keys = (
+            "POSTGRES_HOST",
+            "POSTGRES_PORT",
+            "POSTGRES_USER",
+            "POSTGRES_PASSWORD",
+            "POSTGRES_DB",
+        )
+        return any(bool(os.environ.get(key, "").strip()) for key in postgres_env_keys)
+
+    @property
+    def use_sqlite(self) -> bool:
+        """Whether SQLite should be used as the active database backend."""
+        if not self.USE_SQLITE:
+            return False
+        return not self.postgres_env_configured
+
+    @property
+    def pool(self) -> dict:
+        """Get database pool configuration."""
+        return {
+            "pool_size": self.DB_POOL_SIZE,
+            "max_overflow": self.DB_MAX_OVERFLOW,
+            "pool_recycle": self.DB_POOL_RECYCLE,
+            "pool_timeout": self.DB_POOL_TIMEOUT
+        }
+
+    @property
+    def database_url(self) -> str:
+        """Get database connection URL."""
+        if self.use_sqlite:
+            return f"sqlite:///{self.SQLITE_DB_PATH}"
+        if self.postgres_url:
+            return self.postgres_url
+        return (
+            f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+    @property
+    def test_database_url(self) -> str:
+        """Get test database connection URL."""
+        if self.use_sqlite:
+            return f"sqlite:///{self.SQLITE_DB_PATH}"
+        if self.postgres_url:
+            return self.postgres_url
+        return (
+            f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_TEST_DB}"
+        )
+
+    @property
+    def ollama_url(self) -> str:
+        """Get Ollama URL with trimmed whitespace."""
+        return self.OLLAMA_URL.strip()
+
+    @property
+    def llm_guardrail_prompt(self) -> str:
+        """Get the global guardrail prompt used for all external LLM calls."""
+        return _resolve_llm_prompt_value('LLM_GUARDRAIL_PROMPT', self.LLM_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_request_interpreter_guardrail_prompt(self) -> str:
+        """Get the request-interpretation specific guardrail prompt."""
+        return _resolve_llm_prompt_value('LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT', self.LLM_REQUEST_INTERPRETER_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_change_summary_guardrail_prompt(self) -> str:
+        """Get the change-summary specific guardrail prompt."""
+        return _resolve_llm_prompt_value('LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT', self.LLM_CHANGE_SUMMARY_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_project_naming_guardrail_prompt(self) -> str:
+        """Get the project-naming specific guardrail prompt."""
+        return _resolve_llm_prompt_value('LLM_PROJECT_NAMING_GUARDRAIL_PROMPT', self.LLM_PROJECT_NAMING_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_project_naming_system_prompt(self) -> str:
+        """Get the project-naming system prompt."""
+        return _resolve_llm_prompt_value('LLM_PROJECT_NAMING_SYSTEM_PROMPT', self.LLM_PROJECT_NAMING_SYSTEM_PROMPT)
+
+    @property
+    def llm_project_id_guardrail_prompt(self) -> str:
+        """Get the project-id naming specific guardrail prompt."""
+        return _resolve_llm_prompt_value('LLM_PROJECT_ID_GUARDRAIL_PROMPT', self.LLM_PROJECT_ID_GUARDRAIL_PROMPT)
+
+    @property
+    def llm_project_id_system_prompt(self) -> str:
+        """Get the project-id naming system prompt."""
+        return _resolve_llm_prompt_value('LLM_PROJECT_ID_SYSTEM_PROMPT', self.LLM_PROJECT_ID_SYSTEM_PROMPT)
+
+    @property
+    def editable_llm_prompts(self) -> list[dict[str, str]]:
+        """Return metadata for all LLM prompts that may be persisted and edited from the UI."""
+        prompts = []
+        for env_key, metadata in EDITABLE_LLM_PROMPTS.items():
+            prompts.append(
+                {
+                    'key': env_key,
+                    'label': metadata['label'],
+                    'category': metadata['category'],
+                    'description': metadata['description'],
+                    'default_value': (getattr(self, env_key, '') or '').strip(),
+                    'value': _resolve_llm_prompt_value(env_key, getattr(self, env_key, '')),
+                }
+            )
+        return prompts
+
+    @property
+    def editable_runtime_settings(self) -> list[dict]:
+        """Return metadata for all DB-editable runtime settings."""
+        items = []
+        for key, metadata in EDITABLE_RUNTIME_SETTINGS.items():
+            default_value = getattr(self, key)
+            value = _resolve_runtime_setting_value(key, default_value)
+            items.append(
+                {
+                    'key': key,
+                    'label': metadata['label'],
+                    'category': metadata['category'],
+                    'description': metadata['description'],
+                    'value_type': metadata['value_type'],
+                    'default_value': default_value,
+                    'value': value,
+                }
+            )
+        return items
+
+    @property
+    def llm_tool_allowlist(self) -> list[str]:
+        """Get the allowed LLM tool names as a normalized list."""
+        return [item.strip() for item in self.LLM_TOOL_ALLOWLIST.split(',') if item.strip()]
+
+    @property
+    def llm_tool_context_limit(self) -> int:
+        """Get the number of items to expose per mediated tool payload."""
+        return max(int(self.LLM_TOOL_CONTEXT_LIMIT), 1)
+
+    @property
+    def llm_live_tool_allowlist(self) -> list[str]:
+        """Get the allowed live tool-call names for model-driven lookup requests."""
+        return [item.strip() for item in self.LLM_LIVE_TOOL_ALLOWLIST.split(',') if item.strip()]
+
+    @property
+    def llm_live_tool_stage_allowlist(self) -> list[str]:
+        """Get the LLM stages where live tool requests are enabled."""
+        return [item.strip() for item in self.LLM_LIVE_TOOL_STAGE_ALLOWLIST.split(',') if item.strip()]
+
+    @property
+    def llm_live_tool_stage_tool_map(self) -> dict[str, list[str]]:
+        """Get an optional per-stage live tool map that overrides the simple stage allowlist."""
+        raw = (self.LLM_LIVE_TOOL_STAGE_TOOL_MAP or '').strip()
+        if not raw:
+            return {}
+        try:
+            parsed = json.loads(raw)
+        except Exception:
+            return {}
+        if not isinstance(parsed, dict):
+            return {}
+        allowed_tools = set(self.llm_live_tool_allowlist)
+        normalized: dict[str, list[str]] = {}
+        for stage, tools in parsed.items():
+            if not isinstance(stage, str):
+                continue
+            if not isinstance(tools, list):
+                continue
+            normalized[stage.strip()] = [str(tool).strip() for tool in tools if str(tool).strip() in allowed_tools]
+        return normalized
+
+    def llm_live_tools_for_stage(self, stage: str) -> list[str]:
+        """Return live tools enabled for a specific LLM stage."""
+        stage_map = self.llm_live_tool_stage_tool_map
+        if stage_map:
+            return stage_map.get(stage, [])
+        if stage not in set(self.llm_live_tool_stage_allowlist):
+            return []
+        return self.llm_live_tool_allowlist
+
+    @property
+    def llm_max_tool_call_rounds(self) -> int:
+        """Get the maximum number of model-driven live tool-call rounds per LLM request."""
+        return max(int(self.LLM_MAX_TOOL_CALL_ROUNDS), 0)
+
+    @property
+    def gitea_url(self) -> str:
+        """Get Gitea URL with trimmed whitespace."""
+        return _normalize_service_url(self.GITEA_URL)
+
+    @property
+    def gitea_token(self) -> str:
+        """Get Gitea token with trimmed whitespace."""
+        return self.GITEA_TOKEN.strip()
+
+    @property
+    def gitea_owner(self) -> str:
+        """Get Gitea owner/organization with trimmed whitespace."""
+        return self.GITEA_OWNER.strip()
+
+    @property
+    def gitea_repo(self) -> str:
+        """Get the optional fixed Gitea repository name with trimmed whitespace."""
+        return self.GITEA_REPO.strip()
+
+    @property
+    def use_project_repositories(self) -> bool:
+        """Whether the service should create one repository per generated project."""
+        return not bool(self.gitea_repo)
+
+    @property
+    def n8n_webhook_url(self) -> str:
+        """Get n8n webhook URL with trimmed whitespace."""
+        return _normalize_service_url(self.N8N_WEBHOOK_URL, default_scheme="http")
+
+    @property
+    def n8n_api_url(self) -> str:
+        """Get n8n API URL with trimmed whitespace."""
+        return _normalize_service_url(self.N8N_API_URL, default_scheme="http")
+
+    @property
+    def n8n_api_key(self) -> str:
+        """Get n8n API key with trimmed whitespace."""
+        return self.N8N_API_KEY.strip()
+
+    @property
+    def n8n_telegram_credential_name(self) -> str:
+        """Get the preferred n8n Telegram credential name."""
+        return self.N8N_TELEGRAM_CREDENTIAL_NAME.strip() or "AI Software Factory Telegram"
+
+    @property
+    def telegram_bot_token(self) -> str:
+        """Get Telegram bot token with trimmed whitespace."""
+        return self.TELEGRAM_BOT_TOKEN.strip()
+
+    @property
+    def telegram_chat_id(self) -> str:
+        """Get Telegram chat ID with trimmed whitespace."""
+        return self.TELEGRAM_CHAT_ID.strip()
+
+    @property
+    def backend_public_url(self) -> str:
+        """Get backend public URL with trimmed whitespace."""
+        return _normalize_service_url(self.BACKEND_PUBLIC_URL, default_scheme="http")
+
+    @property
+    def home_assistant_url(self) -> str:
+        """Get Home Assistant URL with trimmed whitespace."""
+        return _normalize_service_url(self.HOME_ASSISTANT_URL, default_scheme="http")
+
+    @property
+    def home_assistant_token(self) -> str:
+        """Get Home Assistant token with trimmed whitespace."""
+        return self.HOME_ASSISTANT_TOKEN.strip()
+
+    @property
+    def home_assistant_battery_entity_id(self) -> str:
+        """Get the Home Assistant battery state entity id."""
+        return str(_resolve_runtime_setting_value('HOME_ASSISTANT_BATTERY_ENTITY_ID', self.HOME_ASSISTANT_BATTERY_ENTITY_ID)).strip()
+
+    @property
+    def home_assistant_surplus_entity_id(self) -> str:
+        """Get the Home Assistant surplus power entity id."""
+        return str(_resolve_runtime_setting_value('HOME_ASSISTANT_SURPLUS_ENTITY_ID', self.HOME_ASSISTANT_SURPLUS_ENTITY_ID)).strip()
+
+    @property
+    def home_assistant_battery_full_threshold(self) -> float:
+        """Get the minimum battery SoC percentage for queue processing."""
+        return float(_resolve_runtime_setting_value('HOME_ASSISTANT_BATTERY_FULL_THRESHOLD', self.HOME_ASSISTANT_BATTERY_FULL_THRESHOLD))
+
+    @property
+    def home_assistant_surplus_threshold_watts(self) -> float:
+        """Get the minimum export/surplus power threshold for queue processing."""
+        return float(_resolve_runtime_setting_value('HOME_ASSISTANT_SURPLUS_THRESHOLD_WATTS', self.HOME_ASSISTANT_SURPLUS_THRESHOLD_WATTS))
+
+    @property
+    def prompt_queue_enabled(self) -> bool:
+        """Whether Telegram prompts should be queued instead of processed immediately."""
+        return bool(_resolve_runtime_setting_value('PROMPT_QUEUE_ENABLED', self.PROMPT_QUEUE_ENABLED))
+
+    @property
+    def prompt_queue_auto_process(self) -> bool:
+        """Whether the background worker should automatically process queued prompts."""
+        return bool(_resolve_runtime_setting_value('PROMPT_QUEUE_AUTO_PROCESS', self.PROMPT_QUEUE_AUTO_PROCESS))
+
+    @property
+    def prompt_queue_force_process(self) -> bool:
+        """Whether queued prompts should bypass the Home Assistant energy gate."""
+        return bool(_resolve_runtime_setting_value('PROMPT_QUEUE_FORCE_PROCESS', self.PROMPT_QUEUE_FORCE_PROCESS))
+
+    @property
+    def prompt_queue_poll_interval_seconds(self) -> int:
+        """Get the queue polling interval for background processing."""
+        return max(int(_resolve_runtime_setting_value('PROMPT_QUEUE_POLL_INTERVAL_SECONDS', self.PROMPT_QUEUE_POLL_INTERVAL_SECONDS)), 5)
+
+    @property
+    def prompt_queue_max_batch_size(self) -> int:
+        """Get the maximum number of queued prompts to process in one batch."""
+        return max(int(_resolve_runtime_setting_value('PROMPT_QUEUE_MAX_BATCH_SIZE', self.PROMPT_QUEUE_MAX_BATCH_SIZE)), 1)
+
+    @property
+    def llm_request_timeout_seconds(self) -> int:
+        """Get the outbound provider timeout for one LLM request."""
+        return max(int(_resolve_runtime_setting_value('LLM_REQUEST_TIMEOUT_SECONDS', self.LLM_REQUEST_TIMEOUT_SECONDS)), 1)
+
+    @property
+    def projects_root(self) -> Path:
+        """Get the root directory for generated project artifacts."""
+        if self.PROJECTS_ROOT.strip():
+            return Path(self.PROJECTS_ROOT).expanduser().resolve()
+        return Path(__file__).resolve().parent.parent / "test-project"
+
+    @property
+    def postgres_host(self) -> str:
+        """Get PostgreSQL host."""
+        return self.POSTGRES_HOST.strip()
+
+    @property
+    def postgres_port(self) -> int:
+        """Get PostgreSQL port as integer."""
+        return int(self.POSTGRES_PORT)
+
+    @property
+    def postgres_user(self) -> str:
+        """Get PostgreSQL user."""
+        return self.POSTGRES_USER.strip()
+
+    @property
+    def postgres_password(self) -> str:
+        """Get PostgreSQL password."""
+        return self.POSTGRES_PASSWORD.strip()
+
+    @property
+    def postgres_db(self) -> str:
+        """Get PostgreSQL database name."""
+        return self.POSTGRES_DB.strip()
+
+    @property
+    def postgres_test_db(self) -> str:
+        """Get test PostgreSQL database name."""
+        return self.POSTGRES_TEST_DB.strip()
+
+# Create instance for module-level access
+settings = Settings()

ai_software_factory/dashboard.html

@@ -0,0 +1,322 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AI Software Factory Dashboard</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+            min-height: 100vh;
+            color: #fff;
+            padding: 20px;
+        }
+
+        .dashboard {
+            max-width: 1200px;
+            margin: 0 auto;
+        }
+
+        .header {
+            text-align: center;
+            padding: 30px;
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 15px;
+            margin-bottom: 20px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .header h1 {
+            font-size: 2.5em;
+            margin-bottom: 10px;
+            background: linear-gradient(90deg, #00d4ff, #00ff88);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            background-clip: text;
+        }
+
+        .header p {
+            color: #888;
+            font-size: 1.1em;
+        }
+
+        .stats-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+            gap: 20px;
+            margin-bottom: 20px;
+        }
+
+        .stat-card {
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 15px;
+            padding: 25px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+            text-align: center;
+        }
+
+        .stat-card h3 {
+            font-size: 0.9em;
+            color: #888;
+            margin-bottom: 10px;
+            text-transform: uppercase;
+            letter-spacing: 1px;
+        }
+
+        .stat-card .value {
+            font-size: 2.5em;
+            font-weight: bold;
+            color: #00d4ff;
+        }
+
+        .stat-card.project .value { color: #00ff88; }
+        .stat-card.active .value { color: #ff6b6b; }
+        .stat-card.code .value { color: #ffd93d; }
+
+        .status-panel {
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 15px;
+            padding: 25px;
+            margin-bottom: 20px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .status-panel h2 {
+            font-size: 1.3em;
+            margin-bottom: 15px;
+            color: #00d4ff;
+        }
+
+        .status-bar {
+            height: 20px;
+            background: #2a2a4a;
+            border-radius: 10px;
+            overflow: hidden;
+            margin-bottom: 10px;
+        }
+
+        .status-fill {
+            height: 100%;
+            background: linear-gradient(90deg, #00d4ff, #00ff88);
+            border-radius: 10px;
+            transition: width 0.5s ease;
+        }
+
+        .message {
+            padding: 10px;
+            background: rgba(0, 212, 255, 0.1);
+            border-radius: 8px;
+            border-left: 4px solid #00d4ff;
+        }
+
+        .projects-section {
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 15px;
+            padding: 25px;
+            margin-bottom: 20px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .projects-section h2 {
+            font-size: 1.3em;
+            margin-bottom: 15px;
+            color: #00ff88;
+        }
+
+        .projects-list {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 15px;
+        }
+
+        .project-item {
+            background: rgba(0, 255, 136, 0.1);
+            padding: 15px 20px;
+            border-radius: 10px;
+            border: 1px solid rgba(0, 255, 136, 0.3);
+            font-size: 0.9em;
+        }
+
+        .project-item.active {
+            background: rgba(255, 107, 107, 0.1);
+            border-color: rgba(255, 107, 107, 0.3);
+        }
+
+        .audit-section {
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 15px;
+            padding: 25px;
+            margin-bottom: 20px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .audit-section h2 {
+            font-size: 1.3em;
+            margin-bottom: 15px;
+            color: #ffd93d;
+        }
+
+        .audit-table {
+            width: 100%;
+            border-collapse: collapse;
+            margin-top: 10px;
+        }
+
+        .audit-table th, .audit-table td {
+            padding: 12px;
+            text-align: left;
+            border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .audit-table th {
+            color: #888;
+            font-weight: 600;
+            font-size: 0.85em;
+        }
+
+        .audit-table td {
+            font-size: 0.9em;
+        }
+
+        .audit-table .timestamp {
+            color: #666;
+            font-size: 0.8em;
+        }
+
+        .actions-panel {
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 15px;
+            padding: 25px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+            text-align: center;
+        }
+
+        .actions-panel h2 {
+            font-size: 1.3em;
+            margin-bottom: 15px;
+            color: #ff6b6b;
+        }
+
+        .actions-panel p {
+            color: #888;
+            margin-bottom: 20px;
+        }
+
+        @media (max-width: 768px) {
+            .stats-grid {
+                grid-template-columns: 1fr;
+            }
+            
+            .projects-list {
+                flex-direction: column;
+            }
+        }
+    </style>
+</head>
+<body>
+    <div class="dashboard">
+        <div class="header">
+            <h1>🚀 AI Software Factory</h1>
+            <p>Real-time Dashboard & Audit Trail Display</p>
+        </div>
+
+        <div class="stats-grid">
+            <div class="stat-card project">
+                <h3>Current Project</h3>
+                <div class="value">test-project</div>
+            </div>
+            <div class="stat-card active">
+                <h3>Active Projects</h3>
+                <div class="value">1</div>
+            </div>
+            <div class="stat-card code">
+                <h3>Code Generated</h3>
+                <div class="value">12.4 KB</div>
+            </div>
+            <div class="stat-card">
+                <h3>Status</h3>
+                <div class="value" id="status-value">running</div>
+            </div>
+        </div>
+
+        <div class="status-panel">
+            <h2>📊 Current Status</h2>
+            <div class="status-bar">
+                <div class="status-fill" id="status-fill" style="width: 75%"></div>
+            </div>
+            <div class="message">
+                <strong>Generating code...</strong><br>
+                <span style="color: #888;">Progress: 75%</span>
+            </div>
+        </div>
+
+        <div class="projects-section">
+            <h2>📁 Active Projects</h2>
+            <div class="projects-list">
+                <div class="project-item active">
+                    <strong>test-project</strong> • Agent: Orchestrator • Last update: just now
+                </div>
+            </div>
+        </div>
+
+        <div class="audit-section">
+            <h2>📜 Audit Trail</h2>
+            <table class="audit-table">
+                <thead>
+                    <tr>
+                        <th>Timestamp</th>
+                        <th>Agent</th>
+                        <th>Action</th>
+                        <th>Status</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <tr>
+                        <td class="timestamp">2026-03-22 01:41:00</td>
+                        <td>Orchestrator</td>
+                        <td>Initialized project</td>
+                        <td style="color: #00ff88;">Success</td>
+                    </tr>
+                    <tr>
+                        <td class="timestamp">2026-03-22 01:41:05</td>
+                        <td>Git Manager</td>
+                        <td>Initialized git repository</td>
+                        <td style="color: #00ff88;">Success</td>
+                    </tr>
+                    <tr>
+                        <td class="timestamp">2026-03-22 01:41:10</td>
+                        <td>Code Generator</td>
+                        <td>Generated main.py</td>
+                        <td style="color: #00ff88;">Success</td>
+                    </tr>
+                    <tr>
+                        <td class="timestamp">2026-03-22 01:41:15</td>
+                        <td>Code Generator</td>
+                        <td>Generated requirements.txt</td>
+                        <td style="color: #00ff88;">Success</td>
+                    </tr>
+                    <tr>
+                        <td class="timestamp">2026-03-22 01:41:18</td>
+                        <td>Orchestrator</td>
+                        <td>Running</td>
+                        <td style="color: #00d4ff;">In Progress</td>
+                    </tr>
+                </tbody>
+            </table>
+        </div>
+
+        <div class="actions-panel">
+            <h2>⚙️ System Actions</h2>
+            <p>Dashboard is rendering successfully. The UI manager is active and monitoring all projects.</p>
+            <p style="color: #888; font-size: 0.9em;">This dashboard is powered by the UIManager component and displays real-time status updates, audit trails, and project information.</p>
+        </div>
+    </div>
+</body>
+</html>

ai_software_factory/database.py

@@ -0,0 +1,216 @@
+"""Database connection and session management."""
+
+from collections.abc import Generator
+from pathlib import Path
+from urllib.parse import urlparse
+
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+try:
+    from .config import settings
+    from .models import Base
+except ImportError:
+    from config import settings
+    from models import Base
+
+
+def get_database_runtime_summary() -> dict[str, str]:
+    """Return a human-readable summary of the effective database backend."""
+    if settings.use_sqlite:
+        db_path = str(Path(settings.SQLITE_DB_PATH or "/tmp/ai_software_factory_test.db").expanduser().resolve())
+        return {
+            "backend": "sqlite",
+            "target": db_path,
+            "database": db_path,
+        }
+
+    parsed = urlparse(settings.database_url)
+    database_name = parsed.path.lstrip("/") or "unknown"
+    host = parsed.hostname or "unknown-host"
+    port = str(parsed.port or 5432)
+    return {
+        "backend": parsed.scheme.split("+", 1)[0] or "postgresql",
+        "target": f"{host}:{port}/{database_name}",
+        "database": database_name,
+    }
+
+
+def get_engine() -> Engine:
+    """Create and return SQLAlchemy engine with connection pooling."""
+    # Use SQLite for tests, PostgreSQL for production
+    if settings.use_sqlite:
+        db_path = settings.SQLITE_DB_PATH or "/tmp/ai_software_factory_test.db"
+        Path(db_path).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
+        db_url = f"sqlite:///{db_path}"
+        # SQLite-specific configuration - no pooling for SQLite
+        engine = create_engine(
+            db_url,
+            connect_args={"check_same_thread": False},
+            echo=settings.LOG_LEVEL == "DEBUG"
+        )
+    else:
+        db_url = settings.database_url
+        # PostgreSQL-specific configuration
+        engine = create_engine(
+            db_url,
+            pool_size=settings.DB_POOL_SIZE or 10,
+            max_overflow=settings.DB_MAX_OVERFLOW or 20,
+            pool_pre_ping=settings.LOG_LEVEL == "DEBUG",
+            echo=settings.LOG_LEVEL == "DEBUG",
+            pool_timeout=settings.DB_POOL_TIMEOUT or 30
+        )
+    
+    return engine
+
+
+def get_session() -> Generator[Session, None, None]:
+    """Yield a managed database session."""
+    engine = get_engine()
+    SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+    session = SessionLocal()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+
+def get_db() -> Generator[Session, None, None]:
+    """Dependency for FastAPI routes that need database access."""
+    yield from get_session()
+
+
+def get_db_sync() -> Session:
+    """Get a database session directly (for non-FastAPI/NiceGUI usage)."""
+    engine = get_engine()
+    SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+    session = SessionLocal()
+    return session
+
+
+def get_db_session() -> Session:
+    """Get a database session directly (for non-FastAPI usage)."""
+    session = next(get_session())
+    return session
+
+
+def get_alembic_config(database_url: str | None = None) -> Config:
+    """Return an Alembic config bound to the active database URL."""
+    package_root = Path(__file__).resolve().parent
+    alembic_ini = package_root / "alembic.ini"
+    config = Config(str(alembic_ini))
+    config.set_main_option("script_location", str(package_root / "alembic"))
+    config.set_main_option("sqlalchemy.url", database_url or settings.database_url)
+    return config
+
+
+def run_migrations(database_url: str | None = None) -> dict:
+    """Apply Alembic migrations to the configured database."""
+    try:
+        config = get_alembic_config(database_url)
+        command.upgrade(config, "head")
+        return {"status": "success", "message": "Database migrations applied."}
+    except Exception as exc:
+        return {"status": "error", "message": str(exc)}
+
+
+def init_db() -> dict:
+    """Initialize database tables and database if needed."""
+    if settings.use_sqlite:
+        result = run_migrations()
+        if result["status"] == "success":
+            print("SQLite database migrations applied successfully.")
+            return {"status": "success", "message": "SQLite database initialized via migrations."}
+        engine = get_engine()
+        try:
+            Base.metadata.create_all(bind=engine)
+            print("SQLite database tables created successfully.")
+            return {"status": "success", "message": "SQLite database initialized with metadata fallback."}
+        except Exception as e:
+            print(f"Error initializing SQLite database: {str(e)}")
+            return {'status': 'error', 'message': f'Error: {str(e)}'}
+    else:
+        # PostgreSQL
+        db_url = settings.database_url
+        db_name = db_url.split('/')[-1] if '/' in db_url else 'ai_software_factory'
+        
+        try:
+            # Create engine to check/create database
+            engine = create_engine(db_url)
+            
+            # Try to create database if it doesn't exist
+            try:
+                with engine.connect() as conn:
+                    # Check if database exists
+                    result = conn.execute(text(f"SELECT 1 FROM {db_name} WHERE 1=0"))
+                    # If no error, database exists
+                    conn.commit()
+                    print(f"PostgreSQL database '{db_name}' already exists.")
+            except Exception as e:
+                # Database doesn't exist or has different error - try to create it
+                error_msg = str(e).lower()
+                # Only create if it's a relation does not exist error or similar
+                if "does not exist" in error_msg or "database" in error_msg:
+                    try:
+                        conn = engine.connect()
+                        conn.execute(text(f"CREATE DATABASE {db_name}"))
+                        conn.commit()
+                        print(f"PostgreSQL database '{db_name}' created.")
+                    except Exception as db_error:
+                        print(f"Could not create database: {str(db_error)}")
+                        # Try to connect anyway - maybe using existing db name
+                        engine = create_engine(db_url.replace(f'/{db_name}', '/postgres'))
+                        with engine.connect() as conn:
+                            # Just create tables in postgres database for now
+                            print(f"Using existing 'postgres' database.")
+
+            migration_result = run_migrations(db_url)
+            if migration_result["status"] == "success":
+                print(f"PostgreSQL database '{db_name}' migrations applied successfully.")
+                return {'status': 'success', 'message': f'PostgreSQL database "{db_name}" initialized via migrations.'}
+
+            Base.metadata.create_all(bind=engine)
+            print(f"PostgreSQL database '{db_name}' tables created successfully.")
+            return {'status': 'success', 'message': f'PostgreSQL database "{db_name}" initialized with metadata fallback.'}
+        
+        except Exception as e:
+            print(f"Error initializing PostgreSQL database: {str(e)}")
+            return {'status': 'error', 'message': f'Error: {str(e)}'}
+
+
+def drop_db() -> dict:
+    """Drop all database tables (use with caution!)."""
+    if settings.use_sqlite:
+        engine = get_engine()
+        try:
+            Base.metadata.drop_all(bind=engine)
+            print("SQLite database tables dropped successfully.")
+            return {'status': 'success', 'message': 'SQLite tables dropped.'}
+        except Exception as e:
+            print(f"Error dropping SQLite tables: {str(e)}")
+            return {'status': 'error', 'message': str(e)}
+    else:
+        db_url = settings.database_url
+        db_name = db_url.split('/')[-1] if '/' in db_url else 'ai_software_factory'
+        
+        try:
+            engine = create_engine(db_url)
+            Base.metadata.drop_all(bind=engine)
+            print(f"PostgreSQL database '{db_name}' tables dropped successfully.")
+            return {'status': 'success', 'message': f'PostgreSQL "{db_name}" tables dropped.'}
+        except Exception as e:
+            print(f"Error dropping PostgreSQL tables: {str(e)}")
+            return {'status': 'error', 'message': str(e)}
+
+
+def create_migration_script() -> str:
+    """Generate a migration script for database schema changes."""
+    return """See ai_software_factory/alembic/versions for managed schema migrations."""

ai_software_factory/frontend.py

@@ -0,0 +1,53 @@
+"""Frontend module for NiceGUI with FastAPI integration.
+
+This module provides the NiceGUI frontend that can be initialized with a FastAPI app.
+The dashboard shown is from dashboard_ui.py with real-time database data.
+"""
+
+from fastapi import FastAPI
+from fastapi.responses import RedirectResponse
+
+from nicegui import app, ui
+
+try:
+    from .dashboard_ui import create_dashboard, create_health_page
+except ImportError:
+    from dashboard_ui import create_dashboard, create_health_page
+
+
+def init(fastapi_app: FastAPI, storage_secret: str = 'Secr2t!') -> None:
+    """Initialize the NiceGUI frontend with the FastAPI app.
+    
+    Args:
+        fastapi_app: The FastAPI application instance.
+        storage_secret: Optional secret for persistent user storage.
+    """
+    
+    def render_dashboard_page() -> None:
+        ui.page_title('AI Software Factory')
+        create_dashboard()
+
+        # NOTE dark mode will be persistent for each user across tabs and server restarts
+        ui.dark_mode().bind_value(app.storage.user, 'dark_mode')
+        ui.checkbox('dark mode').bind_value(app.storage.user, 'dark_mode')
+
+    @ui.page('/')
+    def home() -> None:
+        render_dashboard_page()
+
+    @ui.page('/show')
+    def show() -> None:
+        render_dashboard_page()
+
+    @ui.page('/health-ui')
+    def health_ui() -> None:
+        create_health_page()
+
+    @fastapi_app.get('/dashboard', include_in_schema=False)
+    def dashboard_redirect() -> RedirectResponse:
+        return RedirectResponse(url='/', status_code=307)
+    
+    ui.run_with(
+        fastapi_app,
+        storage_secret=storage_secret,  # NOTE setting a secret is optional but allows for persistent storage per user
+    )

ai_software_factory/models.py

@@ -0,0 +1,192 @@
+"""Database models for AI Software Factory."""
+
+from datetime import datetime
+from enum import Enum
+from typing import List, Optional
+import logging
+
+from sqlalchemy import (
+    Column, Integer, String, Text, Boolean, ForeignKey, DateTime, JSON
+)
+from sqlalchemy.orm import relationship, declarative_base
+
+try:
+    from .config import settings
+except ImportError:
+    from config import settings
+
+Base = declarative_base()
+logger = logging.getLogger(__name__)
+
+
+class ProjectStatus(str, Enum):
+    """Project status enumeration."""
+    INITIALIZED = "initialized"
+    STARTED = "started"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    ERROR = "error"
+
+
+class ProjectHistory(Base):
+    """Main project tracking table."""
+    __tablename__ = "project_history"
+
+    id = Column(Integer, primary_key=True)
+    project_id = Column(String(255), nullable=False)
+    project_name = Column(String(255), nullable=True)
+    features = Column(Text, default="")
+    description = Column(String(255), default="")
+    status = Column(String(50), default='started')
+    progress = Column(Integer, default=0)
+    message = Column(String(500), default="")
+    current_step = Column(String(255), nullable=True)
+    total_steps = Column(Integer, nullable=True)
+    current_step_description = Column(String(1024), nullable=True)
+    current_step_details = Column(Text, nullable=True)
+    error_message = Column(Text, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    started_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    completed_at = Column(DateTime, nullable=True)
+
+    # Relationships
+    project_logs = relationship("ProjectLog", back_populates="project_history", cascade="all, delete-orphan")
+    ui_snapshots = relationship("UISnapshot", back_populates="project_history", cascade="all, delete-orphan")
+    pull_requests = relationship("PullRequest", back_populates="project_history", cascade="all, delete-orphan")
+    pull_request_data = relationship("PullRequestData", back_populates="project_history", cascade="all, delete-orphan")
+    prompt_code_links = relationship("PromptCodeLink", back_populates="project_history", cascade="all, delete-orphan")
+
+
+class ProjectLog(Base):
+    """Detailed log entries for projects."""
+    __tablename__ = "project_logs"
+
+    id = Column(Integer, primary_key=True)
+    history_id = Column(Integer, ForeignKey("project_history.id"), nullable=False)
+    log_level = Column(String(50), default="INFO")  # INFO, WARNING, ERROR
+    log_message = Column(String(500), nullable=False)
+    timestamp = Column(DateTime, nullable=True)
+
+    project_history = relationship("ProjectHistory", back_populates="project_logs")
+
+
+class UISnapshot(Base):
+    """UI snapshots for projects."""
+    __tablename__ = "ui_snapshots"
+
+    id = Column(Integer, primary_key=True)
+    history_id = Column(Integer, ForeignKey("project_history.id"), nullable=False)
+    snapshot_data = Column(JSON, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    project_history = relationship("ProjectHistory", back_populates="ui_snapshots")
+
+
+class PullRequest(Base):
+    """Pull request data for projects."""
+    __tablename__ = "pull_requests"
+
+    id = Column(Integer, primary_key=True)
+    history_id = Column(Integer, ForeignKey("project_history.id"), nullable=False)
+    pr_number = Column(Integer, nullable=False)
+    pr_title = Column(String(500), nullable=False)
+    pr_body = Column(Text)
+    base = Column(String(255), nullable=False)
+    user = Column(String(255), nullable=False)
+    pr_url = Column(String(500), nullable=False)
+    merged = Column(Boolean, default=False)
+    merged_at = Column(DateTime, nullable=True)
+    pr_state = Column(String(50), nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    project_history = relationship("ProjectHistory", back_populates="pull_requests")
+
+
+class PullRequestData(Base):
+    """Pull request data for audit API."""
+    __tablename__ = "pull_request_data"
+
+    id = Column(Integer, primary_key=True)
+    history_id = Column(Integer, ForeignKey("project_history.id"), nullable=False)
+    pr_number = Column(Integer, nullable=False)
+    pr_title = Column(String(500), nullable=False)
+    pr_body = Column(Text)
+    pr_state = Column(String(50), nullable=False)
+    pr_url = Column(String(500), nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    project_history = relationship("ProjectHistory", back_populates="pull_request_data")
+
+
+class SystemLog(Base):
+    """System-wide log entries."""
+    __tablename__ = "system_logs"
+
+    id = Column(Integer, primary_key=True)
+    component = Column(String(50), nullable=False)
+    log_level = Column(String(50), default="INFO")
+    log_message = Column(String(500), nullable=False)
+    user_agent = Column(String(255), nullable=True)
+    ip_address = Column(String(45), nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class AuditTrail(Base):
+    """Audit trail entries for system-wide logging."""
+    __tablename__ = "audit_trail"
+
+    id = Column(Integer, primary_key=True)
+    component = Column(String(50), nullable=True)
+    log_level = Column(String(50), default="INFO")
+    message = Column(String(500), nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    project_id = Column(String(255), nullable=True)
+    action = Column(String(100), nullable=True)
+    actor = Column(String(100), nullable=True)
+    action_type = Column(String(50), nullable=True)
+    details = Column(Text, nullable=True)
+    metadata_json = Column(JSON, nullable=True)
+
+
+class PromptCodeLink(Base):
+    """Explicit lineage between a prompt event and a resulting code change."""
+    __tablename__ = "prompt_code_links"
+
+    id = Column(Integer, primary_key=True)
+    history_id = Column(Integer, ForeignKey("project_history.id"), nullable=False)
+    project_id = Column(String(255), nullable=False)
+    prompt_audit_id = Column(Integer, nullable=False)
+    code_change_audit_id = Column(Integer, nullable=False)
+    file_path = Column(String(500), nullable=True)
+    change_type = Column(String(50), nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    project_history = relationship("ProjectHistory", back_populates="prompt_code_links")
+
+
+class UserAction(Base):
+    """User action audit entries."""
+    __tablename__ = "user_actions"
+
+    id = Column(Integer, primary_key=True)
+    history_id = Column(Integer, ForeignKey("project_history.id"), nullable=True)
+    user_id = Column(String(100), nullable=True)
+    action_type = Column(String(100), nullable=True)
+    actor_type = Column(String(50), nullable=True)
+    actor_name = Column(String(100), nullable=True)
+    action_description = Column(String(500), nullable=True)
+    action_data = Column(JSON, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+
+class AgentAction(Base):
+    """Agent action audit entries."""
+    __tablename__ = "agent_actions"
+
+    id = Column(Integer, primary_key=True)
+    agent_name = Column(String(100), nullable=False)
+    action_type = Column(String(100), nullable=False)
+    success = Column(Boolean, default=True)
+    message = Column(String(500), nullable=True)
+    timestamp = Column(DateTime, default=datetime.utcnow)

ai_software_factory/pytest.ini

@@ -0,0 +1,10 @@
+[pytest]
+testpaths = tests
+pythonpath = .
+addopts = -v --tb=short
+filterwarnings =
+    ignore::DeprecationWarning
+
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = function
+asyncio_default_test_loop_scope = function

ai_software_factory/requirements.txt

@@ -0,0 +1,21 @@
+fastapi>=0.135.3
+uvicorn[standard]==0.27.0
+sqlalchemy==2.0.25
+psycopg2-binary==2.9.9
+pydantic==2.12.5
+pydantic-settings==2.1.0
+python-multipart==0.0.22
+aiofiles==23.2.1
+python-telegram-bot==20.7
+requests==2.31.0
+pytest==7.4.3
+pytest-cov==4.1.0
+black==23.12.1
+isort==5.13.2
+flake8==6.1.0
+mypy==1.7.1
+httpx==0.25.2
+nicegui==3.9.0
+aiohttp>=3.9.0
+pytest-asyncio>=0.23.0
+alembic>=1.14.0

ai_software_factory/start.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+# use path of this example as working directory; enables starting this script from anywhere
+cd "$(dirname "$0")"
+
+if [ "$1" = "prod" ]; then
+    echo "Starting Uvicorn server in production mode..."
+    # we also use a single worker in production mode so socket.io connections are always handled by the same worker
+    uvicorn main:app --workers 1 --log-level info --port 80
+elif [ "$1" = "dev" ]; then
+    echo "Starting Uvicorn server in development mode..."
+    # reload implies workers = 1
+    uvicorn main:app --reload --log-level debug --port 8000
+else
+    echo "Invalid parameter. Use 'prod' or 'dev'."
+    exit 1
+fi

ai_software_factory/test/README.md

@@ -0,0 +1,7 @@
+# Test
+
+Test
+
+## Features
+
+## Tech Stack

ai_software_factory/test/main.py

@@ -0,0 +1,2 @@
+# Generated by AI Software Factory
+print('Hello, World!')

ai_software_factory/testslogger.py

@@ -0,0 +1,400 @@
+"""Test logging utility for validating agent responses and system outputs."""
+
+import re
+from typing import Optional, Dict, Any, List
+from datetime import datetime
+
+# Color codes for terminal output
+class Colors:
+    GREEN = '\033[92m'
+    RED = '\033[91m'
+    YELLOW = '\033[93m'
+    BLUE = '\033[94m'
+    CYAN = '\033[96m'
+    RESET = '\033[0m'
+
+
+class TestLogger:
+    """Utility class for logging test results and assertions."""
+
+    def __init__(self):
+        self.assertions: List[Dict[str, Any]] = []
+        self.errors: List[Dict[str, Any]] = []
+        self.logs: List[str] = []
+
+    def log(self, message: str, level: str = 'INFO') -> None:
+        """Log an informational message."""
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        formatted = f"[{timestamp}] [{level}] {message}"
+        self.logs.append(formatted)
+        print(formatted)
+
+    def success(self, message: str) -> None:
+        """Log a success message with green color."""
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        formatted = f"{Colors.GREEN}[{timestamp}] [✓ PASS] {message}{Colors.RESET}"
+        self.logs.append(formatted)
+        print(formatted)
+
+    def error(self, message: str) -> None:
+        """Log an error message with red color."""
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        formatted = f"{Colors.RED}[{timestamp}] [✗ ERROR] {message}{Colors.RESET}"
+        self.logs.append(formatted)
+        print(formatted)
+
+    def warning(self, message: str) -> None:
+        """Log a warning message with yellow color."""
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        formatted = f"{Colors.YELLOW}[{timestamp}] [!] WARN {message}{Colors.RESET}"
+        self.logs.append(formatted)
+        print(formatted)
+
+    def info(self, message: str) -> None:
+        """Log an info message with blue color."""
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        formatted = f"{Colors.BLUE}[{timestamp}] [ℹ INFO] {message}{Colors.RESET}"
+        self.logs.append(formatted)
+        print(formatted)
+
+    def assert_contains(self, text: str, expected: str, message: str = '') -> bool:
+        """Assert that text contains expected substring."""
+        try:
+            contains = expected in text
+            if contains:
+                self.success(f"✓ '{expected}' found in text")
+                self.assertions.append({
+                    'type': 'assert_contains',
+                    'result': 'pass',
+                    'expected': expected,
+                    'message': message or f"'{expected}' in text"
+                })
+                return True
+            else:
+                self.error(f"✗ Expected '{expected}' not found in text")
+                self.assertions.append({
+                    'type': 'assert_contains',
+                    'result': 'fail',
+                    'expected': expected,
+                    'message': message or f"'{expected}' in text"
+                })
+                return False
+        except Exception as e:
+            self.error(f"Assertion failed with exception: {e}")
+            self.assertions.append({
+                'type': 'assert_contains',
+                'result': 'error',
+                'expected': expected,
+                'message': message or f"Assertion failed: {e}"
+            })
+            return False
+
+    def assert_not_contains(self, text: str, unexpected: str, message: str = '') -> bool:
+        """Assert that text does not contain expected substring."""
+        try:
+            contains = unexpected in text
+            if not contains:
+                self.success(f"✓ '{unexpected}' not found in text")
+                self.assertions.append({
+                    'type': 'assert_not_contains',
+                    'result': 'pass',
+                    'unexpected': unexpected,
+                    'message': message or f"'{unexpected}' not in text"
+                })
+                return True
+            else:
+                self.error(f"✗ Unexpected '{unexpected}' found in text")
+                self.assertions.append({
+                    'type': 'assert_not_contains',
+                    'result': 'fail',
+                    'unexpected': unexpected,
+                    'message': message or f"'{unexpected}' not in text"
+                })
+                return False
+        except Exception as e:
+            self.error(f"Assertion failed with exception: {e}")
+            self.assertions.append({
+                'type': 'assert_not_contains',
+                'result': 'error',
+                'unexpected': unexpected,
+                'message': message or f"Assertion failed: {e}"
+            })
+            return False
+
+    def assert_equal(self, actual: str, expected: str, message: str = '') -> bool:
+        """Assert that two strings are equal."""
+        try:
+            if actual == expected:
+                self.success(f"✓ Strings equal")
+                self.assertions.append({
+                    'type': 'assert_equal',
+                    'result': 'pass',
+                    'expected': expected,
+                    'message': message or f"actual == expected"
+                })
+                return True
+            else:
+                self.error(f"✗ Strings not equal. Expected: '{expected}', Got: '{actual}'")
+                self.assertions.append({
+                    'type': 'assert_equal',
+                    'result': 'fail',
+                    'expected': expected,
+                    'actual': actual,
+                    'message': message or "actual == expected"
+                })
+                return False
+        except Exception as e:
+            self.error(f"Assertion failed with exception: {e}")
+            self.assertions.append({
+                'type': 'assert_equal',
+                'result': 'error',
+                'expected': expected,
+                'actual': actual,
+                'message': message or f"Assertion failed: {e}"
+            })
+            return False
+
+    def assert_starts_with(self, text: str, prefix: str, message: str = '') -> bool:
+        """Assert that text starts with expected prefix."""
+        try:
+            starts_with = text.startswith(prefix)
+            if starts_with:
+                self.success(f"✓ Text starts with '{prefix}'")
+                self.assertions.append({
+                    'type': 'assert_starts_with',
+                    'result': 'pass',
+                    'prefix': prefix,
+                    'message': message or f"text starts with '{prefix}'"
+                })
+                return True
+            else:
+                self.error(f"✗ Text does not start with '{prefix}'")
+                self.assertions.append({
+                    'type': 'assert_starts_with',
+                    'result': 'fail',
+                    'prefix': prefix,
+                    'message': message or f"text starts with '{prefix}'"
+                })
+                return False
+        except Exception as e:
+            self.error(f"Assertion failed with exception: {e}")
+            self.assertions.append({
+                'type': 'assert_starts_with',
+                'result': 'error',
+                'prefix': prefix,
+                'message': message or f"Assertion failed: {e}"
+            })
+            return False
+
+    def assert_ends_with(self, text: str, suffix: str, message: str = '') -> bool:
+        """Assert that text ends with expected suffix."""
+        try:
+            ends_with = text.endswith(suffix)
+            if ends_with:
+                self.success(f"✓ Text ends with '{suffix}'")
+                self.assertions.append({
+                    'type': 'assert_ends_with',
+                    'result': 'pass',
+                    'suffix': suffix,
+                    'message': message or f"text ends with '{suffix}'"
+                })
+                return True
+            else:
+                self.error(f"✗ Text does not end with '{suffix}'")
+                self.assertions.append({
+                    'type': 'assert_ends_with',
+                    'result': 'fail',
+                    'suffix': suffix,
+                    'message': message or f"text ends with '{suffix}'"
+                })
+                return False
+        except Exception as e:
+            self.error(f"Assertion failed with exception: {e}")
+            self.assertions.append({
+                'type': 'assert_ends_with',
+                'result': 'error',
+                'suffix': suffix,
+                'message': message or f"Assertion failed: {e}"
+            })
+            return False
+
+    def assert_regex(self, text: str, pattern: str, message: str = '') -> bool:
+        """Assert that text matches a regex pattern."""
+        try:
+            if re.search(pattern, text):
+                self.success(f"✓ Regex pattern matched")
+                self.assertions.append({
+                    'type': 'assert_regex',
+                    'result': 'pass',
+                    'pattern': pattern,
+                    'message': message or f"text matches regex '{pattern}'"
+                })
+                return True
+            else:
+                self.error(f"✗ Regex pattern did not match")
+                self.assertions.append({
+                    'type': 'assert_regex',
+                    'result': 'fail',
+                    'pattern': pattern,
+                    'message': message or f"text matches regex '{pattern}'"
+                })
+                return False
+        except re.error as e:
+            self.error(f"✗ Invalid regex pattern: {e}")
+            self.assertions.append({
+                'type': 'assert_regex',
+                'result': 'error',
+                'pattern': pattern,
+                'message': message or f"Invalid regex: {e}"
+            })
+            return False
+        except Exception as ex:
+            self.error(f"Assertion failed with exception: {ex}")
+            self.assertions.append({
+                'type': 'assert_regex',
+                'result': 'error',
+                'pattern': pattern,
+                'message': message or f"Assertion failed: {ex}"
+            })
+            return False
+
+    def assert_length(self, text: str, expected_length: int, message: str = '') -> bool:
+        """Assert that text has expected length."""
+        try:
+            length = len(text)
+            if length == expected_length:
+                self.success(f"✓ Length is {expected_length}")
+                self.assertions.append({
+                    'type': 'assert_length',
+                    'result': 'pass',
+                    'expected_length': expected_length,
+                    'message': message or f"len(text) == {expected_length}"
+                })
+                return True
+            else:
+                self.error(f"✗ Length is {length}, expected {expected_length}")
+                self.assertions.append({
+                    'type': 'assert_length',
+                    'result': 'fail',
+                    'expected_length': expected_length,
+                    'actual_length': length,
+                    'message': message or f"len(text) == {expected_length}"
+                })
+                return False
+        except Exception as e:
+            self.error(f"Assertion failed with exception: {e}")
+            self.assertions.append({
+                'type': 'assert_length',
+                'result': 'error',
+                'expected_length': expected_length,
+                'message': message or f"Assertion failed: {e}"
+            })
+            return False
+
+    def assert_key_exists(self, text: str, key: str, message: str = '') -> bool:
+        """Assert that a key exists in a JSON-like text."""
+        try:
+            if f'"{key}":' in text or f"'{key}':" in text:
+                self.success(f"✓ Key '{key}' exists")
+                self.assertions.append({
+                    'type': 'assert_key_exists',
+                    'result': 'pass',
+                    'key': key,
+                    'message': message or f"key '{key}' exists"
+                })
+                return True
+            else:
+                self.error(f"✗ Key '{key}' not found")
+                self.assertions.append({
+                    'type': 'assert_key_exists',
+                    'result': 'fail',
+                    'key': key,
+                    'message': message or f"key '{key}' exists"
+                })
+                return False
+        except Exception as e:
+            self.error(f"Assertion failed with exception: {e}")
+            self.assertions.append({
+                'type': 'assert_key_exists',
+                'result': 'error',
+                'key': key,
+                'message': message or f"Assertion failed: {e}"
+            })
+            return False
+
+    def assert_substring_count(self, text: str, substring: str, count: int, message: str = '') -> bool:
+        """Assert that substring appears count times in text."""
+        try:
+            actual_count = text.count(substring)
+            if actual_count == count:
+                self.success(f"✓ Substring appears {count} time(s)")
+                self.assertions.append({
+                    'type': 'assert_substring_count',
+                    'result': 'pass',
+                    'substring': substring,
+                    'expected_count': count,
+                    'actual_count': actual_count,
+                    'message': message or f"'{substring}' appears {count} times"
+                })
+                return True
+            else:
+                self.error(f"✗ Substring appears {actual_count} time(s), expected {count}")
+                self.assertions.append({
+                    'type': 'assert_substring_count',
+                    'result': 'fail',
+                    'substring': substring,
+                    'expected_count': count,
+                    'actual_count': actual_count,
+                    'message': message or f"'{substring}' appears {count} times"
+                })
+                return False
+        except Exception as e:
+            self.error(f"Assertion failed with exception: {e}")
+            self.assertions.append({
+                'type': 'assert_substring_count',
+                'result': 'error',
+                'substring': substring,
+                'expected_count': count,
+                'message': message or f"Assertion failed: {e}"
+            })
+            return False
+
+    def get_assertion_count(self) -> int:
+        """Get total number of assertions made."""
+        return len(self.assertions)
+
+    def get_failure_count(self) -> int:
+        """Get number of failed assertions."""
+        return sum(1 for assertion in self.assertions if assertion.get('result') == 'fail')
+
+    def get_success_count(self) -> int:
+        """Get number of passed assertions."""
+        return sum(1 for assertion in self.assertions if assertion.get('result') == 'pass')
+
+    def get_logs(self) -> List[str]:
+        """Get all log messages."""
+        return self.logs.copy()
+
+    def get_errors(self) -> List[Dict[str, Any]]:
+        """Get all error records."""
+        return self.errors.copy()
+
+    def clear(self) -> None:
+        """Clear all logs and assertions."""
+        self.assertions.clear()
+        self.errors.clear()
+        self.logs.clear()
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        return False
+
+
+# Convenience function for context manager usage
+def test_logger():
+    """Create and return a TestLogger instance."""
+    return TestLogger()

project_name/VERSION

@@ -1 +0,0 @@
-0.0.1

project_name/hello_world.sh

@@ -1,3 +0,0 @@
-#!/bin/bash
-
-echo "Hello world"

test-project/test/TestApp/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.env
+.venv/
+node_modules/
+.env
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+.git

test-project/test/TestApp/README.md

@@ -0,0 +1,11 @@
+# TestApp
+
+A test application
+
+## Features
+- feature1
+- feature2
+
+## Tech Stack
+- python
+- fastapi

test-project/test/TestApp/main.py

@@ -0,0 +1,2 @@
+# Generated by AI Software Factory
+print('Hello, World!')

test-project/test/test-project/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.env
+.venv/
+node_modules/
+.env
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+.git

test-project/test/test-project/README.md

@@ -0,0 +1,11 @@
+# test-project
+
+Test project description
+
+## Features
+- feature-1
+- feature-2
+
+## Tech Stack
+- python
+- fastapi

test-project/test/test-project/main.py

@@ -0,0 +1,2 @@
+# Generated by AI Software Factory
+print('Hello, World!')

test-project/test/test/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.env
+.venv/
+node_modules/
+.env
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+.git

test-project/test/test/README.md

@@ -0,0 +1,7 @@
+# Test
+
+Test
+
+## Features
+
+## Tech Stack

test-project/test/test/main.py

@@ -0,0 +1,2 @@
+# Generated by AI Software Factory
+print('Hello, World!')