updated file_agent execute condition

README_CoderG_05182026.md

@@ -33,61 +33,68 @@ A production-ready orchestration workflow tool that cuts code asset production t
 * **Infrastructure Layer:** `GitHub REST API v3 Engine` — Automates remote cloud platform discovery, profile querying, and repository initialization on headless systems.
 * **Format Compilation Compilers:** `PyYAML`, `TOML`, `python-docx` — Decodes plaintext generator responses directly into precise configuration scripts and professional document layouts.
 
----
-
-
 ---
 
 ## 🏗️ Core Architecture Overview
 
 CoderG bypasses monolithic script patterns by delegating tasks across highly specialized micro-agents:
 
-┌──────────────────────────────┐
-│      app.py (Manager)        │ <── Gradio Presentation Control
-└──────────────┬───────────────┘
-                             │
-     ┌───────────────────────┼───────────────────────┐
-     ▼                       ▼                       ▼
-┌────────────────┐      ┌────────────────┐      ┌────────────────┐
-│  core_logic.py │      │ file_agent.py  │      │  git_agent.py  │
-│   (The Brain)  │      │  (The Writer)  │      │ (The Courier)  │
-└────────┬───────┘      └────────┬───────┘      └────────┬───────┘
-│                       │                       │
-└───────────────────────┼───────────────────────┘
-▼
-┌──────────────────────────┐
-│ agent_logging.py (Audit) │ ──> outputs/agent.log
-└──────────────────────────┘
+> The blueprint maps out the decoupled Manager-Worker design pattern, illustrating presentation layer's controlling specialized modules while piping structural logs to an audit trail
+
+                     +---------------------------------------+
+                     |           app.py (Manager)            | <--- Gradio Presentation Control
+                     +---------------------------------------+
+                                         |
+                +------------------------+------------------------+
+                |                        |                        |
+                v                        v                        v
+    +-----------------------++-----------------------++-----------------------+
+    |     core_logic.py     ||     file_agent.py     ||     git_agent.py     |
+    |      (The Brain)      ||     (The Writer)      ||     (The Courier)    |
+    +-----------------------++-----------------------++-----------------------+
+                |                        |                        |
+                +------------------------+------------------------+
+                                         |
+                                         v
+                     +---------------------------------------+
+                     |         agent_logging.py (Audit)       | ---> outputs/agent.log
+                     +---------------------------------------+
 
+---
 
 ## 📐 System Flowchart & Interaction Model
 
 The architectural diagram below traces an instruction's path as it travels through CoderG's isolated processing channels:
 
+> The flowchart tracks the - Run-time Execution Flow - exact lifecycle of a user request, tracing token streaming, workspace generation, remote repository initialization, and the final zero-footprint directory purge.
+
+[ User Input ]
+       |
+       v
+ +------------+        Streams Text Tokens
+ |   app.py   | <-------------------------------------------------------+
+ +------------+                                                         |
+       |                                                                |
+       | Invokes Event Processing                                       |
+       v                                                                |
+ +------------+        Passes Raw Artifacts        +---------------+    |
+ | core_logic | ---------------------------------> |  file_agent   | ---+
+ +------------+                                    +---------------+
+       |                                                   |
+       | Writes Workspace Files                            | Creates Backups
+       v                                                   v
+ +------------+        Executes Remote Push        +---------------+
+ | git_agent  | <--------------------------------- |   outputs/    |
+ +------------+         via Control Tower          +---------------+
+       |
+       +---> [ API Provision Check ] ---> Pushes Assets to Remote GitHub Target
+       |
+       v
+ +------------+
+ | temp_repo/ | ---> Purges Folder Completely on Termination (Zero Footprint)
+ +------------+
 
-[User Input ]
-│
-▼
-┌──────────┐      Streams Text Tokens
-│  app.py  │ <───────────────────────────────┐
-└────┬─────┘                                 │
-│ Invokes Event Processing              │
-▼                                       │
-┌──────────────┐   Passes Raw Artifacts ┌──────────────┐
-│core_logic.py │ ─────────────────────> │file_agent.py │
-└──────────────┘                        └──────┬───────┘
-│ Writes Workspace Files
-▼
-┌──────────────┐   Executes Remote Push ┌──────────────┐
-│git_agent.py  │ <───────────────────── │ outputs/     │ ◄── [Creates Backups]
-└──────┬───────┘   via Control Tower    └──────────────┘
-│
-├─► [API Provision check] ──► Pushes Assets to Remote GitHub Target
-▼
-┌──────────────┐
-│  temp_repo/  │ ──► Purges Folder Completely on Termination (Zero Footprint)
-└──────────────┘
-
+---
 
 ### Module Component Breakdown/Descriptions
 1. **`app.py` (Control Tower / UI Layer):** A 3-column asymmetric Gradio interface managing dynamic conversation sessions, asynchronous text streaming execution, state tracking, and explicit telemetry log piping.
@@ -120,12 +127,73 @@ The architectural diagram below traces an instruction's path as it travels throu
 * **Core Logic:** A file utility tracking internal state changes.
 * **Key Mechanisms:** Appends structured, timestamped logs out to `outputs/agent.log` to track initialization tasks, file events, or deployment problems.
 
-> Worker module includes:
+---
+
+### Worker Module - Detailed Analysis:
 
 * agent_logging.py, 
 * file_agent.py, 
 * git_agent.py
 
+
+The application relies on an isolated Manager-Worker pattern. 
+
+**app.py** sets up the interface, 
+**core_logic.py** makes strategic architectural decisions, and 
+the **Worker Module (agent_logging.py, file_agent.py, git_agent.py)** executes the concrete file system and network operations.
+
+Here is exactly how each worker behaves, executes tasks, and intersects with the application core:
+
+1. agent_logging.py (The Audit Trail)
+
+**Core Function:** This script provides unified telemetry and observability for the entire application. It handles raw I/O operations to append formatted structural logs into outputs/agent.log with high-precision timestamps (%Y-%m-%d %H:%M:%S).
+
+**Relation to app.py & core_logic.py:** It acts as a passive background layer. Rather than interacting with the user interface, it listens to the other agents. Whenever core_logic.py hits an inference issue or a worker finishes a physical action, they call log_agent_action() to register the event.
+
+**Detailed Operation:** 
+
+* Accepts an action_type (e.g., FILE_CREATION, GIT_ERROR) and a detailed message string.
+* Proactively checks if the outputs folder exists; if missing, it runs an on-the-fly directory creation.
+*3.* Opens the log file in append mode ("a"), writing the log payload in an explicit format: [TIMESTAMP] [ACTION] Message.
+
+2. file_agent.py (The Document Writer)
+
+**Core Function:** This is your disk serialization worker. It takes raw text tokens or structural payloads generated by your LLM core and turns them into actual physical workspace formats on disk (.md, .txt, .yaml, .toml, .docx).
+
+**Relation to app.py & core_logic.py:** Once core_logic.py finishes streaming its raw textual architectural insights back to app.py for user presentation, it immediately calls file_agent.write_document(). This saves the generated material locally before any remote actions take place.
+
+**Detailed Operation:**
+
+* Inspects the file extension of the target file.
+* Runs type-safe routing branches:
+* For text formats (.md, .txt), it uses standard safe file system streams.
+* For configuration files (.yaml, .toml), it evaluates whether the data stream is a string or a dict and runs safe serialization tools (yaml.safe_dump or toml.dump).
+* For Microsoft Word structures (.docx), it spawns a clean virtual XML processing model via python-docx.
+* Fires a completion signal to agent_logging.py or returns an explicit error string up to the core loop if a permissions block occurs.
+
+3. git_agent.py (The Cloud Courier)
+
+**Core Function:** This is your external networking and synchronization engine. It handles all calls to the remote GitHub REST API and coordinates local Git repository staging tree changes via native GitPython bindings.
+
+**Relation to app.py & core_logic.py:** This worker is directly wired to the Agentic Control Tower UI panel in app.py. When the human operator clicks Approve & Push to GitHub, app.py bypasses core_logic.py entirely and passes your staged file lists directly into this worker to execute the deployment.
+
+**Detailed Operation:**
+
+* Reads GITHUB_TOKEN and GITHUB_USERNAME from environment variables, throwing an authentication failure log if missing.
+* Remote Provisioning Check: Hits the GitHub API (/repos/{username}/{repo_name}). If it catches a 404 Not Found, it switches to a POST routine to create a new repository under the user account automatically.
+* Staging & Sync: Safely spins up a local folder called temp_repo/. It clones the destination repository, copies the staged target assets across from your local staging environment (outputs/), tracks changes (repo.index.add), commits the delta with the custom commit message, and pushes the local state up to the origin remote branch.
+* Dynamic Purge (finally block): To ensure zero footprint and prevent disk space buildup, a mandatory shutil.rmtree routine runs at the end of the operation, wiping out the temp_repo/ workspace completely regardless of whether the push succeeded or failed.
+
+In a Gist: When a user interacts with CoderG:
+
+**app.py** receives the user instruction and kicks off the visual stream.
+
+**core_logic.py** thinks, researches, generates the documentation strategy, and sends text back to the screen; calls file_agent.py to stage those files into the local outputs/ workspace.
+
+The user clicks approval in the Control Tower, prompting **git_agent.py** to clone down the repository into a temporary folder, transfer the files over, push them to GitHub, and instantly clean up after itself.
+
+**agent_logging.py** silently captures every single successful step and edge-case exception along the way to make debugging straightforward.
+
 ---
 
 ## 🛠️ Tech-Stack & Framework Layering
@@ -156,6 +224,66 @@ To keep internal host resources, containers, or Hugging Face spaces lean and unb
 
 ---
 
+## User-directed Git Repository Control
+
+**The Visual Intimation:** User notified for Git Repo Management
+
+The system uses two distinct visual indicators on the interface to signal that it has paused and is explicitly awaiting a human decision:
+
+1. The Main Chat Status Intercept
+At the very bottom of the streamed response text in the central chat window, a bold status flag appears:
+
+```
+🤖 Silicon Architect:
+[Generated content here...]
+
+✅ Files successfully generated in localized staging environment.
+
+◌ Awaiting authorization control panel to push to GitHub.
+```
+
+This is the user's explicit cue. The chat stream stops moving, and the text explicitly tells them that the material has transitioned from a theoretical response to an active, localized artifact awaiting deployment.
+
+2. The Control Tower Telemetry Log
+Concurrently, the right-hand panel (📊 Deployment Telemetry Logs) changes its state. Instead of its initial generic state, it reflects a holding state:
+
+```
+_Awaiting local environment staging completion..._
+```
+
+> The Human-in-the-Loop Operational Flow
+
+Because the application separates Generation (core_logic.py) from Transport (git_agent.py), the workspace naturally freezes in a secure state until a human interacts with it.
+
+[ Step 1: Model Streams Content ]
+                  │
+                  ▼
+  [ Step 2: Local File Staged Automatically ]
+                  │
+                  ▼
+┌───────────────────────────────────────────┐
+│  SYSTEM PAUSES & PRINTS INTERCEPT NOTICE  │ ◄─── User sees "Awaiting authorization..."
+└─────────────────────┬─────────────────────┘
+                      │
+            Is the user satisfied?
+                      │
+         ┌────────────┴────────────┐
+         ▼                         ▼
+     [ YES ]                    [ NO ]
+         │                         │
+User clicks "Approve       User types a adjustment
+   & Push to GitHub"          prompt in chat box
+         │                         │
+         ▼                         ▼
+`git_agent` executes       `core_logic` overwrites
+and flushes workspace     staging with updated data
+
+**In a Gist:**
+
+The end-user knows it is time to use the Control Tower because the agent literally concludes its response with an explicit message stating that it is now waiting for their authorization click. If the user is unhappy with the code or document layout on screen, they simply ignore the button, reply with corrections in the chat input, and the agent will overwrite the staged files with the corrected versions—starting the approval cycle over again.
+
+---
+
 ## 🚀 Planned & Strategic Enhancements
 
 ### Phase 1: Context Capture Optimizations

core_logic.py

@@ -128,6 +128,7 @@ def chat_function(message, history):
         )
 
         response_text = ""
+
         # Step 1: Stream the raw LLM output token by token to the user
         for chunk in completion:
             if chunk.choices and chunk.choices[0].delta.content:
@@ -135,33 +136,42 @@ def chat_function(message, history):
                 response_text += token
                 yield response_text
 
-        # Step 2: Transition seamlessly to Local File Generation
-        yield response_text + "\n\n◌ _File agent initialized: Generating local documentation workspace..._"
-        
-        from file_agent import write_document
-        import shutil
-        
-        filename = "COURSE_README.md"
-        backup_filename = "COURSE_README_-1.md"
-        
-        # Proactively manage historical backup copy before writing fresh file state
-        src_path = os.path.join("outputs", filename)
-        dst_path = os.path.join("outputs", backup_filename)
-        if os.path.exists(src_path):
-            try:
-                shutil.copy2(src_path, dst_path)
-            except Exception as e:
-                from agent_logging import log_agent_action
-                log_agent_action("BACKUP_ERROR", f"Failed to cycle historical version file: {str(e)}")
-
-        # Write fresh incoming file generation
-        file_path = write_document(response_text, filename)
-        
-        # Step 3: Inform the UI that the material is staged and ready for the GitHub authorization layer
-        if "Error" not in file_path:
-            yield response_text + f"\n\n✅ _Files successfully generated in localized staging environment._\n\n◌ _Awaiting authorization control panel to push to GitHub._"
-        else:
-            yield response_text + f"\n\n❌ _File generation failed: {file_path}_"
+        # ARTIFACT CHECK: Scan the response text for any code block structures
+        # This matches strings enclosed within triple backticks ```
+        has_code_blocks = bool(re.search(r"```[\s\S]*?```", response_text))
+
+        if has_code_blocks:
+            # ONLY execute file creation and staging alerts if an artifact is detected
+            
+            # Step 2: Transition seamlessly to Local File Generation
+            yield response_text + "\n\n◌ _File agent initialized: Generating local documentation workspace..._"
+            
+            from file_agent import write_document
+            import shutil
+            
+            filename = "COURSE_README.md"
+            backup_filename = "COURSE_README_-1.md"
+            
+            # Proactively manage historical backup copy before writing fresh file state
+            src_path = os.path.join("outputs", filename)
+            dst_path = os.path.join("outputs", backup_filename)
+            if os.path.exists(src_path):
+                try:
+                    shutil.copy2(src_path, dst_path)
+                except Exception as e:
+                    from agent_logging import log_agent_action
+                    log_agent_action("BACKUP_ERROR", f"Failed to cycle historical version file: {str(e)}")
+
+            # Write fresh incoming file generation
+            file_path = write_document(response_text, filename)
+            
+            print(f"\nGenerated file at: {file_path}")
+            
+            # Step 3: Inform the UI that the material is staged and ready for the GitHub authorization layer
+            if "Error" not in file_path:
+                yield response_text + f"\n\n✅ _Files successfully generated in localized staging environment._\n\n◌ _Awaiting authorization control panel to push to GitHub._"
+            else:
+                yield response_text + f"\n\n❌ _File generation failed: {file_path}_"
 
     except Exception as e:
         yield f"Error: {str(e)}"

perception_agent.py

@@ -39,7 +39,7 @@ def read_image_file(file_path):
                     ]
                 }
             ],
-            temperature=0.0
+            temperature=0.2
         )
         log_agent_action("PERCEPTION_SUCCESS", f"Vision extraction complete for {file_path}")
         return f"\n--- Visual Content Extraction from {os.path.basename(file_path)} ---\n{response.choices[0].message.content}\n"
@@ -76,7 +76,7 @@ def read_document_file(file_path):
             paragraphs = [p.text for p in doc.paragraphs]
             return f"\n--- Document Text Extraction: {filename} ---\n" + "\n".join(paragraphs) + "\n"
         
-        # 4. NEW ADDITION: Portable Document Format (.pdf) Ingestion
+        # 4. Portable Document Format (.pdf) Ingestion
         elif ext == '.pdf':
             log_agent_action("PERCEPTION", f"Initializing pypdf reader pipeline: {filename}")
             reader = PdfReader(file_path)