devops-copilot 0.1.0__tar.gz → 0.1.1__tar.gz

devops_copilot-0.1.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: devops-copilot
+Version: 0.1.1
+Summary: An AI-driven DevOps Copilot and CLI Client for managing bare-metal servers securely
+Author: irzix
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: server
+Requires-Dist: fastapi>=0.111.0; extra == "server"
+Requires-Dist: uvicorn>=0.30.0; extra == "server"
+Requires-Dist: sqlmodel>=0.0.22; extra == "server"
+Requires-Dist: pyjwt>=2.8.0; extra == "server"
+Requires-Dist: aiosqlite>=0.20.0; extra == "server"
+Requires-Dist: cryptography>=42.0.0; extra == "server"
+Requires-Dist: langchain>=0.2.0; extra == "server"
+Requires-Dist: chromadb>=0.5.0; extra == "server"
+Requires-Dist: pydantic-settings>=2.2.0; extra == "server"
+Requires-Dist: bcrypt>=4.1.0; extra == "server"
+Requires-Dist: python-multipart>=0.0.9; extra == "server"
+Requires-Dist: greenlet>=3.0.0; extra == "server"
+Requires-Dist: langchain-openai>=0.1.0; extra == "server"
+Requires-Dist: asyncssh>=2.14.0; extra == "server"
+
+# DevOps Copilot 🚀
+
+**An autonomous, self-learning AI DevOps Assistant & CLI Client that manages bare-metal servers with Experiential Memory (`ExpeL`), Semantic Guardrails, and Real-Time SSH Tunneling.**
+
+---
+
+## 💡 About The Project
+
+Managing infrastructure via traditional CLI tools or basic AI wrappers often leads to dangerous mistakes, repetitive debugging dead-ends, and fragmented server logs. **DevOps Copilot** redefines server management by bringing **Closed-Loop Experiential Learning (ExpeL)** directly to your terminal.
+
+Unlike standard AI chat wrappers that forget previous troubleshooting sessions, `DevOps Copilot` builds a permanent, structured **ChromaDB Vector Knowledge Base** of your infrastructure:
+
+- **🧠 Zero-Click Experiential Learning (ExpeL & Reflexion):** Every time an incident or bug is diagnosed and resolved, the agent distills the entire session into a structured Postmortem (`Problem`, `Real Cause`, `What didn't work`, `What worked`). Before tackling new errors, relevant past lessons are **automatically retrieved and injected** into the agent's context—ensuring it *never repeats a dead end*.
+- **🛡️ Semantic Security Guardrails:** Local vector search intercepts and blocks catastrophic shell commands (e.g., `rm -rf /`, `mkfs`) before they ever touch your servers.
+- **🧑‍💻 Human-in-the-Loop (HITL) Approvals:** State-modifying actions dynamically prompt for explicit admin confirmation (`[y/N]`) inside the terminal with clean prompt synchronization.
+- **⚡ Real-Time Async Execution Tunnel:** Streams LLM reasoning, SSH `stdout`, and `stderr` line-by-line via resilient WebSockets with automatic reconnection and exponential backoff.
+- **🔒 Zero-Trust Credential Encryption:** Passwords and SSH private keys are encrypted at rest using AES-256 (`Fernet`).
+
+---
+
+## 🏛️ System Architecture & ExpeL Loop
+
+```
++-----------------------------------------------------------------------------------+
+|                                 DevOps Copilot CLI                                |
+|  (Typer Async Client + Real-Time WebSocket Tunnel + [y/N] Terminal Approval)      |
++-----------------------------------------------------------------------------------+
+                                   |           ^
+                   REST Auth/CRUD  |           | WebSocket Stream (stdout/stderr)
+                                   v           |
++-----------------------------------------------------------------------------------+
+|                              FastAPI Backend Server                               |
+|                                                                                   |
+|  +------------------------+   +-----------------------+   +--------------------+  |
+|  |     Auth Module        |   |    Servers Module     |   | Guardrails Module  |  |
+|  |  (JWT & AES Fernet)    |   |  (AsyncSSH Execution) |   | (Vector Blacklist) |  |
+|  +------------------------+   +-----------------------+   +--------------------+  |
+|                                                                                   |
+|  +-----------------------------------------------------------------------------+  |
+|  |                              Chat & Agent Module                            |  |
+|  |   LangChain StateGraph + Zero-Click ExpeL Injection + OpenRouter LLM        |  |
+|  +-----------------------------------------------------------------------------+  |
+|                                       |                                           |
+|                                       v                                           |
+|  +-----------------------------------------------------------------------------+  |
+|  |                            Knowledge Base (ChromaDB)                        |  |
+|  |  [command_history]   [server_logs]   [server_configs]   [lessons_learned]   |  |
+|  +-----------------------------------------------------------------------------+  |
++-----------------------------------------------------------------------------------+
+```
+
+### The Closed-Loop Experiential Learning (`ExpeL`) Flow:
+1. **Observe & Act:** Agent connects via `AsyncSSH`, runs non-destructive diagnostics or approved actions, and indexes outputs into `command_history` and `server_logs`.
+2. **Judge & Extract:** When an incident is resolved, running `devops-copilot lesson <session_id>` triggers an automated LLM extraction (`Problem`, `Real Cause`, `What didn't work`, `What worked`) stored in `lessons_learned`.
+3. **Zero-Click Injection (Future Decision):** On any future chat turn or command error, the `inject_experiential_memory` middleware queries `lessons_learned` and injects proven solutions directly into the prompt context.
+
+---
+
+## Key Features
+- **Experiential Learning (ExpeL / Reflexion Postmortems):** Distills complex debugging sessions into structured `Lessons Learned` cards indexed into ChromaDB with zero-click context injection.
+- **Lean RAG Knowledge Base:** Automatically chunks and indexes executed SSH command outputs, logs, and server configs into separate **ChromaDB** collections.
+- **Semantic Guardrails:** Uses local vector search to intercept and block dangerous terminal commands.
+- **Human-in-the-Loop (HITL):** Enforces admin approval (`[y/N]`) inside the terminal for any state-modifying actions.
+- **CLI Connection Resilience:** Automatically reconnects to the WebSocket server using exponential backoff if the network drops or the server restarts.
+- **Real-Time Streaming:** Streams LLM thoughts and active SSH `stdout`/`stderr` line-by-line using WebSockets with 30s execution timeouts.
+- **Encrypted Credentials:** Securely encrypts passwords and SSH private keys using Fernet (AES-256).
+- **Server & Session CRUD:** Full REST API support for updating/deleting server connections and deleting chat sessions.
+- **Flexible AI Models:** Powered by **OpenRouter** (supports Llama 3, Gemini, GPT, etc.).
+
+---
+
+## 📦 Quick Start (Backend Server)
+
+### 1. Configure Settings
+Copy the env file and populate keys:
+```bash
+cp .env.example .env
+```
+Make sure to add your `OPENROUTER_API_KEY` and a custom base64 `ENCRYPTION_KEY` in `.env`.
+
+### 2. Run with Docker Compose
+```bash
+docker compose up -d --build
+```
+The server will boot on port `8000`. Database tables and security blacklist vectors are automatically seeded on startup.
+
+---
+
+## 💻 Quick Start (CLI Client)
+
+### 1. Install Globally
+Install the package in editable mode from your local repository root:
+```bash
+uv pip install -e .
+```
+
+### 2. Authenticate
+Configure the server URL and log in to get your JWT access token:
+```bash
+devops-copilot login
+```
+
+### 3. Interactive Chat & Auto-Postmortems
+Start the real-time DevOps chat session:
+```bash
+devops-copilot chat
+```
+*Ask the agent to check stats or run actions. Approve state-modifying commands directly in the prompt.*
+
+Extract and index a structured Experiential Lesson Learned from any completed troubleshooting session:
+```bash
+devops-copilot lesson <session_id>
+```

devops_copilot-0.1.1/README.md

@@ -0,0 +1,113 @@
+# DevOps Copilot 🚀
+
+**An autonomous, self-learning AI DevOps Assistant & CLI Client that manages bare-metal servers with Experiential Memory (`ExpeL`), Semantic Guardrails, and Real-Time SSH Tunneling.**
+
+---
+
+## 💡 About The Project
+
+Managing infrastructure via traditional CLI tools or basic AI wrappers often leads to dangerous mistakes, repetitive debugging dead-ends, and fragmented server logs. **DevOps Copilot** redefines server management by bringing **Closed-Loop Experiential Learning (ExpeL)** directly to your terminal.
+
+Unlike standard AI chat wrappers that forget previous troubleshooting sessions, `DevOps Copilot` builds a permanent, structured **ChromaDB Vector Knowledge Base** of your infrastructure:
+
+- **🧠 Zero-Click Experiential Learning (ExpeL & Reflexion):** Every time an incident or bug is diagnosed and resolved, the agent distills the entire session into a structured Postmortem (`Problem`, `Real Cause`, `What didn't work`, `What worked`). Before tackling new errors, relevant past lessons are **automatically retrieved and injected** into the agent's context—ensuring it *never repeats a dead end*.
+- **🛡️ Semantic Security Guardrails:** Local vector search intercepts and blocks catastrophic shell commands (e.g., `rm -rf /`, `mkfs`) before they ever touch your servers.
+- **🧑‍💻 Human-in-the-Loop (HITL) Approvals:** State-modifying actions dynamically prompt for explicit admin confirmation (`[y/N]`) inside the terminal with clean prompt synchronization.
+- **⚡ Real-Time Async Execution Tunnel:** Streams LLM reasoning, SSH `stdout`, and `stderr` line-by-line via resilient WebSockets with automatic reconnection and exponential backoff.
+- **🔒 Zero-Trust Credential Encryption:** Passwords and SSH private keys are encrypted at rest using AES-256 (`Fernet`).
+
+---
+
+## 🏛️ System Architecture & ExpeL Loop
+
+```
++-----------------------------------------------------------------------------------+
+|                                 DevOps Copilot CLI                                |
+|  (Typer Async Client + Real-Time WebSocket Tunnel + [y/N] Terminal Approval)      |
++-----------------------------------------------------------------------------------+
+                                   |           ^
+                   REST Auth/CRUD  |           | WebSocket Stream (stdout/stderr)
+                                   v           |
++-----------------------------------------------------------------------------------+
+|                              FastAPI Backend Server                               |
+|                                                                                   |
+|  +------------------------+   +-----------------------+   +--------------------+  |
+|  |     Auth Module        |   |    Servers Module     |   | Guardrails Module  |  |
+|  |  (JWT & AES Fernet)    |   |  (AsyncSSH Execution) |   | (Vector Blacklist) |  |
+|  +------------------------+   +-----------------------+   +--------------------+  |
+|                                                                                   |
+|  +-----------------------------------------------------------------------------+  |
+|  |                              Chat & Agent Module                            |  |
+|  |   LangChain StateGraph + Zero-Click ExpeL Injection + OpenRouter LLM        |  |
+|  +-----------------------------------------------------------------------------+  |
+|                                       |                                           |
+|                                       v                                           |
+|  +-----------------------------------------------------------------------------+  |
+|  |                            Knowledge Base (ChromaDB)                        |  |
+|  |  [command_history]   [server_logs]   [server_configs]   [lessons_learned]   |  |
+|  +-----------------------------------------------------------------------------+  |
++-----------------------------------------------------------------------------------+
+```
+
+### The Closed-Loop Experiential Learning (`ExpeL`) Flow:
+1. **Observe & Act:** Agent connects via `AsyncSSH`, runs non-destructive diagnostics or approved actions, and indexes outputs into `command_history` and `server_logs`.
+2. **Judge & Extract:** When an incident is resolved, running `devops-copilot lesson <session_id>` triggers an automated LLM extraction (`Problem`, `Real Cause`, `What didn't work`, `What worked`) stored in `lessons_learned`.
+3. **Zero-Click Injection (Future Decision):** On any future chat turn or command error, the `inject_experiential_memory` middleware queries `lessons_learned` and injects proven solutions directly into the prompt context.
+
+---
+
+## Key Features
+- **Experiential Learning (ExpeL / Reflexion Postmortems):** Distills complex debugging sessions into structured `Lessons Learned` cards indexed into ChromaDB with zero-click context injection.
+- **Lean RAG Knowledge Base:** Automatically chunks and indexes executed SSH command outputs, logs, and server configs into separate **ChromaDB** collections.
+- **Semantic Guardrails:** Uses local vector search to intercept and block dangerous terminal commands.
+- **Human-in-the-Loop (HITL):** Enforces admin approval (`[y/N]`) inside the terminal for any state-modifying actions.
+- **CLI Connection Resilience:** Automatically reconnects to the WebSocket server using exponential backoff if the network drops or the server restarts.
+- **Real-Time Streaming:** Streams LLM thoughts and active SSH `stdout`/`stderr` line-by-line using WebSockets with 30s execution timeouts.
+- **Encrypted Credentials:** Securely encrypts passwords and SSH private keys using Fernet (AES-256).
+- **Server & Session CRUD:** Full REST API support for updating/deleting server connections and deleting chat sessions.
+- **Flexible AI Models:** Powered by **OpenRouter** (supports Llama 3, Gemini, GPT, etc.).
+
+---
+
+## 📦 Quick Start (Backend Server)
+
+### 1. Configure Settings
+Copy the env file and populate keys:
+```bash
+cp .env.example .env
+```
+Make sure to add your `OPENROUTER_API_KEY` and a custom base64 `ENCRYPTION_KEY` in `.env`.
+
+### 2. Run with Docker Compose
+```bash
+docker compose up -d --build
+```
+The server will boot on port `8000`. Database tables and security blacklist vectors are automatically seeded on startup.
+
+---
+
+## 💻 Quick Start (CLI Client)
+
+### 1. Install Globally
+Install the package in editable mode from your local repository root:
+```bash
+uv pip install -e .
+```
+
+### 2. Authenticate
+Configure the server URL and log in to get your JWT access token:
+```bash
+devops-copilot login
+```
+
+### 3. Interactive Chat & Auto-Postmortems
+Start the real-time DevOps chat session:
+```bash
+devops-copilot chat
+```
+*Ask the agent to check stats or run actions. Approve state-modifying commands directly in the prompt.*
+
+Extract and index a structured Experiential Lesson Learned from any completed troubleshooting session:
+```bash
+devops-copilot lesson <session_id>
+```

{devops_copilot-0.1.0 → devops_copilot-0.1.1}/app/cli/main.py

@@ -247,5 +247,46 @@ def chat():
     # 3. Enter the async WebSocket execution loop
     asyncio.run(run_chat_loop(server_url, token, session_id))
 
+
+@app.command("lesson")
+def lesson(
+    session_id: int = typer.Argument(..., help="The Chat Session ID to analyze and extract postmortem from")
+):
+    """
+    Extract a structured Experiential Lesson Learned (ExpeL Postmortem) from a past debugging session
+    and index it into the permanent vector database.
+    """
+    config = load_config()
+    if not config:
+        typer.secho("Error: No configuration found. Please run 'devops-copilot login' first.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    server_url = config["server_url"]
+    token = config["token"]
+    headers = {"Authorization": f"Bearer {token}"}
+
+    typer.echo(f"Analyzing session #{session_id} and extracting Experiential Lesson Learned...")
+    try:
+        response = httpx.post(f"{server_url}/api/v1/chat/sessions/{session_id}/postmortem", headers=headers, timeout=60.0)
+        if response.status_code == 404:
+            typer.secho(f"Session #{session_id} not found or no access.", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1)
+        response.raise_for_status()
+        res_data = response.json()
+        lesson_data = res_data.get("lesson_learned", {})
+        typer.secho("\n✨ [Experiential Lesson Learned Recorded successfully!]", fg=typer.colors.GREEN, bold=True)
+        typer.echo(f"  • Server:           {lesson_data.get('server_name', 'N/A')}")
+        typer.echo(f"  • Problem:          {lesson_data.get('problem', 'N/A')}")
+        typer.echo(f"  • Real Cause:       {lesson_data.get('real_cause', 'N/A')}")
+        typer.echo(f"  • What didn't work: {lesson_data.get('what_didnt_work', 'N/A')}")
+        typer.echo(f"  • What worked:      {lesson_data.get('what_worked', 'N/A')}")
+        typer.echo(f"  • Time to Resolve:  {lesson_data.get('time_to_resolve', 'N/A')}\n")
+    except typer.Exit:
+        raise
+    except Exception as e:
+        typer.secho(f"Error generating lesson learned: {str(e)}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+
 if __name__ == "__main__":
     app()

{devops_copilot-0.1.0 → devops_copilot-0.1.1}/app/modules/chat/agent.py

@@ -18,6 +18,15 @@ from app.core.security import decrypt_data
 from app.modules.servers.models import Server
 from app.modules.servers.service import servers_service
 from app.modules.chat.models import AgentAction
+from app.modules.guardrails.service import is_command_safe
+from app.modules.knowledge.service import (
+    index_command_output,
+    search as knowledge_search,
+    index_log,
+    index_config,
+    index_lesson_learned,
+    search_lessons_learned as service_search_lessons,
+)
 
 # Context variables to track active execution details across async threads
 active_websocket = contextvars.ContextVar("active_websocket")
@@ -123,7 +132,6 @@ async def execute_ssh_command(server_id: int | str, command: str) -> str:
     """
     try:
         # 1. Run semantic safety guardrail
-        from app.modules.guardrails.service import is_command_safe
         is_safe, warning, similarity = is_command_safe(command)
         if not is_safe:
             return f"Execution Blocked by Guardrail: {warning} (similarity index: {similarity:.2f})"
@@ -249,7 +257,6 @@ async def execute_ssh_command(server_id: int | str, command: str) -> str:
 
                     # Auto-index execution output into RAG knowledge base
                     try:
-                        from app.modules.knowledge.service import index_command_output
                         index_command_output(server.name, command, stdout_str, stderr_str, exit_code)
                     except Exception:
                         pass  # Non-critical: don't break execution if indexing fails
@@ -273,8 +280,7 @@ async def search_knowledge(query: str, sources: list[str] | None = None) -> str:
     Use this tool to recall past command outputs, server logs, or config file contents.
     """
     try:
-        from app.modules.knowledge.service import search
-        return search(query, collection_names=sources, n_results=3)
+        return knowledge_search(query, collection_names=sources, n_results=3)
     except Exception as e:
         return f"Knowledge search error: {str(e)}"
 
@@ -328,7 +334,6 @@ async def fetch_server_logs(server_id: int | str, log_source: str = "journalctl
 
         # Auto-index fetched logs
         try:
-            from app.modules.knowledge.service import index_log
             index_log(server.name, log_source, stdout)
         except Exception:
             pass
@@ -397,7 +402,6 @@ async def fetch_server_config(server_id: int | str, file_path: str) -> str:
 
         # Auto-index the config file
         try:
-            from app.modules.knowledge.service import index_config
             index_config(server.name, file_path, stdout)
         except Exception:
             pass
@@ -407,6 +411,56 @@ async def fetch_server_config(server_id: int | str, file_path: str) -> str:
         return f"Error fetching config: {str(e)}"
 
 
+@tool
+async def record_lesson_learned(
+    server_id: int | str,
+    problem: str,
+    real_cause: str,
+    what_didnt_work: str,
+    what_worked: str,
+    time_to_resolve: str
+) -> str:
+    """
+    Record a structured lesson learned (postmortem) after successfully resolving an incident or bug on a server.
+    This populates the knowledge base (ExpeL/Reflexion) to resolve similar issues instantly next time.
+    """
+    try:
+        owner_id = active_owner_id.get()
+        async with async_session_maker() as session:
+            try:
+                is_id = isinstance(server_id, int) or (isinstance(server_id, str) and server_id.isdigit())
+                if is_id:
+                    server = await servers_service.get_server_by_id(session, int(server_id) if isinstance(server_id, str) else server_id, owner_id)
+                else:
+                    server = await servers_service.get_server_by_name(session, str(server_id), owner_id)
+            except Exception:
+                return f"Error: Server '{server_id}' not found."
+
+        index_lesson_learned(
+            server_name=server.name,
+            problem=problem,
+            real_cause=real_cause,
+            what_didnt_work=what_didnt_work,
+            what_worked=what_worked,
+            time_to_resolve=time_to_resolve
+        )
+        return f"Lesson Learned recorded for {server.name}: Problem '{problem}' resolved via '{what_worked}'."
+    except Exception as e:
+        return f"Error recording lesson learned: {str(e)}"
+
+
+@tool
+async def search_lessons_learned(query: str) -> str:
+    """
+    Semantic search across structured past lessons learned (postmortems).
+    Always call this before troubleshooting an incident or error to see what worked and what didn't work previously.
+    """
+    try:
+        return service_search_lessons(query)
+    except Exception as e:
+        return f"Error searching lessons learned: {str(e)}"
+
+
 # Define list of tools available to the Agent
 tools = [
     list_available_servers,
@@ -414,23 +468,28 @@ tools = [
     search_knowledge,
     fetch_server_logs,
     fetch_server_config,
+    record_lesson_learned,
+    search_lessons_learned,
 ]
 
 # Setup agent prompt template
 system_prompt = """You are a highly capable DevOps AI Assistant managing servers via SSH.
-You have tools to list servers, execute commands, fetch logs/configs, and search past knowledge.
+You have tools to list servers, execute commands, fetch logs/configs, search past knowledge, and record/search structured lessons learned.
 
 IMPORTANT INSTRUCTIONS:
 1. Always call `list_available_servers` first if you do not know the server_id.
-2. Use `search_knowledge` to recall past command outputs, logs, or configs before re-running commands.
-3. Use `fetch_server_logs` to pull and index server logs (journalctl, syslog, etc.).
-4. Use `fetch_server_config` to read and index config files (nginx, systemd, etc.).
-5. Any command you execute will be checked by a semantic guardrail.
-6. If a tool returns 'PAUSED: REQUIRES_APPROVAL: <action_id>', you MUST:
+2. EXPERIENTIAL LEARNING PROTOCOL (ExpeL / Reflexion):
+   - Before debugging or troubleshooting ANY server error or incident: ALWAYS call `search_lessons_learned` first to check if a similar issue occurred before. Pay close attention to "What didn't work" to avoid dead ends.
+   - After successfully resolving a server issue, bug, or incident: ALWAYS call `record_lesson_learned` with the structured breakdown (Problem, Real Cause, What didn't work, What worked, Time to Resolve).
+3. Use `search_knowledge` to recall general past command outputs, logs, or configs before re-running commands.
+4. Use `fetch_server_logs` to pull and index server logs (journalctl, syslog, etc.).
+5. Use `fetch_server_config` to read and index config files (nginx, systemd, etc.).
+6. Any command you execute will be checked by a semantic guardrail.
+7. If a tool returns 'PAUSED: REQUIRES_APPROVAL: <action_id>', you MUST:
    - STOP all execution immediately. Do not attempt to call any other tools.
    - Reply to the user explaining that the command requires their approval.
    - Explicitly mention the Action ID: '<action_id>'.
-7. Be concise and report the final outputs clearly.
+8. Be concise and report the final outputs clearly.
 """
 
 def create_agent_executor(callbacks=None):
@@ -441,3 +500,24 @@ def create_agent_executor(callbacks=None):
         tools=tools,
         system_prompt=system_prompt
     )
+
+
+def inject_experiential_memory(prompt: str) -> str:
+    """
+    Zero-Click ExpeL Auto-Retrieval:
+    Automatically searches past structured lessons learned and injects them directly into the prompt context.
+    Ensures the 'Retrieve Next Time -> Future Decision' loop is 100% systemic and guaranteed.
+    """
+    try:
+        retrieved_lessons = service_search_lessons(prompt, n_results=2)
+        if "No matching lessons" not in retrieved_lessons and "No lessons learned recorded" not in retrieved_lessons:
+            return (
+                f"{prompt}\n\n"
+                f"[⚡ AUTO-RETRIEVED EXPERIENTIAL MEMORY (ExpeL) ⚡]\n"
+                f"Relevant past troubleshooting postmortems automatically retrieved for your current task:\n"
+                f"{retrieved_lessons}\n"
+                f"CRITICAL INSTRUCTION: Review 'What didn't work' and 'What worked' above. Do NOT repeat dead ends.\n"
+            )
+        return prompt
+    except Exception:
+        return prompt

{devops_copilot-0.1.0 → devops_copilot-0.1.1}/app/modules/chat/router.py

@@ -1,9 +1,10 @@
 import jwt
+import json
 from fastapi import APIRouter, Depends, HTTPException, status, WebSocket, WebSocketDisconnect, Query
 from typing import List
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import select
-from langchain_core.messages import HumanMessage, AIMessage
+from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
 
 from app.core.config import settings
 from app.core.database import get_session, async_session_maker
@@ -20,6 +21,8 @@ from app.modules.chat.schema import (
 )
 from app.modules.chat.agent import (
     create_agent_executor,
+    get_llm,
+    inject_experiential_memory,
     StreamingCallbackHandler,
     active_websocket,
     active_session_id,
@@ -27,6 +30,7 @@ from app.modules.chat.agent import (
     decrypt_data,
     asyncssh
 )
+from app.modules.knowledge.service import index_lesson_learned, index_command_output
 
 router = APIRouter()
 
@@ -105,6 +109,70 @@ async def delete_session(
     await session.commit()
     return {"status": "success", "message": f"Chat session {session_id} deleted successfully"}
 
+@router.post("/sessions/{session_id}/postmortem")
+async def generate_postmortem(
+    session_id: int,
+    current_user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_session)
+):
+    """
+    Generate an automatic Post-Incident Lesson Learned (Postmortem) from the session history
+    using Experiential Learning (ExpeL) protocol, and index it into ChromaDB.
+    """
+    sess_statement = select(ChatSession).where(ChatSession.id == session_id, ChatSession.user_id == current_user.id)
+    sess_result = await session.exec(sess_statement)
+    if not sess_result.first():
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Chat session not found")
+
+    msg_statement = select(ChatMessage).where(ChatMessage.session_id == session_id).order_by(ChatMessage.created_at.asc())
+    msg_result = await session.exec(msg_statement)
+    messages = msg_result.all()
+    if not messages:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="No messages found in this session to analyze.")
+
+    transcript = "\n".join([f"[{m.role.upper()}]: {m.content}" for m in messages])
+    llm = get_llm()
+    prompt = """You are an Expert DevOps Incident Analyzer performing an Experiential Learning (ExpeL / Reflexion) postmortem.
+Analyze the following troubleshooting conversation transcript between an admin and an AI agent.
+Extract the core troubleshooting lesson into the exact JSON schema below. Output ONLY valid JSON:
+{
+  "server_name": "The name or IP of the server where the incident occurred (or 'unknown' if not clear)",
+  "problem": "A concise 2-5 word description of the problem (e.g. OOMKilled, Nginx 502 Bad Gateway)",
+  "real_cause": "The actual root cause discovered during troubleshooting",
+  "what_didnt_work": "Summary of commands or approaches that failed or didn't fix the issue",
+  "what_worked": "The exact resolution or deployment that fixed the issue",
+  "time_to_resolve": "Estimated time taken to resolve (e.g. 15 min, 3 steps)"
+}"""
+
+    try:
+        response = await llm.ainvoke([SystemMessage(content=prompt), HumanMessage(content=f"TRANSCRIPT:\n{transcript[:15000]}")])
+        content_text = response.content
+        if isinstance(content_text, list):
+            content_text = " ".join([str(c) for c in content_text])
+        
+        # Clean markdown code block if present
+        clean_json = content_text.strip()
+        if clean_json.startswith("```json"):
+            clean_json = clean_json[7:]
+        if clean_json.startswith("```"):
+            clean_json = clean_json[3:]
+        if clean_json.endswith("```"):
+            clean_json = clean_json[:-3]
+        clean_json = clean_json.strip()
+
+        data = json.loads(clean_json)
+        index_lesson_learned(
+            server_name=data.get("server_name", "unknown"),
+            problem=data.get("problem", "Unknown Issue"),
+            real_cause=data.get("real_cause", "N/A"),
+            what_didnt_work=data.get("what_didnt_work", "N/A"),
+            what_worked=data.get("what_worked", "N/A"),
+            time_to_resolve=data.get("time_to_resolve", "N/A")
+        )
+        return {"status": "success", "lesson_learned": data}
+    except Exception as e:
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to extract postmortem: {str(e)}")
+
 # --- WebSocket Real-Time Chat & Execution Tunnel ---
 
 @router.websocket("/ws")
@@ -188,9 +256,12 @@ async def websocket_endpoint(
                     callback = StreamingCallbackHandler(websocket)
                     agent_executor = create_agent_executor(callbacks=[callback])
 
+                    # Auto-inject Experiential Learning memory into context if matches exist
+                    enriched_content = inject_experiential_memory(content)
+
                     # Invoke agent compiled StateGraph using messages schema
                     inputs = {
-                        "messages": chat_history + [HumanMessage(content=content)]
+                        "messages": chat_history + [HumanMessage(content=enriched_content)]
                     }
                     agent_response = await agent_executor.ainvoke(inputs)
 
@@ -306,7 +377,6 @@ async def websocket_endpoint(
 
                     # Auto-index approved command output into RAG knowledge base
                     try:
-                        from app.modules.knowledge.service import index_command_output
                         index_command_output(server.name, action.command, stdout_str, stderr_str, exit_code)
                     except Exception:
                         pass
@@ -330,9 +400,12 @@ async def websocket_endpoint(
                             f"Please analyze these outputs and provide your final response to the user."
                         )
 
+                        # Auto-inject Experiential Learning memory into resume prompt
+                        enriched_resume = inject_experiential_memory(resume_prompt)
+
                         # Invoke the agent graph with the resume message
                         agent_response = await agent_executor.ainvoke({
-                            "messages": [HumanMessage(content=resume_prompt)]
+                            "messages": [HumanMessage(content=enriched_resume)]
                         })
 
                         ai_text = agent_response["messages"][-1].content

{devops_copilot-0.1.0 → devops_copilot-0.1.1}/app/modules/knowledge/service.py

@@ -5,10 +5,11 @@ from typing import List, Optional
 # Shared ChromaDB persistent client (same data volume as guardrails)
 client = chromadb.PersistentClient(path="data/chroma_db")
 
-# --- 3 Separate Collections ---
+# --- 4 Separate Collections ---
 command_history = client.get_or_create_collection(name="command_history")
 server_logs = client.get_or_create_collection(name="server_logs")
 server_configs = client.get_or_create_collection(name="server_configs")
+lessons_learned = client.get_or_create_collection(name="lessons_learned")
 
 CHUNK_SIZE = 500
 CHUNK_OVERLAP = 50
@@ -84,11 +85,61 @@ def index_config(server_name: str, file_path: str, content: str):
         )
 
 
+def index_lesson_learned(
+    server_name: str,
+    problem: str,
+    real_cause: str,
+    what_didnt_work: str,
+    what_worked: str,
+    time_to_resolve: str
+):
+    """Index a structured post-incident postmortem (Experiential Learning / ExpeL) into lessons_learned."""
+    doc = (
+        f"Problem: {problem}\n"
+        f"Real Cause: {real_cause}\n"
+        f"What didn't work: {what_didnt_work}\n"
+        f"What worked: {what_worked}\n"
+        f"Time to Resolve: {time_to_resolve}"
+    )
+    metadata = {
+        "server_name": server_name,
+        "problem": problem,
+        "real_cause": real_cause,
+        "what_worked": what_worked,
+        "time_to_resolve": time_to_resolve,
+        "source": "lessons_learned",
+    }
+    lessons_learned.add(
+        ids=[f"lsn_{uuid.uuid4().hex[:12]}"],
+        documents=[doc],
+        metadatas=[metadata],
+    )
+
+
+def search_lessons_learned(query: str, n_results: int = 3) -> str:
+    """Semantic search specifically across structured past lessons learned."""
+    if lessons_learned.count() == 0:
+        return "No lessons learned recorded yet in the vector database."
+    
+    results = lessons_learned.query(query_texts=[query], n_results=min(n_results, lessons_learned.count()))
+    if not results or not results["documents"] or not results["documents"][0]:
+        return "No matching lessons learned found."
+    
+    cards = []
+    for doc, meta in zip(results["documents"][0], results["metadatas"][0]):
+        cards.append(
+            f"[Lesson Learned - Server: {meta.get('server_name', '?')}]\n"
+            f"{doc}"
+        )
+    return "\n\n---\n\n".join(cards)
+
+
 # Map collection name -> collection object
 _COLLECTIONS = {
     "command_history": command_history,
     "server_logs": server_logs,
     "server_configs": server_configs,
+    "lessons_learned": lessons_learned,
 }
 
 

devops_copilot-0.1.1/devops_copilot.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: devops-copilot
+Version: 0.1.1
+Summary: An AI-driven DevOps Copilot and CLI Client for managing bare-metal servers securely
+Author: irzix
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: server
+Requires-Dist: fastapi>=0.111.0; extra == "server"
+Requires-Dist: uvicorn>=0.30.0; extra == "server"
+Requires-Dist: sqlmodel>=0.0.22; extra == "server"
+Requires-Dist: pyjwt>=2.8.0; extra == "server"
+Requires-Dist: aiosqlite>=0.20.0; extra == "server"
+Requires-Dist: cryptography>=42.0.0; extra == "server"
+Requires-Dist: langchain>=0.2.0; extra == "server"
+Requires-Dist: chromadb>=0.5.0; extra == "server"
+Requires-Dist: pydantic-settings>=2.2.0; extra == "server"
+Requires-Dist: bcrypt>=4.1.0; extra == "server"
+Requires-Dist: python-multipart>=0.0.9; extra == "server"
+Requires-Dist: greenlet>=3.0.0; extra == "server"
+Requires-Dist: langchain-openai>=0.1.0; extra == "server"
+Requires-Dist: asyncssh>=2.14.0; extra == "server"
+
+# DevOps Copilot 🚀
+
+**An autonomous, self-learning AI DevOps Assistant & CLI Client that manages bare-metal servers with Experiential Memory (`ExpeL`), Semantic Guardrails, and Real-Time SSH Tunneling.**
+
+---
+
+## 💡 About The Project
+
+Managing infrastructure via traditional CLI tools or basic AI wrappers often leads to dangerous mistakes, repetitive debugging dead-ends, and fragmented server logs. **DevOps Copilot** redefines server management by bringing **Closed-Loop Experiential Learning (ExpeL)** directly to your terminal.
+
+Unlike standard AI chat wrappers that forget previous troubleshooting sessions, `DevOps Copilot` builds a permanent, structured **ChromaDB Vector Knowledge Base** of your infrastructure:
+
+- **🧠 Zero-Click Experiential Learning (ExpeL & Reflexion):** Every time an incident or bug is diagnosed and resolved, the agent distills the entire session into a structured Postmortem (`Problem`, `Real Cause`, `What didn't work`, `What worked`). Before tackling new errors, relevant past lessons are **automatically retrieved and injected** into the agent's context—ensuring it *never repeats a dead end*.
+- **🛡️ Semantic Security Guardrails:** Local vector search intercepts and blocks catastrophic shell commands (e.g., `rm -rf /`, `mkfs`) before they ever touch your servers.
+- **🧑‍💻 Human-in-the-Loop (HITL) Approvals:** State-modifying actions dynamically prompt for explicit admin confirmation (`[y/N]`) inside the terminal with clean prompt synchronization.
+- **⚡ Real-Time Async Execution Tunnel:** Streams LLM reasoning, SSH `stdout`, and `stderr` line-by-line via resilient WebSockets with automatic reconnection and exponential backoff.
+- **🔒 Zero-Trust Credential Encryption:** Passwords and SSH private keys are encrypted at rest using AES-256 (`Fernet`).
+
+---
+
+## 🏛️ System Architecture & ExpeL Loop
+
+```
++-----------------------------------------------------------------------------------+
+|                                 DevOps Copilot CLI                                |
+|  (Typer Async Client + Real-Time WebSocket Tunnel + [y/N] Terminal Approval)      |
++-----------------------------------------------------------------------------------+
+                                   |           ^
+                   REST Auth/CRUD  |           | WebSocket Stream (stdout/stderr)
+                                   v           |
++-----------------------------------------------------------------------------------+
+|                              FastAPI Backend Server                               |
+|                                                                                   |
+|  +------------------------+   +-----------------------+   +--------------------+  |
+|  |     Auth Module        |   |    Servers Module     |   | Guardrails Module  |  |
+|  |  (JWT & AES Fernet)    |   |  (AsyncSSH Execution) |   | (Vector Blacklist) |  |
+|  +------------------------+   +-----------------------+   +--------------------+  |
+|                                                                                   |
+|  +-----------------------------------------------------------------------------+  |
+|  |                              Chat & Agent Module                            |  |
+|  |   LangChain StateGraph + Zero-Click ExpeL Injection + OpenRouter LLM        |  |
+|  +-----------------------------------------------------------------------------+  |
+|                                       |                                           |
+|                                       v                                           |
+|  +-----------------------------------------------------------------------------+  |
+|  |                            Knowledge Base (ChromaDB)                        |  |
+|  |  [command_history]   [server_logs]   [server_configs]   [lessons_learned]   |  |
+|  +-----------------------------------------------------------------------------+  |
++-----------------------------------------------------------------------------------+
+```
+
+### The Closed-Loop Experiential Learning (`ExpeL`) Flow:
+1. **Observe & Act:** Agent connects via `AsyncSSH`, runs non-destructive diagnostics or approved actions, and indexes outputs into `command_history` and `server_logs`.
+2. **Judge & Extract:** When an incident is resolved, running `devops-copilot lesson <session_id>` triggers an automated LLM extraction (`Problem`, `Real Cause`, `What didn't work`, `What worked`) stored in `lessons_learned`.
+3. **Zero-Click Injection (Future Decision):** On any future chat turn or command error, the `inject_experiential_memory` middleware queries `lessons_learned` and injects proven solutions directly into the prompt context.
+
+---
+
+## Key Features
+- **Experiential Learning (ExpeL / Reflexion Postmortems):** Distills complex debugging sessions into structured `Lessons Learned` cards indexed into ChromaDB with zero-click context injection.
+- **Lean RAG Knowledge Base:** Automatically chunks and indexes executed SSH command outputs, logs, and server configs into separate **ChromaDB** collections.
+- **Semantic Guardrails:** Uses local vector search to intercept and block dangerous terminal commands.
+- **Human-in-the-Loop (HITL):** Enforces admin approval (`[y/N]`) inside the terminal for any state-modifying actions.
+- **CLI Connection Resilience:** Automatically reconnects to the WebSocket server using exponential backoff if the network drops or the server restarts.
+- **Real-Time Streaming:** Streams LLM thoughts and active SSH `stdout`/`stderr` line-by-line using WebSockets with 30s execution timeouts.
+- **Encrypted Credentials:** Securely encrypts passwords and SSH private keys using Fernet (AES-256).
+- **Server & Session CRUD:** Full REST API support for updating/deleting server connections and deleting chat sessions.
+- **Flexible AI Models:** Powered by **OpenRouter** (supports Llama 3, Gemini, GPT, etc.).
+
+---
+
+## 📦 Quick Start (Backend Server)
+
+### 1. Configure Settings
+Copy the env file and populate keys:
+```bash
+cp .env.example .env
+```
+Make sure to add your `OPENROUTER_API_KEY` and a custom base64 `ENCRYPTION_KEY` in `.env`.
+
+### 2. Run with Docker Compose
+```bash
+docker compose up -d --build
+```
+The server will boot on port `8000`. Database tables and security blacklist vectors are automatically seeded on startup.
+
+---
+
+## 💻 Quick Start (CLI Client)
+
+### 1. Install Globally
+Install the package in editable mode from your local repository root:
+```bash
+uv pip install -e .
+```
+
+### 2. Authenticate
+Configure the server URL and log in to get your JWT access token:
+```bash
+devops-copilot login
+```
+
+### 3. Interactive Chat & Auto-Postmortems
+Start the real-time DevOps chat session:
+```bash
+devops-copilot chat
+```
+*Ask the agent to check stats or run actions. Approve state-modifying commands directly in the prompt.*
+
+Extract and index a structured Experiential Lesson Learned from any completed troubleshooting session:
+```bash
+devops-copilot lesson <session_id>
+```

{devops_copilot-0.1.0 → devops_copilot-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devops-copilot"
-version = "0.1.0"
+version = "0.1.1"
 description = "An AI-driven DevOps Copilot and CLI Client for managing bare-metal servers securely"
 readme = "README.md"
 requires-python = ">=3.12"

devops_copilot-0.1.0/PKG-INFO

@@ -1,81 +0,0 @@
-Metadata-Version: 2.4
-Name: devops-copilot
-Version: 0.1.0
-Summary: An AI-driven DevOps Copilot and CLI Client for managing bare-metal servers securely
-Author: irzix
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-Requires-Dist: typer>=0.12.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: websockets>=12.0
-Provides-Extra: server
-Requires-Dist: fastapi>=0.111.0; extra == "server"
-Requires-Dist: uvicorn>=0.30.0; extra == "server"
-Requires-Dist: sqlmodel>=0.0.22; extra == "server"
-Requires-Dist: pyjwt>=2.8.0; extra == "server"
-Requires-Dist: aiosqlite>=0.20.0; extra == "server"
-Requires-Dist: cryptography>=42.0.0; extra == "server"
-Requires-Dist: langchain>=0.2.0; extra == "server"
-Requires-Dist: chromadb>=0.5.0; extra == "server"
-Requires-Dist: pydantic-settings>=2.2.0; extra == "server"
-Requires-Dist: bcrypt>=4.1.0; extra == "server"
-Requires-Dist: python-multipart>=0.0.9; extra == "server"
-Requires-Dist: greenlet>=3.0.0; extra == "server"
-Requires-Dist: langchain-openai>=0.1.0; extra == "server"
-Requires-Dist: asyncssh>=2.14.0; extra == "server"
-
-# DevOps-Copilot 🚀
-
-An open-source, AI-driven DevOps Copilot and CLI Client designed to manage raw root/bare-metal servers securely. It features persistent credential encryption, real-time terminal streaming, and semantic security guardrails using a local vector database.
-
----
-
-## Key Features
-- **Lean RAG Knowledge Base:** Automatically chunks and indexes executed SSH command outputs, logs, and server configs into separate **ChromaDB** collections, enabling the agent to search past server history before executing new commands.
-- **Semantic Guardrails:** Uses local vector search to intercept and block dangerous terminal commands.
-- **Human-in-the-Loop (HITL):** Enforces admin approval (`[y/N]`) inside the terminal for any state-modifying actions with clean prompt synchronization.
-- **CLI Connection Resilience:** Automatically reconnects to the WebSocket server using exponential backoff if the network drops or the server restarts.
-- **Real-Time Streaming:** Streams LLM thoughts and active SSH `stdout`/`stderr` line-by-line using WebSockets with 30s execution timeouts.
-- **Encrypted Credentials:** Securely encrypts passwords and SSH private keys using Fernet (AES-256).
-- **Server & Session CRUD:** Full REST API support for updating/deleting server connections and deleting chat sessions (with cascade cleanup).
-- **Flexible AI Models:** Powered by **OpenRouter** (supports Llama 3, Gemini, GPT, etc.).
-
----
-
-## 📦 Quick Start (Backend Server)
-
-### 1. Configure Settings
-Copy the env file and populate keys:
-```bash
-cp .env.example .env
-```
-Make sure to add your `OPENROUTER_API_KEY` and a custom base64 `ENCRYPTION_KEY` in `.env`.
-
-### 2. Run with Docker Compose
-```bash
-docker compose up -d --build
-```
-The server will boot on port `8000`. Database tables and security blacklist vectors are automatically seeded on startup.
-
----
-
-## 💻 Quick Start (CLI Client)
-
-### 1. Install Globally
-Install the package in editable mode from your local repository root:
-```bash
-uv pip install -e .
-```
-
-### 2. Authenticate
-Configure the server URL and log in to get your JWT access token:
-```bash
-devops-copilot login
-```
-
-### 3. Interactive Chat
-Start the real-time DevOps chat session:
-```bash
-devops-copilot chat
-```
-*Ask the agent to check stats or run actions. Approve state-modifying commands directly in the prompt.*

devops_copilot-0.1.0/README.md

@@ -1,55 +0,0 @@
-# DevOps-Copilot 🚀
-
-An open-source, AI-driven DevOps Copilot and CLI Client designed to manage raw root/bare-metal servers securely. It features persistent credential encryption, real-time terminal streaming, and semantic security guardrails using a local vector database.
-
----
-
-## Key Features
-- **Lean RAG Knowledge Base:** Automatically chunks and indexes executed SSH command outputs, logs, and server configs into separate **ChromaDB** collections, enabling the agent to search past server history before executing new commands.
-- **Semantic Guardrails:** Uses local vector search to intercept and block dangerous terminal commands.
-- **Human-in-the-Loop (HITL):** Enforces admin approval (`[y/N]`) inside the terminal for any state-modifying actions with clean prompt synchronization.
-- **CLI Connection Resilience:** Automatically reconnects to the WebSocket server using exponential backoff if the network drops or the server restarts.
-- **Real-Time Streaming:** Streams LLM thoughts and active SSH `stdout`/`stderr` line-by-line using WebSockets with 30s execution timeouts.
-- **Encrypted Credentials:** Securely encrypts passwords and SSH private keys using Fernet (AES-256).
-- **Server & Session CRUD:** Full REST API support for updating/deleting server connections and deleting chat sessions (with cascade cleanup).
-- **Flexible AI Models:** Powered by **OpenRouter** (supports Llama 3, Gemini, GPT, etc.).
-
----
-
-## 📦 Quick Start (Backend Server)
-
-### 1. Configure Settings
-Copy the env file and populate keys:
-```bash
-cp .env.example .env
-```
-Make sure to add your `OPENROUTER_API_KEY` and a custom base64 `ENCRYPTION_KEY` in `.env`.
-
-### 2. Run with Docker Compose
-```bash
-docker compose up -d --build
-```
-The server will boot on port `8000`. Database tables and security blacklist vectors are automatically seeded on startup.
-
----
-
-## 💻 Quick Start (CLI Client)
-
-### 1. Install Globally
-Install the package in editable mode from your local repository root:
-```bash
-uv pip install -e .
-```
-
-### 2. Authenticate
-Configure the server URL and log in to get your JWT access token:
-```bash
-devops-copilot login
-```
-
-### 3. Interactive Chat
-Start the real-time DevOps chat session:
-```bash
-devops-copilot chat
-```
-*Ask the agent to check stats or run actions. Approve state-modifying commands directly in the prompt.*

devops_copilot-0.1.0/devops_copilot.egg-info/PKG-INFO

@@ -1,81 +0,0 @@
-Metadata-Version: 2.4
-Name: devops-copilot
-Version: 0.1.0
-Summary: An AI-driven DevOps Copilot and CLI Client for managing bare-metal servers securely
-Author: irzix
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-Requires-Dist: typer>=0.12.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: websockets>=12.0
-Provides-Extra: server
-Requires-Dist: fastapi>=0.111.0; extra == "server"
-Requires-Dist: uvicorn>=0.30.0; extra == "server"
-Requires-Dist: sqlmodel>=0.0.22; extra == "server"
-Requires-Dist: pyjwt>=2.8.0; extra == "server"
-Requires-Dist: aiosqlite>=0.20.0; extra == "server"
-Requires-Dist: cryptography>=42.0.0; extra == "server"
-Requires-Dist: langchain>=0.2.0; extra == "server"
-Requires-Dist: chromadb>=0.5.0; extra == "server"
-Requires-Dist: pydantic-settings>=2.2.0; extra == "server"
-Requires-Dist: bcrypt>=4.1.0; extra == "server"
-Requires-Dist: python-multipart>=0.0.9; extra == "server"
-Requires-Dist: greenlet>=3.0.0; extra == "server"
-Requires-Dist: langchain-openai>=0.1.0; extra == "server"
-Requires-Dist: asyncssh>=2.14.0; extra == "server"
-
-# DevOps-Copilot 🚀
-
-An open-source, AI-driven DevOps Copilot and CLI Client designed to manage raw root/bare-metal servers securely. It features persistent credential encryption, real-time terminal streaming, and semantic security guardrails using a local vector database.
-
----
-
-## Key Features
-- **Lean RAG Knowledge Base:** Automatically chunks and indexes executed SSH command outputs, logs, and server configs into separate **ChromaDB** collections, enabling the agent to search past server history before executing new commands.
-- **Semantic Guardrails:** Uses local vector search to intercept and block dangerous terminal commands.
-- **Human-in-the-Loop (HITL):** Enforces admin approval (`[y/N]`) inside the terminal for any state-modifying actions with clean prompt synchronization.
-- **CLI Connection Resilience:** Automatically reconnects to the WebSocket server using exponential backoff if the network drops or the server restarts.
-- **Real-Time Streaming:** Streams LLM thoughts and active SSH `stdout`/`stderr` line-by-line using WebSockets with 30s execution timeouts.
-- **Encrypted Credentials:** Securely encrypts passwords and SSH private keys using Fernet (AES-256).
-- **Server & Session CRUD:** Full REST API support for updating/deleting server connections and deleting chat sessions (with cascade cleanup).
-- **Flexible AI Models:** Powered by **OpenRouter** (supports Llama 3, Gemini, GPT, etc.).
-
----
-
-## 📦 Quick Start (Backend Server)
-
-### 1. Configure Settings
-Copy the env file and populate keys:
-```bash
-cp .env.example .env
-```
-Make sure to add your `OPENROUTER_API_KEY` and a custom base64 `ENCRYPTION_KEY` in `.env`.
-
-### 2. Run with Docker Compose
-```bash
-docker compose up -d --build
-```
-The server will boot on port `8000`. Database tables and security blacklist vectors are automatically seeded on startup.
-
----
-
-## 💻 Quick Start (CLI Client)
-
-### 1. Install Globally
-Install the package in editable mode from your local repository root:
-```bash
-uv pip install -e .
-```
-
-### 2. Authenticate
-Configure the server URL and log in to get your JWT access token:
-```bash
-devops-copilot login
-```
-
-### 3. Interactive Chat
-Start the real-time DevOps chat session:
-```bash
-devops-copilot chat
-```
-*Ask the agent to check stats or run actions. Approve state-modifying commands directly in the prompt.*