README.md

---
title: Florentine Families Graph
emoji: 🌍
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.12.0
app_file: app.py
pinned: false
license: cc-by-sa-4.0
---

Here’s a compelling README for your application:

---

# Florentine Families Network Analysis

Welcome to the **Florentine Families Network Analysis Tool**
- a simple yet powerful prototype designed to analyze the [Florentine family network](https://networkx.org/documentation/stable/reference/generated/networkx.generators.social.florentine_families_graph.html#) using graph-based metrics.
- integrates **Smolagents**, **Arize Phoenix**, and **NetworkX** to explore the relationships and centrality dynamics of Renaissance-era Florence families.
- the `app.py` code is a little out of date but I left it `as is` as it showcased where effective telemetry can bring immediate visibility to the impact of minor changes in the tool definition

NOTE: Smolagents has some cool features like [reusable tools](https://huggingface.co/spaces/dwb2023/florentine-families-graph/blob/main/huggingface_spaces_tool_template.md) - but as expected there are some growing pains

## Key Features

### 1. **Smolagents for Agentic Intelligence**
   - Employs **Smolagents** to power agentic workflows with multi-step reasoning and secure code execution.
   - Uses the **CodeAgent** to execute Python-based tool calls, enabling dynamic interactions with graph data.
   - Integrates tools like centrality calculators and visualization functions, allowing users to explore the network effectively.

### 2. **NetworkX for Graph Analysis**
   - Leverages the **Florentine Families** dataset from **NetworkX**, a classic representation of Renaissance family alliances.
   - Computes critical centrality metrics such as:
     - **Degree Centrality**: Identifies the most connected families.
     - **Betweenness Centrality**: Highlights families bridging other relationships.
     - **Closeness Centrality**: Finds families with optimal influence in the network.
   - Provides visual insights into the network structure, helping uncover pivotal roles in Florence's social fabric.

### 3. **Arize Phoenix for Telemetry and Debugging**
   - Integrates with **Arize Phoenix** via OpenTelemetry, ensuring robust tracking and inspection of agent workflows.
   - Logs agent actions, tool calls, and errors, enabling users to debug and optimize their queries.
   - Supports analysis of user interactions and system performance through intuitive dashboards.

### 4. **Interactive Gradio Interface**
   - Provides a user-friendly interface for inputting queries and viewing results.
   - Predefined examples guide users to explore the centrality roles of key families like the Medici and Strozzi.
   - Displays results in textual and visual formats for enhanced comprehension.

---

## How It Works

1. **Input Your Query**: Use natural language to describe your analysis goals (e.g., *"Highlight the Medici family's role using betweenness centrality."*).
2. **Agentic Reasoning**: The **CodeAgent** formulates the necessary computations and retrieves insights using NetworkX and predefined tools.
3. **Graph Analysis**: Metrics are computed and analyzed in real-time, with visualizations optionally generated using tools like **PyVis**.
4. **Telemetry Monitoring**: Every interaction is logged and monitored via Arize Phoenix, providing transparency and debugging capabilities.

---

## Examples

### Analyze Medici's Central Role
```text
"Highlight the Medici family's central role in the network using all three centrality metrics."
```

### Explore the Strozzi Family
```text
"Focus on the Strozzi family's role in the network using betweenness centrality."
```

### Compare Families
```text
"Compare family positions in the network using degree and closeness centrality."
```
#### Overview of 6 CodeAgent runs

![arize-phonix-telemetry](arize_pheonix_6_codeagent_runs.png)

#### Code Generated to create HTML

![arize-phoenix-telemetry-detail-code-html](arize_phoenix_file_image_html.png)

##### HTML Output

![html-output](centrality_network.html)


---

## Setup Instructions

### Prerequisites
- Python 3.8 or higher
- Hugging Face API Token (`HF_TOKEN`)
- Arize Phoenix API Key (`PHOENIX_API_KEY`)

### Installation
1. Clone this repository.
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
3. Export environment variables:
   ```bash
   export HF_TOKEN=your_hf_api_token
   export PHOENIX_API_KEY=your_phoenix_api_key
   ```

4. Run the app:
   ```bash
   python app.py
   ```

---

## Technology Stack

- **Smolagents**: For agentic workflows and secure execution.
- **NetworkX**: For robust graph-based computations.
- **Arize Phoenix**: For monitoring and telemetry via OpenTelemetry.
- **Gradio**: For an intuitive user interface.
- **PyVis**: For interactive graph visualizations.

---

## Contributing

We welcome contributions! Please submit issues or pull requests for enhancements or bug fixes.

---

## License

This project is licensed under cc-by-sa-4.0.

---

## Acknowledgments

- Smolagents by Hugging Face
- NetworkX for their graph library and Florentine family dataset
- Arize Phoenix for telemetry insights that accelerated the alignment of LLM behavior