| title | PEP Typing Knowledge Graph |
|---|---|
| emoji | 📋 |
| sdk | docker |
| app_port | 7860 |
| pinned | false |
Transforming Python's typing evolution into a structured Knowledge Graph that enables precedent-aware reasoning, historical analysis, and explainable recommendations for new language proposals.
Python's typing ecosystem has evolved through years of discussion across dozens of Python Enhancement Proposals (PEPs). Every new language feature, whether involving generics, protocols, TypedDict, ParamSpec, or type narrowing, emerged from extensive technical debates between core Python contributors.
Unfortunately, this historical knowledge is scattered across hundreds of pages of PEP documents, making it difficult for developers to understand:
- whether an idea has already been proposed,
- why previous proposals succeeded or failed,
- which technical objections were raised,
- and which historical discussions should be considered before proposing a new language feature.
This repository transforms that historical information into a structured Knowledge Graph capable of reasoning over unseen feature proposals using explicit relationships extracted from real Python Typing PEPs.
Instead of performing simple keyword search, the system reasons over entities, concepts, arguments, proposal history, and relationships to provide grounded recommendations backed by historical precedent.
Modern software engineering increasingly depends on systems that can reason over structured knowledge rather than retrieve isolated documents.
This project explores that idea within one of the most influential programming language ecosystems.
Rather than asking:
"Which PEP mentions this keyword?"
the system answers questions such as:
- Which historical proposals are most similar to my idea?
- What objections have already been discussed?
- Which concepts overlap?
- Which previous PEP should I study first?
- How has this concept evolved over time?
The result is an explainable reasoning engine built entirely on explicit knowledge representation instead of opaque semantic embeddings.
- Built from 29 real Python Typing PEPs
- Extracts 425+ historical design arguments
- Models 4 entity types
- Connects entities through 8 relationship types
- Performs precedent-aware reasoning over previously unseen feature proposals
- Includes chronological concept evolution analysis
- Generates grounded recommendations instead of generic summaries
- Uses zero external NLP or Knowledge Graph libraries
- Built entirely with the Python Standard Library
Transforms raw Python Typing PEPs into an explicit graph consisting of:
- PEPs
- Contributors
- Technical Concepts
- Design Arguments
- Historical References
- Proposal Relationships
Instead of relying on external NLP libraries or LLMs, every extraction rule is manually designed after studying the original PEP corpus.
This makes the entire extraction pipeline deterministic, explainable, and reproducible.
Given a completely new feature proposal, the engine identifies:
- related concepts
- historical precedents
- similar proposals
- previously raised objections
- recommended reading order
before producing a grounded recommendation.
Developers can inspect how individual typing concepts evolved over multiple PEPs, including supersession chains and historical debates.
Every recommendation is traceable back to actual source PEPs.
No hallucinated facts.
No black-box semantic retrieval.
Every conclusion is supported by explicit graph relationships.
| Metric | Value |
|---|---|
| Python Typing PEPs | 29 |
| Extracted Arguments | 425+ |
| Entity Types | 4 |
| Relationship Types | 8 |
| Supported Concepts | 21 |
| Contributors Identified | 27 |
| External Dependencies | 0 |
New Language Proposal
↓
Extract Concepts
↓
Traverse Knowledge Graph
↓
Find Historical Precedents
↓
Retrieve Related Arguments
↓
Generate Grounded Recommendation
↓
Recommend Relevant PEP Sections
The system is designed to support developers during the earliest stages of language design by surfacing historical context that would otherwise require reading thousands of lines of PEP discussions.
This repository demonstrates several core areas of modern AI and software engineering:
- Knowledge Representation
- Knowledge Graph Construction
- Rule-Based Information Extraction
- Explainable AI
- Graph-Based Reasoning
- Static Knowledge Systems
- Software Architecture
- Developer Tooling
The architecture is intentionally designed to be extensible to broader programming language evolution, standards documentation, and technical knowledge systems.
The system is organized as a deterministic knowledge processing pipeline. Rather than relying on machine learning models or semantic vector search, every stage operates on explicitly modeled entities, relationships, and reasoning rules extracted directly from the Python Typing PEP corpus.
┌────────────────────────────────────┐
│ Python Typing PEP Corpus │
│ (29 Real PEPs) │
└────────────────┬────────────────────┘
│
▼
┌────────────────────────────────────┐
│ Hand-Written RST Parser │
│ │
│ • Document Parsing │
│ • Metadata Extraction │
│ • Section Detection │
│ • Entity Identification │
└────────────────┬────────────────────┘
│
▼
┌────────────────────────────────────┐
│ Knowledge Graph Construction Engine │
│ │
│ • Entity Creation │
│ • Relationship Mapping │
│ • Argument Extraction │
│ • Reference Linking │
└────────────────┬────────────────────┘
│
▼
┌────────────────────────────────────┐
│ Knowledge Graph State │
│ │
│ Entities │
│ Relationships │
│ Metadata │
└────────────────┬────────────────────┘
│
┌─────────────────┴──────────────────┐
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ Structural Validation │ │ Historical Reasoning │
│ │ │ │
│ Graph Integrity │ │ Concept Matching │
│ Entity Consistency │ │ Precedent Discovery │
│ Relationship Checks │ │ Recommendation Engine │
└────────────┬────────────┘ └────────────┬────────────┘
│ │
└──────────────────┬───────────────┘
▼
┌──────────────────────────────────┐
│ Structured JSON Report │
│ │
│ • Related PEPs │
│ • Historical Arguments │
│ • Design Recommendation │
│ • Supporting Evidence │
└──────────────────────────────────┘
The repository consists of four independent processing stages.
| Stage | Responsibility |
|---|---|
| Parsing | Reads raw RST PEP documents and extracts structured information |
| Knowledge Construction | Creates entities and relationships inside the knowledge graph |
| Validation | Ensures graph integrity and verifies structural consistency |
| Reasoning | Answers previously unseen language proposals using graph traversal |
Each stage has a single responsibility, making the system deterministic, modular, and independently testable.
Instead of storing documents as plain text, the repository converts Python's typing history into an explicit graph representation.
Every important object inside the corpus becomes an entity.
PEP
Person
Concept
Argument
Relationships between these entities preserve historical context.
Rather than asking:
"Which document contains this keyword?"
the reasoning engine can answer questions such as:
- Which proposals discuss the same concept?
- Which people contributed to related proposals?
- Which objections repeatedly appear?
- Which proposal superseded another?
- Which concepts evolved together?
This structured representation enables reasoning that traditional keyword search cannot perform reliably.
The knowledge graph contains four primary entity types.
| Entity | Description |
|---|---|
| PEP | Individual Python Enhancement Proposal |
| Person | Authors, delegates, and contributors |
| Concept | Technical typing concepts such as Protocols, ParamSpec, TypedDict, or Type Narrowing |
| Argument | Historical design discussions extracted directly from PEP documents |
Each entity contains structured metadata rather than unstructured text, allowing relationships to be traversed efficiently.
Entities are connected through explicit semantic relationships.
Person
│
AUTHORED_BY
▼
PEP
│
├──────── REFERENCES ─────────────► PEP
│
├──────── SUPERSEDES ─────────────► PEP
│
├──────── DISCUSSES_CONCEPT ──────► Concept
│
└──────── HAS_ARGUMENT ───────────► Argument
│
▼
ARGUMENT_ABOUT
│
▼
Concept
This graph structure preserves historical context while enabling deterministic graph traversal during reasoning.
Knowledge extraction is intentionally rule-based.
No external NLP libraries.
No LLM-assisted extraction.
No pre-trained entity recognition models.
Instead, every extraction rule was manually designed after studying the Python Typing PEP corpus.
The extraction pipeline performs:
- RST document parsing
- Metadata extraction
- Section segmentation
- Concept identification
- Argument extraction
- Cross-reference detection
- Relationship construction
- Graph serialization
This approach prioritizes explainability, reproducibility, and deterministic behavior over probabilistic extraction.
When a developer submits a new language proposal, the system performs several reasoning steps before generating a recommendation.
User Proposal
↓
Concept Extraction
↓
Concept Matching
↓
Historical Graph Traversal
↓
Precedent Discovery
↓
Argument Aggregation
↓
Recommendation Generation
↓
Structured JSON Report
Unlike traditional search systems, the reasoning engine evaluates relationships between concepts instead of relying solely on textual similarity.
This enables the system to surface historical precedents that share conceptual foundations even when wording differs.
Several design principles guided the implementation of this repository.
Running the system multiple times over the same dataset always produces identical knowledge graphs and identical reasoning outputs.
Every recommendation can be traced back to explicit entities and relationships within the knowledge graph.
Nothing is inferred through opaque latent representations.
The entire repository uses only Python's Standard Library.
This keeps the system lightweight, portable, reproducible, and easy to inspect.
Each processing stage operates independently.
- Parsing
- Graph Construction
- Validation
- Reasoning
Because each module has a clearly defined responsibility, future improvements can be implemented without affecting unrelated components.
The system never invents historical arguments.
Every recommendation is backed by relationships extracted directly from real Python Typing PEPs, ensuring outputs remain explainable and verifiable.
The repository is organized around a simple, modular architecture where each component has a single responsibility. Parsing, graph construction, validation, and reasoning are intentionally separated to keep the system maintainable, testable, and easy to extend.
pep-typing-knowledge-system/
│
├── README.md
├── approach.md
│
├── data/
│ ├── raw/
│ │ ├── pep-0482.rst
│ │ ├── ...
│ │ └── pep-0746.rst
│ │
│ └── processed/
│ └── knowledge_state.json
│
├── src/
│ ├── build_knowledge.py
│ ├── validate.py
│ ├── reason.py
│ └── timeline.py
│
└── output/
└── last_report.json
| Directory | Purpose |
|---|---|
| data/raw/ | Original Python Typing PEP documents |
| data/processed/ | Generated Knowledge Graph |
| src/ | Core parsing, graph construction, validation, and reasoning logic |
| output/ | Generated reasoning reports |
| approach.md | Design decisions, tradeoffs, and implementation rationale |
Responsible for transforming raw Python Typing PEP documents into a structured Knowledge Graph.
Responsibilities include:
- Parsing RST documents
- Extracting entities
- Building relationships
- Detecting references
- Constructing graph edges
- Serializing the knowledge state
Output
knowledge_state.json
Performs structural validation on the generated graph.
Validation includes:
- Missing entities
- Broken references
- Invalid relationships
- Duplicate identifiers
- Graph consistency
The validator ensures every relationship references valid entities before reasoning begins.
Implements the primary reasoning engine.
Given an unseen feature proposal, it performs:
- Concept extraction
- Graph traversal
- Historical precedent discovery
- Argument aggregation
- Recommendation generation
This is the primary interface intended for developers.
Provides chronological exploration of a single concept.
Instead of asking
"What proposal is most similar?"
developers can ask
"How did this concept evolve?"
The timeline engine reconstructs concept evolution across multiple PEPs, showing supersession history, design debates, and historical context.
The repository intentionally keeps its dependency footprint minimal.
| Requirement | Version |
|---|---|
| Python | 3.9+ |
| External Libraries | None |
| Package Manager | Not Required |
| Database | None |
| API Keys | None |
Everything runs using the Python Standard Library.
No additional installation is required.
Clone the repository.
git clone https://github.com/AnmollCodes/pep-typing-knowledge-system.git
cd pep-typing-knowledge-systemVerify Python installation.
python3 --versionExpected
Python 3.9+
No further setup is necessary.
The repository already includes the complete PEP dataset.
Simply build the graph.
cd src
python3 build_knowledge.pyExample output
Building Knowledge Graph...
Reading 29 Python Typing PEPs...
Extracting entities...
Building relationships...
Generating graph...
Done.
Knowledge Graph Statistics
PEPs: 29
People: 27
Concepts: 21
Arguments: 425+
Relationship Types: 8
Output:
../data/processed/knowledge_state.json
Before performing reasoning, validate the graph.
python3 validate.pyExample output
Running structural validation...
Checking entities...
Checking relationships...
Checking references...
No structural errors found.
Graph validation successful.
This guarantees that every relationship references existing entities and that the generated graph is internally consistent.
The reasoning engine accepts new feature proposals through either command-line arguments or standard input.
python3 reason.py "Should Python support readonly TypedDict fields?"echo "Should isinstance() perform flow-sensitive narrowing for Protocol classes?" | python3 reason.py──────────────────────────────────────────
Knowledge Graph Reasoning Report
──────────────────────────────────────────
Matched Concepts
• TypedDict
• Mutability
• Type Safety
──────────────────────────────────────────
Relevant Historical PEPs
1. PEP 589
2. PEP 705
3. PEP 655
──────────────────────────────────────────
Historical Arguments
• Mutable dictionaries introduce ambiguity.
• Static guarantees should not affect runtime behavior.
• Type safety must remain explicit.
──────────────────────────────────────────
Recommendation
Study PEP 705 first.
Its discussion provides the closest historical precedent for introducing readonly semantics into TypedDict.
──────────────────────────────────────────
Every reasoning session is also exported as structured JSON.
output/
└── last_report.json
This allows downstream tools to consume reasoning results programmatically.
Example
{
"matched_concepts": [...],
"precedent_peps": [...],
"arguments": [...],
"recommendation": "..."
}The repository also includes a second reasoning interface focused on historical evolution.
List all supported concepts.
python3 timeline.py --listExample
Protocols
Type Narrowing
TypedDict
ParamSpec
Generics
TypeAlias
Variance
...
Inspect one concept.
python3 timeline.py type_narrowingExample output
PEP 544
↓
PEP 586
↓
PEP 647
↓
PEP 742
TypeGuard
↓
TypeIs
Historical Discussion
...
Recommendation
...
Unlike the reasoning engine, the timeline explorer focuses on understanding how a concept evolved over time rather than finding precedent for a new proposal.
The repository requires no runtime configuration.
| Setting | Required |
|---|---|
| Environment Variables | ❌ |
| API Keys | ❌ |
| Database | ❌ |
| External Services | ❌ |
Network access is only used if you choose to refresh the bundled PEP files from the official Python repository. Otherwise, the project runs completely offline.
This project intentionally prioritizes determinism, explainability, and knowledge representation over statistical inference.
Every major architectural decision was made to maximize transparency and reproducibility rather than prediction accuracy.
Python's typing evolution is fundamentally a network of interconnected ideas rather than a collection of isolated documents.
A traditional search engine answers:
"Which document contains this phrase?"
This repository instead answers questions such as:
- Which historical proposal is conceptually closest?
- Which technical debates repeatedly appear?
- Which proposal superseded another?
- Which contributors worked on similar ideas?
- Which concepts evolved together?
Representing this information as a graph preserves those relationships explicitly and enables explainable reasoning over historical design decisions.
Modern NLP systems often rely on pretrained models or Large Language Models for entity extraction.
This repository deliberately avoids those approaches.
Every parsing rule, concept matcher, and relationship extractor is implemented manually after studying the original PEP corpus.
This design provides several advantages:
- Fully deterministic outputs
- Reproducible graph generation
- Complete transparency
- Easy debugging
- No external dependencies
- No API costs
- No hallucinated entities
The objective was not to maximize recall but to produce a system whose reasoning process can be inspected and trusted.
Embedding-based retrieval excels at semantic similarity but introduces probabilistic behavior that is difficult to interpret.
For this project, explainability was prioritized over semantic flexibility.
Every recommendation is generated by traversing explicit graph relationships rather than nearest-neighbor searches in vector space.
As a result, every output can be traced back to concrete entities and relationships extracted directly from the original PEP documents.
Large Language Models can summarize documentation effectively, but they often blur the boundary between retrieved knowledge and generated content.
This repository intentionally avoids generative reasoning.
Instead, recommendations are constructed from:
- extracted concepts
- historical arguments
- proposal relationships
- graph traversal
- explicit reasoning rules
This ensures that recommendations remain grounded in historical evidence rather than generated interpretations.
Every software system involves trade-offs.
The following decisions were made intentionally.
| Decision | Benefit | Trade-off |
|---|---|---|
| Rule-based extraction | Deterministic and explainable | Less flexible than ML-based extraction |
| Knowledge Graph | Rich relationship modeling | Higher implementation complexity |
| Standard Library only | Lightweight and portable | Fewer built-in parsing utilities |
| Curated concept vocabulary | High precision | Lower recall for unseen terminology |
| Graph traversal | Explainable recommendations | Less semantic flexibility than embeddings |
These trade-offs align with the project's primary goal: building an interpretable reasoning engine rather than a general-purpose search system.
This repository focuses exclusively on Python's Typing PEPs (PEP 482–746).
It is intentionally scoped to one domain to prioritize depth over breadth.
The current knowledge graph includes:
- Python Typing PEPs
- Authors and delegates
- Technical concepts
- Historical arguments
- Proposal relationships
- Cross references
- Concept evolution
It does not currently model:
- All Python PEPs
- CPython source code
- GitHub discussions
- Python mailing list archives
- Issue tracker conversations
- Runtime implementation details
Every engineering project has boundaries.
Current limitations include:
- The knowledge base is limited to 29 typing PEPs.
- Concept matching relies on a manually curated vocabulary.
- Relationship extraction is rule-based rather than statistical.
- The reasoning engine does not rank relevance using embeddings.
- Historical context is limited to official PEP documents.
- The repository currently exposes a CLI interface only.
These limitations are intentional design decisions rather than implementation gaps.
Several directions could significantly expand the system while preserving its explainable architecture.
- Support the complete Python PEP corpus
- Include rejected and deferred proposals
- Parse Python Steering Council discussions
- Integrate mailing-list archives
- Connect CPython implementation commits
- Hybrid symbolic + semantic retrieval
- Confidence scoring
- Graph ranking algorithms
- Path explanation generation
- Multi-hop relationship reasoning
- Interactive web interface
- Graph visualization
- Search dashboard
- REST API
- Interactive timeline explorer
- Automatic graph validation
- Incremental graph updates
- Relationship confidence metrics
- Entity versioning
- Graph diffing across Python releases
This repository demonstrates practical experience across several areas of software engineering and applied AI.
- Knowledge Representation
- Explainable AI
- Symbolic Reasoning
- Rule-Based AI
- Information Extraction
- System Design
- Software Architecture
- Data Modeling
- Modular Design
- CLI Development
- Graph Construction
- Relationship Modeling
- Structured Data Processing
- Parsing Pipelines
- Data Validation
- Standard Library
- File Processing
- JSON Serialization
- Command Line Applications
- Modular Project Organization
This repository was built around one guiding principle:
Historical software engineering knowledge should be structured, searchable, and explainable—not buried inside long-form documentation.
Instead of generating answers from statistical models, the system reconstructs historical design context through explicit knowledge representation and deterministic reasoning.
Contributions are welcome.
Potential areas of improvement include:
- Additional Python PEP coverage
- Improved concept extraction rules
- New relationship types
- Visualization tools
- REST API support
- Performance optimizations
- Documentation improvements
Please open an issue before submitting significant architectural changes to discuss the proposed approach.
Primary sources used throughout the project include:
- Python Enhancement Proposals (PEP 482–746)
- Official Python PEP Repository
- Python Typing Documentation
Additional implementation rationale is documented in:
approach.md
Special thanks to the Python community for maintaining the public PEP archive that makes historical language evolution accessible for study and experimentation.
This project is released under the MIT License.
⭐ Consider starring the repository if you found the implementation useful or learned something from it.
Feedback, discussions, and suggestions are always welcome.