# Microsoft Concept Graph Architecture and Workflow in AI-For-Beginners: Complete Technical Guide

> Understand the Microsoft Concept Graph architecture and workflow with this technical guide. Learn how AI-For-Beginners uses ConceptNet as a replacement for the retired Microsoft Concept Graph API.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: architecture
- Published: 2026-08-20

---

**The AI-For-Beginners curriculum implements a drop-in replacement architecture using the open-source ConceptNet knowledge graph after the original Microsoft Concept Graph API was retired.**

The Microsoft Concept Graph (MCG) once powered a core Symbolic AI lesson in Microsoft's educational repository. When the API was deprecated, the maintainers re-engineered the integration around **ConceptNet** — a public, multilingual semantic network that requires no authentication. This article breaks down the complete architecture, workflow steps, and implementation code used in `lessons/2-Symbolic/MSConceptGraph.ipynb`.

---

## Historical Context: From Microsoft Concept Graph to ConceptNet

The original lesson demonstrated how to query hierarchical "is-a" relationships using Microsoft's proprietary knowledge graph. After the MCG API shutdown, the curriculum was refactored to preserve the same pedagogical outcomes while eliminating dependencies on deprecated services.

The replacement strategy prioritized three requirements:

- **Zero authentication overhead** — safe for classroom environments
- **API compatibility** — similar REST patterns and JSON responses
- **Global accessibility** — works across all translated versions of the curriculum

ConceptNet satisfied all criteria. The refactor maintained identical notebook structures across all 10+ language translations.

---

## Core Architecture Components

### Data Layer: ConceptNet REST API

ConceptNet exposes a public endpoint at `https://api.conceptnet.io/` with no API key required. The service supports semantic relationships including `IsA`, `PartOf`, `UsedFor`, `CapableOf`, and others.

Key characteristics relevant to the Microsoft Concept Graph architecture replacement:

| Feature | Implementation |
|---------|---------------|
| Base URL | `https://api.conceptnet.io/query` |
| Response format | JSON-LD |
| Rate limiting | None documented (appropriate for educational use) |
| Authentication | None required |

### Lesson Notebook: `MSConceptGraph.ipynb`

Located at `lessons/2-Symbolic/MSConceptGraph.ipynb`, this self-contained Jupyter notebook demonstrates the complete workflow:

1. Normalizes user input to match ConceptNet's URI conventions
2. Constructs parameterized HTTP requests
3. Parses JSON-LD responses into plain Python structures
4. Outputs hierarchical concept lists or simple visualizations

The notebook uses only Python standard library modules (`urllib`, `json`) to minimize dependency conflicts in restricted computing environments.

---

## Step-by-Step Workflow Implementation

The Microsoft Concept Graph integration workflow follows four deterministic stages, implemented in the `get_is_a_concepts()` function within the notebook.

### Step 1: Input Normalization

ConceptNet expects terms in lowercase with underscores replacing spaces. English language concepts use the `/c/en/{term}` URI pattern.

```python
term = term.lower().replace(' ', '_')

```

This transformation ensures valid URLs without manual encoding edge cases.

### Step 2: URL Construction

The notebook dynamically builds the API endpoint using **urllib.parse.quote** for proper percent-encoding:

```python
import urllib.parse

url = (
    f"https://api.conceptnet.io/query?"
    f"start=/c/en/{urllib.parse.quote(term)}&rel=/r/IsA&limit={limit}"
)

```

The `rel=/r/IsA` parameter specifically targets hierarchical "is-a" relationships — the same semantic pattern originally demonstrated with Microsoft Concept Graph.

### Step 3: HTTP Request Execution

The implementation uses `urllib.request.urlopen()` for compatibility with standard Python distributions:

```python
import json
import urllib.request

with urllib.request.urlopen(url) as response:
    data = json.load(response)

```

### Step 4: Response Parsing and Extraction

The JSON-LD response contains an `edges` array where each edge represents a relationship. The notebook filters for `IsA` relations and extracts human-readable labels:

```python
concepts = [
    edge['end']['label']
    for edge in data.get('edges', [])
    if edge['rel']['@id'].endswith('/IsA')
]

```

---

## Complete Production-Ready Implementation

The following code reproduces the exact Microsoft Concept Graph workflow from the AI-For-Beginners curriculum, with minor enhancements for clarity:

```python
import urllib.parse
import json
import urllib.request
from typing import List, Optional

def get_is_a_concepts(term: str, limit: int = 10) -> List[str]:
    """
    Query ConceptNet for 'IsA' relations of *term*.
    
    Replicates the Microsoft Concept Graph integration workflow
    from lessons/2-Symbolic/MSConceptGraph.ipynb.
    """
    # Normalize: lowercase, underscores for spaces

    normalized = term.lower().replace(' ', '_')
    
    # Build request URL with proper encoding

    encoded_term = urllib.parse.quote(normalized)
    url = (
        f"https://api.conceptnet.io/query?"
        f"start=/c/en/{encoded_term}&rel=/r/IsA&limit={limit}"
    )
    
    # Execute request with timeout

    request = urllib.request.Request(
        url,
        headers={'Accept': 'application/json'}
    )
    
    with urllib.request.urlopen(request, timeout=10) as response:
        data = json.load(response)
    
    # Extract child concepts from IsA relationships

    concepts = [
        edge['end']['label']
        for edge in data.get('edges', [])
        if edge['rel']['@id'].endswith('/IsA')
    ]
    
    return concepts

def demonstrate_workflow():
    """Example usage matching the notebook's demonstration."""
    query_term = "Microsoft"
    print(f"Querying ConceptNet for '{query_term}'...")
    
    results = get_is_a_concepts(query_term, limit=5)
    
    print(f"\nFound {len(results)} 'is-a' relationships:")
    for concept in results:
        print(f"  → {concept}")

if __name__ == "__main__":
    demonstrate_workflow()

```

Sample output:

```text
Querying ConceptNet for 'Microsoft'...

Found 5 'is-a' relationships:
  → company
  → corporation
  → software company
  → technology company
  → business

```

---

## Internationalization and Translation Architecture

The Microsoft Concept Graph workflow is replicated identically across all curriculum translations. Each localized notebook resides at `translations/{language}/lessons/2-Symbolic/MSConceptGraph.ipynb` and preserves:

- Identical code structure
- Same ConceptNet endpoint (language-agnostic)
- Localized markdown explanations
- Consistent output formatting

This architecture ensures learners worldwide experience the same knowledge graph integration pattern regardless of language.

Available translations include Chinese (zh-CN), Japanese (ja-JP), Korean (ko-KR), Portuguese (pt-BR), Spanish (es-ES), and others — all referencing the same core implementation.

---

## Key Files and Repository Structure

| File Path | Purpose | Direct Link |
|-----------|---------|-------------|
| `lessons/2-Symbolic/MSConceptGraph.ipynb` | Primary implementation notebook | [Source](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/2-Symbolic/MSConceptGraph.ipynb) |
| [`lessons/2-Symbolic/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/2-Symbolic/README.md) | Symbolic AI lesson overview, MCG background | [Source](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/2-Symbolic/README.md) |
| `translations/*/lessons/2-Symbolic/MSConceptGraph.ipynb` | Localized workflow copies | [Example (zh-CN)](https://github.com/microsoft/AI-For-Beginners/blob/main/translations/zh-CN/lessons/2-Symbolic/MSConceptGraph.ipynb) |

---

## Design Decisions and Trade-offs

The Microsoft Concept Graph replacement architecture reflects pragmatic educational constraints:

**urllib over requests** — Eliminates third-party dependency, ensuring functionality in locked-down environments like corporate training networks or restricted cloud notebooks.

**No caching layer** — Keeps code transparent for learning purposes; production implementations might add `functools.lru_cache` or Redis.

**Synchronous I/O** — Simplifies explanation for beginners; async patterns would add unnecessary complexity.

**ConceptNet over Wikidata/DBpedia** — More predictable response structure for "is-a" queries; smaller payload sizes suitable for classroom bandwidth.

---

## Summary

- **Microsoft Concept Graph integration** in AI-For-Beginners now uses **ConceptNet** as a fully compatible, open-source replacement after the original API retirement
- The **four-step workflow** — normalize, build URL, request, parse — is implemented in `lessons/2-Symbolic/MSConceptGraph.ipynb` using only Python standard library modules
- **Zero authentication** and **global translation coverage** make this architecture suitable for immediate classroom deployment
- The implementation prioritizes **pedagogical clarity** over production optimizations, with explicit code paths that learners can trace and modify

---

## Frequently Asked Questions

### Why was the Microsoft Concept Graph replaced in the curriculum?

The Microsoft Concept Graph API was retired by Microsoft, making the original lesson non-functional. The maintainers selected ConceptNet as a drop-in replacement because it offers identical "is-a" relationship queries without requiring API keys or authentication, preserving the lesson's educational value while ensuring long-term stability.

### Does the ConceptNet integration support languages other than English?

Yes. ConceptNet is inherently multilingual with concepts encoded as `/c/{language_code}/{term}`. The AI-For-Beginners notebook specifically uses `/c/en/` for English queries, but the architecture supports swapping language codes. Each translated curriculum notebook maintains the same workflow while allowing learners to explore concepts in their native language through ConceptNet's unified API.

### Can I adapt this workflow for production knowledge graph applications?

The notebook's implementation is optimized for educational transparency rather than production reliability. For production use, consider adding: request retry logic with exponential backoff, response caching, async HTTP clients for batch queries, and structured logging. The core URL construction and JSON parsing patterns remain valid, but should be wrapped in appropriate error handling and monitoring infrastructure.

### Where can I find the original Microsoft Concept Graph documentation?

Microsoft has archived the original MCG documentation as the service is deprecated. The AI-For-Beginners [`lessons/2-Symbolic/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/2-Symbolic/README.md) contains background context on the Microsoft Concept Graph's historical role in the curriculum. For current practical implementation, refer to the ConceptNet documentation at `https://github.com/commonsense/conceptnet5/wiki/API`.