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

Requires: Python 3.8+ (no external dependencies)

✨ What it does (at a glance)

  • 🔒 Safe by default: all built‑ins are read‑only; writes require explicit code.
  • 🔤 Language‑centric normalization: /translate converts + − × ÷ = ≈ < ≤ > ≥ ^ % and currency symbols ($ € £ ¥ ₩ ₹ ₿ …) into canonical tokens (+ - * / = ~, <USD>, <EUR>, etc.).
  • 🌐 HTTP surface (no frameworks): /health, /adapters, /results/latest, /translate, /metrics.
  • 🗂️ Adapter model: drop‑in modules for heartbeat, band plans, IEC‑61850 path helper; stubs for SNMP/NETCONF/gNMI/OpenADR/IEC‑61850/DNP3/TM Forum.
  • 📈 Observability: Prometheus text at /metrics and JSONL exports (JSONEachRow) for ClickHouse.
  • 🛡️ Orthography = safety: semantics ride with the signal; everything spelled, typed, and auditable.

🚀 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

MethodPathPurposeExample
GET/healthHeartbeat, UTC time, uptime/health
GET/adaptersEnabled adapters + state/adapters
GET/results/latestLatest payloads per adapter/results/latest
GET/translate?q=...Currency + operator normalization/translate?q=$199.99+VAT=€210≈
GET/metricsPrometheus 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 reads using 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 allowlists for 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.”