feat: Initial commit of the reflection agent service

Author: PryskaS

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+# File: .github/workflows/ci.yml
+name: Code Quality and Tests
+
+# This workflow runs on every push to the main branch
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build-and-test:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    steps:
+      # Step 1: Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # Step 2: Set up a specific version of Python
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # Step 3: Install dependencies from our requirements.txt
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -e .
+
+      # Step 4: Lint the code with Ruff for style and quality checks
+      - name: Lint with Ruff
+        run: |
+          ruff check .
+
+      # Step 5: Run the unit tests with Pytest
+      - name: Test with Pytest
+        run: |
+          pytest

.gitinore

@@ -0,0 +1,22 @@
+# --- Secrets ---
+# The golden rule: never commit secrets.
+.env
+
+# --- Python Cache & Compiled Files ---
+# These are generated automatically by the Python interpreter.
+__pycache__/
+*.pyc
+
+# --- Python Build & Installation Artifacts ---
+# Generated by setuptools/pip when installing in editable mode.
+*.egg-info/
+build/
+dist/
+
+# --- Testing Artifacts ---
+# Cache generated by pytest to speed up tests.
+.pytest_cache/
+
+# --- IDE/Editor Specific ---
+# VSCode specific files
+.vscode/

Dockerfile

@@ -0,0 +1,22 @@
+# Stage 1: Use an official lightweight Python image as a parent image
+FROM python:3.12-slim
+
+# Set the working directory inside the container
+WORKDIR /app
+
+# Copy the file with dependencies first
+COPY requirements.txt .
+
+# Install the dependencies
+# --no-cache-dir makes the image smaller
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of application code into the container
+COPY . .
+
+# Tell Docker that the container will listen on port 8001
+EXPOSE 8001
+
+# The command to run application when the container starts
+# Use 0.0.0.0 to make the server accessible from outside the container
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8001"]

__pycache__/main.cpython-312.pyc

@@ -0,0 +1,120 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "75d3bee5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# We install the necessary libraries directly from the notebook.\n",
+    "# The '!' allows us to run shell commands.\n",
+    "!pip install openai python-dotenv"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ee51e92d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from dotenv import load_dotenv\n",
+    "\n",
+    "# Import our custom agent class\n",
+    "from reflection_pattern_agent.reflection_agent import ReflectionAgent\n",
+    "\n",
+    "# Load environment variables from the .env file\n",
+    "# This is where we securely load our OPENAI_API_KEY\n",
+    "load_dotenv()\n",
+    "\n",
+    "print(\"Libraries and agent class imported successfully.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9e2757f1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# 1. Instantiate the agent\n",
+    "# This will automatically pick up the API key from the environment\n",
+    "agent = ReflectionAgent()\n",
+    "\n",
+    "# 2. Define a simple prompt to test the generation\n",
+    "test_prompt = \"Write a short, engaging tweet about the importance of MLOps.\"\n",
+    "\n",
+    "# 3. Call the generate method\n",
+    "print(\"--- Calling the generate method... ---\")\n",
+    "initial_draft = agent.generate(prompt=test_prompt)\n",
+    "\n",
+    "# 4. Print the result\n",
+    "print(\"\\n--- Initial Draft Generated ---\")\n",
+    "print(initial_draft)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a42e570b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# --- Full Cycle Integration Test ---\n",
+    "\n",
+    "# 1. Define a more complex task where reflection can make a real difference.\n",
+    "complex_prompt = \"\"\"\n",
+    "Write a short paragraph for a LinkedIn post announcing a new feature\n",
+    "for our project management tool. The feature is an AI-powered assistant\n",
+    "that automatically suggests the next task for a user based on their\n",
+    "project's progress and priorities. Mention the key benefit:\n",
+    "it helps reduce decision fatigue for team leads.\n",
+    "\"\"\"\n",
+    "\n",
+    "# 2. Execute the full run cycle\n",
+    "initial_draft, reflections, final_output = agent.run(prompt=complex_prompt)\n",
+    "\n",
+    "# 3. Analyze the results\n",
+    "print(\"\\n\" + \"=\"*50)\n",
+    "print(\"INITIAL DRAFT\")\n",
+    "print(\"=\"*50)\n",
+    "print(initial_draft)\n",
+    "\n",
+    "print(\"\\n\" + \"=\"*50)\n",
+    "print(\"REFLECTIONS\")\n",
+    "print(\"=\"*50)\n",
+    "# Print reflections as a bulleted list\n",
+    "for r in reflections:\n",
+    "    print(f\"- {r}\")\n",
+    "\n",
+    "print(\"\\n\" + \"=\"*50)\n",
+    "print(\"FINAL REFINED OUTPUT\")\n",
+    "print(\"=\"*50)\n",
+    "print(final_output)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "reflection_agent",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

__pycache__/reflection_agent.cpython-312.pyc

@@ -0,0 +1,69 @@
+import logging
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+from typing import List
+
+# Load environment variables from a .env file
+load_dotenv()
+
+# Import core logic
+from reflection_pattern_agent.reflection_agent import ReflectionAgent
+
+# Set up logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+# --- The API Contract (Pydantic Models) ---
+
+class RunRequest(BaseModel):
+    prompt: str = Field(
+        ...,
+        description="The initial prompt for the agent to process.",
+        example="Write a tweet about the future of AI agents."
+    )
+
+class RunResponse(BaseModel):
+    initial_draft: str
+    reflections: List[str]
+    final_output: str
+
+# --- FastAPI Application Setup ---
+app = FastAPI(
+    title="Reflection Agent Service",
+    description="An API to access an AI agent that uses the reflection pattern to improve its output.",
+    version="1.0.0"
+)
+
+# --- API Endpoints ---
+
+# Basic health check endpoint
+@app.get("/health", tags=["Monitoring"])
+def health_check():
+    """Checks if the service is running."""
+    return {"status": "ok"}
+
+@app.post("/run", response_model=RunResponse, tags=["Agent Logic"])
+def execute_agent_run(request: RunRequest):
+    """
+    Executes the full generate-reflect-generate cycle of the agent.
+    """
+    try:
+        logger.info(f"Received request for prompt: '{request.prompt[:50]}...'") # Log de início
+        agent = ReflectionAgent()
+        initial_draft, reflections, final_output = agent.run(request.prompt)
+
+        if initial_draft is None:
+            logger.error("Agent failed to generate an initial draft.")
+            raise HTTPException(status_code=500, detail="Agent failed to generate an initial draft.")
+
+        logger.info("Successfully completed agent run.") # Log de sucesso
+        return RunResponse(
+            initial_draft=initial_draft,
+            reflections=reflections,
+            final_output=final_output
+        )
+    except Exception as e:
+        # ESTA É A MUDANÇA MAIS IMPORTANTE
+        logger.exception("An unhandled exception occurred during agent run.")
+        raise HTTPException(status_code=500, detail=f"An internal error occurred: {str(e)}")

lab_reflection_agent.ipynb

@@ -0,0 +1,18 @@
+[project]
+name = "reflection_pattern_agent"
+version = "0.1.0"
+authors = [
+    { name="Priscila Santos", email="priscila.olimpia@gmail.com" },
+]
+description = "An agentic pattern for self-reflection and output improvement."
+readme = "README.md"  # TO DO add a README file
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["reflection_pattern_agent*"]

main.py

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: reflection_pattern_agent
+Version: 0.1.0
+Summary: An agentic pattern for self-reflection and output improvement.
+Author-email: Seu Nome <seu@email.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown

pyproject.toml

@@ -0,0 +1,8 @@
+pyproject.toml
+reflection_pattern_agent/__init__.py
+reflection_pattern_agent/reflection_agent.py
+reflection_pattern_agent.egg-info/PKG-INFO
+reflection_pattern_agent.egg-info/SOURCES.txt
+reflection_pattern_agent.egg-info/dependency_links.txt
+reflection_pattern_agent.egg-info/top_level.txt
+tests/test_reflection_agent.py