SolveForce UCLS Infra Gateway — Read‑Only Scaffold (v0.1)

Language first. Signals second. Safety always.

A minimal, standard‑library Python gateway that polls infrastructure read‑only, normalizes operators + currencies into canonical tokens, and exposes results over a clean HTTP surface—ready for observability and ClickHouse ingestion.

---

⬇️ Downloads

• Dev build (ZIP)solveforce-code-20250819-054125.zip
• Single‑file runnersolveforce_gateway_single.py
• SHA‑256 (ZIP)fef17c50dd6af27d2a1784336b0c3a6b85965723bd87ea2cb5438b1a19f0964a

Requires: Python 3.8+ (no external dependencies)

---

✨ What it does (at a glance)

---

🚀 Quick start

# Option A: full scaffold
unzip solveforce-code-20250819-054125.zip
cd solveforce-code
python ucls_infra_gateway.py --config config.example.json
# Open: http://127.0.0.1:8080/health

# Option B: single-file runner
python solveforce_gateway_single.py --host 127.0.0.1 --port 8080 --poll 5

---

🔌 Endpoints

Method	Path	Purpose	Example
GET	/health	Heartbeat, UTC time, uptime	/health
GET	/adapters	Enabled adapters + state	/adapters
GET	/results/latest	Latest payloads per adapter	/results/latest
GET	/translate?q=...	Currency + operator normalization	/translate?q=$199.99+VAT=€210≈
GET	/metrics	Prometheus exposition (text)	/metrics

---

⚙️ Configuration (edit config.example.json)

{
  "http": {"host": "127.0.0.1", "port": 8080},
  "poll_interval_sec": 5,
  "adapters": [
    {"name": "heartbeat", "enabled": true},
    {"name": "currency_operator", "enabled": true, "config": {"load_currency_sample": true}},
    {"name": "bandplan", "enabled": true, "config": {
      "bandplan_files": ["solveforce_gateway/data/bandplans/US_FCC_2.4_5.json"]
    }},
    {"name": "iec61850_helper", "enabled": true}
  ],
  "exports": {
    "enable_prometheus": true,
    "export_jsonl": true,
    "export_dir": "exports"
  }
}

---

🧰 Included adapters (read‑only)

• heartbeat— proof‑of‑life sequence + timestamps
• currency_operator— math operator + currency symbol normalizer; shows example parse
• bandplan— sample US FCC 2.4/5 GHz (inc. DFS) with channels
• iec61850_helper— parses MMXU1.A.phsA.cVal.mag.f style LN/DO/DA path components

Stubs you can wire next

snmp, netconf, gnmi, openadr, iec61850, dnp3, tmforum

Keep them read‑only: poll/get/subscribe only; no control ops; explicit capability allowlists.

---

🧭 How to extend (drop‑in pattern)

Create solveforce_gateway/adapters/my_adapter.py:

from ..core import AdapterInterface
class MyAdapter(AdapterInterface):
    NAME = "my_adapter"
    def poll(self):
        self.seq += 1
        return {"seq": self.seq, "payload": "hello, world"}

Enable it in the config:

{"name": "my_adapter", "enabled": true}

The manager will handle polling, /results/latest, /adapters, /metrics, and JSONL export.

---

🔍 Observability & exports

• Prometheus scrape: GET /metrics
• ClickHouse ingest: exports/*.jsonl with JSONEachRow (e.g., CREATE TABLE gw_heartbeat ... ENGINE=MergeTree)

---

🛡️ Safety posture

• Read‑only adapters by design; any write requires a new adapter with explicit verbs.
• Short‑lived sessions for network protocols; no stored credentials in code; keep secrets in env/keystore.
• Canonical tokens prevent silent ambiguity (− vs -, × vs *, $ vs A$|C$|NZ$).

---

🗺️ Roadmap (wire‑up sequence)

• SNMP (ifTable, sysUpTime, optics DOM, CPU/mem)
• NETCONF <get> trees(no edit-config)
• gNMI subscribe/get(read‑only)
• OpenADR 2.0b / IEEE 2030.5(VEN polling, no control)
• IEC‑61850 MMS readsusing the path helper for LN/DO/DA traversal
• DNP3 class scans(no control ops, no restarts)
• TM Forum Open APIs(Service/ResourceInventory, TroubleTicket—GET only)
• Global band plans + CLDR script allowlistsfor IDNs/brand TLD bundles

---

🪪 License & attribution

• MIT License — © 2025 Ronald Joseph Legarski, Jr.
• Published by: SolveForce (Nationwide & International Services)

---

📞 Contact SolveForce

(888) 765‑8301 • SolveForce Communications — Telecom & Technology Solutions
From smart grids to edge, from language to energy, we unify signals with sense.

---

🧠 Why this matters (the recursive bit)

Language orders the network; the network carries language. By spelling every signal (operators, currencies, paths) in one canonical grammar, we make infrastructure legible, interoperable, and auditable—from substations to routers to ledgers. Meaning travels with the measurement.

---

🧰 Troubleshooting

• Port in use?Change "port" in config.example.json.
• No Python 3.8+?pyenv or system package upgrade recommended.
• No data under /results/latest?Ensure the adapter is "enabled": true and wait one poll interval.
• Metrics empty?Hit /health first, then /metrics to verify counters advance.

---

“Speak, and the network listens; listen, and the network spells back in order.”

Key terms in plain language

Open a term for a concise explanation of language used on this page.

🔗API

An application programming interface is a defined way for software systems to exchange data or request functions from one another.

📞VoIP

Voice over Internet Protocol carries phone calls over an IP network instead of a traditional analog phone line. Call quality depends on network stability, latency, and traffic management.

💬Unified Communications (UCaaS)

A cloud-based combination of business calling, messaging, meetings, presence, and collaboration tools managed as one communications service.

🔌SIP Trunking

A service that connects a business phone system to the public telephone network using Internet Protocol, replacing or supplementing traditional phone lines.

📊Bandwidth

The amount of data a connection can carry in a given time, usually measured in Mbps or Gbps. More bandwidth supports more users, devices, and simultaneous applications.

⏱️Latency

The time it takes data to travel between two points. Lower latency improves voice, video meetings, cloud applications, gaming, and other real-time services.