docs: update README files to enhance project structure and clarify...

AI Agent is a lightweight, modular backend built with **[`FastAPI`](https://fastapi.tiangolo.com/)** that exposes REST API endpoints for interacting with multiple AI sub-agents. 

It is designed to be easily extensible with support for different LLMs and OpenOP MCP servers.

It keeps a short per-session chat memory in Redis when `REDIS_URL` is set.

---

## Authentication

Every request carries the user's Keycloak access token (`Authorization: Bearer …`). The agent

passes it to the MCP server, which sends it to OEG, so the user's own roles decide what AI2 may

do. `AUTH_ENABLED=false` turns this off for platforms deployed without login.

## Repository layout

| Path | Contents |

|---|---|

| [`mcp_module/`](mcp_module/README.md) | MCP server |

| [`ai_agent/`](ai_agent/README.md) | AI Agent |

| [`deployment/docker/`](deployment/docker/README.md) | Docker Compose for both modules and Redis |

| [`deployment/helm/`](deployment/helm/README.md) | Helm chart, the same one the platform chart deploys |

| `tests/` | Unit tests for both modules (`pytest`) |

---

├── routes/                # API route definitions

│   ├── groq.py             # Groq-related endpoints

│   └── debug.py            # Debug / health endpoints

├── .env                   # Environment variables

├── prompts/               # System prompts for the agent and its memory

├── memory.py              # Redis session memory

├── security.py            # Bearer token check

├── app.py                 # Application entry point

├── Dockerfile

├── requirements.txt       # Python dependencies

```

### 1. Clone the Repository

```

git clone <your-repo-url>

cd ai_agent

git clone https://labs.etsi.org/rep/oop/code/ai2.git

cd ai2

```

### 2. Create a Virtual Environment (Recommended)

### 3. Install Dependencies

```

pip install -r requirements.txt

pip install -r ai_agent/requirements.txt

```

### 4. Configure Environment Variables

Follow these steps to set up and run the app locally.

Start the backend server using:

Start the backend server from the repository root using:

```

python -m ai_agent.app

GROQ_MODEL_NAME=qwen/qwen3.8-27b

```

Optional, with the defaults the compose file uses: `REDIS_URL` (`redis://redis:6379/0`),

`MEMORY_WINDOW_TURNS` (`10`) and `MEMORY_TTL_SECONDS` (`3600`) for the agent's session memory.

## Run

Start services

```

|-----------|-----------|

| mcp       | 8004      |

| ai-agent  | 9013      |

| redis     | 6385      |

---

 No newline at end of file

├── models/                  # Pydantic models for CAMARA API compliance or custom types

├── tools/                   # MCP tools registered as callable endpoints

├── security/                # Security-related module placeholders

├── security/                # Forwards the caller's bearer token to OEG

├── app.py

├── requirements.txt

└── Dockerfile

```

git clone https://labs.etsi.org/rep/oop/code/ai2.git

cd mcp_module

cd ai2

python3 -m venv venv

source venv/bin/activate  # (on Linux/macOS) venv\Scripts\activate     # (on Windows)

pip install -r requirements.txt

pip install -r mcp_module/requirements.txt

```

Create a `.env` file in the project root (if not already present) and set your API configuration:

Create a `.env` file in `mcp_module/` or the repository root (if not already present) and set your API configuration:

```

OEG_SERVICE_URL=http://your-oeg-host

Run the application with:

From the repository root:

```

python app.py

python -m mcp_module.app

```

By default, it runs on `127.0.0.1:8004` unless overridden by `MCP_HOST` and `MCP_PORT`.

3. Register the tool in `app.py`.

4. Add corresponding typed request models.

---

## Roadmap

Extend the MCP server with relevant prompts, tool call(s), and more comprehensive parameter assertions.