Agent.md

# Agent.md

## 1. Deployment Configuration

### Target Space
- **Profile:** `AUXteam`  
- **Space:** `tiny_factory`  
- **Full Identifier:** `AUXteam/tiny_factory`  
- **Frontend Port:** `7860` (mandatory for all Hugging Face Spaces)

### Deployment Method
Choose the correct SDK based on the app type based on the codebase language:

- **Gradio SDK** — for Gradio applications  
- **Streamlit SDK** — for Streamlit applications  
- **Docker SDK** — for all other applications (recommended default for flexibility)

### HF Token
- The environment variable **`$HF_TOKEN` will always be provided at execution time**.
- Never hardcode the token. Always read it from the environment.
- All monitoring and log‑streaming commands rely on `$HF_TOKEN`.

### Required Files
- `Dockerfile`
- `README.md` with Hugging Face YAML frontmatter:
  ```yaml
  ---
  title: Tiny Factory
  sdk: docker
  app_port: 7860
  ---
  ```
- `.hfignore` to exclude unnecessary files
- This `Agent.md` file (must be committed before deployment)

---

## 2. API Exposure and Documentation

### Mandatory Endpoints
Every deployment **must** expose:

- **`/health`**  
  - Returns HTTP 200 when the app is ready.  
  - Required for Hugging Face to transition the Space from *starting* → *running*.

- **`/api-docs`**  
  - Documents **all** available API endpoints.  
  - Must be reachable at:  
    `https://HF_PROFILE-tiny_factory.hf.space/api-docs`

### Functional Endpoints
Documented endpoints:

### /api/v1/generate_personas
- Method: POST
- Purpose: Generates a list of personas using a double sequential generation pipeline (extracting parameters via an LLM and generating using a remote model).
- Request:
  ```json
  {
    "business_description": "Tech startup",
    "customer_profile": "Young professionals",
    "num_personas": 1
  }
  ```
- Response:
  ```json
  [
    {
      "parameters_used": {
        "age": 30,
        "gender": "Non-binary",
        "occupation": "Professional",
        "city": "Metropolis",
        "country": "Country",
        "custom_values": "Innovation, Community",
        "custom_life_attitude": "Optimistic",
        "life_story": "A standard professional background with a passion for their field.",
        "interests_hobbies": "Technology, Reading",
        "attribute_count": 200
      },
      "persona_profile": "Profile text generated by external API"
    }
  ]
  ```

All endpoints listed here **must** appear in `/api-docs`.

---

## 3. Deployment Workflow

### Standard Deployment Command
After any code change, run:

```bash
hf upload AUXteam/tiny_factory --repo-type=space
```

This command must be executed **after updating and committing Agent.md**.

### Deployment Steps
1. Ensure all code changes are committed.  
2. Ensure `Agent.md` is updated and committed.  
3. Run the upload command.  
4. Wait for the Space to build.  
5. Monitor logs (see next section).  
6. When the Space is running, execute all test cases.

### Continuous Deployment Rule
After **every** relevant edit (logic, dependencies, API changes):

- Update `Agent.md`
- Redeploy using the upload command
- Re-run all test cases
- Confirm `/health` and `/api-docs` are functional

This applies even for long-running projects.

---

## 4. Monitoring and Logs

### Build Logs (SSE)
```bash
curl -N \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/spaces/AUXteam/tiny_factory/logs/build"
```

### Run Logs (SSE)
```bash
curl -N \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/spaces/AUXteam/tiny_factory/logs/run"
```

### Notes
- If the Space stays in *starting* for too long, `/health` is usually failing.  
- If the Space times out after ~30 minutes, check logs immediately.  
- Fix issues, commit changes, redeploy.

---

## 5. Test Run Cases (Mandatory After Every Deployment)

These tests ensure the agentic system can verify the deployment automatically.

### 1. Health Check
```
GET https://HF_PROFILE-tiny_factory.hf.space/health
Expected: HTTP 200, body: {"status": "ok"} or similar
```

### 2. API Docs Check
```
GET https://HF_PROFILE-tiny_factory.hf.space/api-docs
Expected: HTTP 200, valid documentation UI or JSON spec
```

### 3. Functional Endpoint Tests
For each endpoint documented above, define:

- Example request
- Expected response structure
- Validation criteria (e.g., non-empty output, valid JSON)

Example:

```
POST https://HF_PROFILE-tiny_factory.hf.space/api/v1/generate_personas
Payload:
{
  "business_description": "test",
  "customer_profile": "test",
  "num_personas": 1
}
Expected:
- HTTP 200
- JSON Array of generated profiles
- Each element containing "parameters_used" and "persona_profile"
```

### 4. End-to-End Behaviour
- Confirm the UI loads (if applicable)
- Confirm API endpoints respond within reasonable time
- Confirm no errors appear in run logs

---

## 6. Maintenance Rules

- `Agent.md` must always reflect the **current** deployment configuration, API surface, and test cases.
- Any change to:
  - API routes  
  - Dockerfile  
  - Dependencies  
  - App logic  
  - Deployment method  
  requires updating this file.
- This file must be committed **before** every deployment.
- This file is the operational contract for autonomous agents interacting with the project.