# sync-spec-agent

🔍 AI-powered MCP assistant for telecom synchronization standards (ITU-T & 3GPP)

Ask questions about PTP, SyncE, GNSS, timing budgets in plain English — get answers with exact standard references.

## What it does

```
You ask:  "What is the time error requirement for 5G TDD base stations?"
Agent:    "Per ITU-T G.8271, the maximum absolute time error at the air 
           interface is ±1.5 μs for wide-area phase synchronization.
           Reference: G.8271 Table 1, Category A."
```

## Quick Start

```bash
# 1. Clone and install
git clone https://github.com/abinashkumar/sync-spec-agent.git
cd sync-spec-agent
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Set API key
export GOOGLE_API_KEY='your-gemini-key'

# 3. Index the knowledge base
python ingest.py

# 4. Start MCP server
python server.py
```

## Supported Standards

### ITU-T Synchronization
- G.8271 — Time/phase sync requirements
- G.8272 / G.8272.1 — PRTC / ePRTC
- G.8275.1 — PTP Full Timing Support (L2 profile)
- G.8275.2 — PTP Partial Timing Support (L3 profile)
- G.8262 / G.8262.1 — SyncE EEC / eEEC
- G.8264 — ESMC (SyncE messaging)
- G.8273.2 — T-BC / T-TSC clock requirements

### 3GPP
- TS 38.104 — NR base station timing requirements
- TS 38.401 — NG-RAN architecture (sync aspects)

### IEEE
- IEEE 1588-2019 — Precision Time Protocol v2.1

## Architecture

```
┌─────────────────────────────────────────────────┐
│             sync-spec-agent                      │
│                                                  │
│  ┌──────────┐   ┌───────────┐   ┌────────────┐ │
│  │Knowledge │──►│ Chunking  │──►│  ChromaDB  │ │
│  │  Base    │   │ + Embed   │   │ (vectors)  │ │
│  │(docs/)   │   │           │   │            │ │
│  └──────────┘   └───────────┘   └─────┬──────┘ │
│                                        │        │
│  ┌──────────┐                   ┌──────▼──────┐ │
│  │   MCP    │◄──────────────────│ RAG Engine  │ │
│  │  Server  │   answer + refs   │ (query +    │ │
│  │          │                   │  generate)  │ │
│  └────┬─────┘                   └─────────────┘ │
│       │                                          │
└───────┼──────────────────────────────────────────┘
        │ MCP Protocol
        ▼
  Any MCP Client (Claude, Kiro, etc.)
```

## Tech Stack

- Python 3.11+
- ChromaDB (vector store)
- Google Gemini (embeddings + generation)
- MCP SDK (Model Context Protocol server)

## Project Structure

```
sync-spec-agent/
├── docs/                  # Knowledge base documents
│   ├── itu-t/            # ITU-T standards summaries
│   ├── 3gpp/            # 3GPP spec extracts
│   └── guides/          # Vendor white papers & guides
├── src/
│   ├── ingest.py        # Document ingestion pipeline
│   ├── rag.py           # RAG query engine
│   └── server.py        # MCP server
├── tests/               # Test queries and validation
├── requirements.txt
├── README.md
└── .env.example
```

## Author

**Abinash Kumar** — Telecom Systems Engineer | 14 years in 5G RAN, synchronization testing, and test automation

- LinkedIn: [linkedin.com/in/abinash-kumar-26261657](https://linkedin.com/in/abinash-kumar-26261657)

## License

MIT