> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
Hati hii inaorodhesha miunganisho yote kati ya mfumo wa TrustGraph na miundomino ya uwasilishaji na ufuatiliaji. Kwa sasa, mfumo huu umewekwa ili kutumia Apache Pulsar. Uchunguzi huu unaeleza maeneo yote ya kuunganisha ili kutoa taarifa kwa urekebishaji wa baadaye kuelekea uainishaji wa uwasilishaji na ufuatiliaji unaoweza kusanidiwa.
## Hali ya Sasa: Maeneo ya Kuunganisha ya Pulsar
### 1. Matumizi ya Moja kwa Moja ya Mteja wa Pulsar
Habari njema: Safu ya uainishaji (Mtumiaji, Mtayarishaji, Mchapishaji, Msubiri) hutoa uainishaji safi wa mwingiliano mwingi wa Pulsar.
Changamoto:
1.**Ukuaji wa mfumo wa schemas:** Ufafanuzi kila ujumbe hutumia `pulsar.schema.Record` na aina za Pulsar
2.**Enums maalum za Pulsar:**`InitialPosition`, `ConsumerType`
3.**Vizuizi vya Pulsar:**`_pulsar.Timeout`, `_pulsar.Interrupted`, `_pulsar.InvalidConfiguration`, `_pulsar.AlreadyClosed`
4.**Mifumo ya mbinu:**`acknowledge()`, `negative_acknowledge()`, `subscribe()`, `create_producer()`, n.k.
5.**Muundo wa URI ya mada:** Muundo wa `kind://tenant/namespace/topic` wa Pulsar
### Hatua Zinazofuata
Ili kufanya miundombinu ya p/s kuwa configurable, tunahitaji:
1. Kuunda kiolesura cha uainishaji kwa mfumo wa mteja/schema
2. Kuainisha enums na vizuizi maalum za Pulsar
3. Kuunda wrappers za schemas au ufafanuzi mbadala wa schemas
4. Kutekeleza kiolesura kwa wateja na mifumo mingine (Kafka, RabbitMQ, Redis Streams, n.k.)
5. Kusasisha `pubsub.py` ili iwe configurable na iunge mkono mifumo mingi
6. Kutoa njia ya uhamishaji kwa usakinishaji uliopo
## Mfumo Mkuu wa 1: Mfumo wa Adapta na Safu ya Tafsiri ya Schemas
### Maarifa Muhimu
Mfumo wa schemas ndio msingi wa mfumo huu.
**1. Endelea kutumia muundo wa Pulsar kama uwakilishi wa ndani**
Usiandike upya maelezo yote ya muundo.
Muundo utabaki `pulsar.schema.Record` ndani.
Tumia adapta ili kutafsiri katika eneo kati ya programu yetu na mfumo wa utumaji/kupokea.
**2. Unda safu ya utengwa kwa utumaji/kupokea:**
```
┌─────────────────────────────────────┐
│ Existing Code (unchanged) │
│ - Uses Pulsar schemas internally │
│ - Consumer/Producer/Publisher │
└──────────────┬──────────────────────┘
│
┌──────────────┴──────────────────────┐
│ PubSubFactory (configurable) │
│ - Creates backend-specific client │
└──────────────┬──────────────────────┘
│
┌──────┴──────┐
│ │
┌───────▼─────┐ ┌────▼─────────┐
│ PulsarAdapter│ │ KafkaAdapter │ etc...
│ (passthrough)│ │ (translates) │
└──────────────┘ └──────────────┘
```
**3. Tafakikata viambishi vya dhahabu:**
`PubSubClient` - muunganisho wa mteja
`PubSubProducer` - kutuma ujumbe
`PubSubConsumer` - kupokea ujumbe
`SchemaAdapter` - kutafsiri muundo wa Pulsar kuwa/kutoka JSON au muundo maalum wa mfumo wa nyuma
**4. Maelezo ya utekelezaji:**
Kwa **adapta ya Pulsar**: Karibu kupita moja kwa moja, tafsiri ndogo.
Kwa **mfumo mwingine wa nyuma** (Kafka, RabbitMQ, n.k.):
Tafsiri vitu vya rekodi ya Pulsar kuwa JSON/bytes
Linganisha dhana kama:
`InitialPosition.Earliest/Latest` → auto.offset.reset ya Kafka
`acknowledge()` → kukubali kwa Kafka
`negative_acknowledge()` → mfumo wa kurudisha au DLQ
URI za mada → majina ya mada maalum ya mfumo wa nyuma
### Uchambuzi
**Faida:**
✅ Mabadiliko madogo ya msimbo kwa huduma zilizopo
✅ Muundo unaendelea kuwa kama ilivyo (hakuna marekebisho makubwa)
✅ Njia ya hatua kwa hatua ya uhamishaji
✅ Watumiaji wa Pulsar hawona tofauti
✅ Mifumo mipya ya nyuma inaongezwa kupitia adapta
**Hasara:**
⚠️ Bado ina utegemezi wa Pulsar (kwa maelezo ya muundo)
⚠️ Mizozo mingine inapotafsiri dhana
### Toleo Mbadala
Unda **mfumo wa muundo wa TrustGraph** ambao hautegemei mfumo wowote wa kutuma na kupokea (kwa kutumia madarasa ya data au Pydantic), kisha uzalisha muundo wa Pulsar/Kafka/n.k. kutoka humo. Hii inahitaji kuandikewa tena kila faili ya muundo na inaweza kusababisha mabadiliko.
### Mapendekezo kwa Rasimu ya 1
Anza na **mbinu ya adapta** kwa sababu:
1. Ni ya vitendo - inafanya kazi na msimbo uliopo
2. Inathibitisha dhana kwa hatari ndogo
3. Inaweza kubadilika kuwa mfumo wa asili wa muundo baadaye ikiwa inahitajika
4. Inadumishwa kupitia usanidi: variable moja ya mazingira inabadilisha mifumo ya nyuma
## Mbinu ya Rasimu ya 2: Mfumo wa Muundo Usio na Utendaji wa Nyuma na Madarasa ya Data
### Dhana Kuu
Tumia **madarasa ya data ya Python** kama muundo wa muundo wa kati. Kila mfumo wa nyuma wa kutuma na kupokea hutoa utafsiri wake mwenyewe wa kuandika/kusoma kwa madarasa ya data, na kuondoa hitaji kwamba muundo wa Pulsar uendelee kuwa katika msimbo.
### Ulinganifu wa Muundo katika Kiwango cha Kiwanda
Badala ya kutafsiri muundo wa Pulsar, **kila mfumo wa nyuma hutoa utunzaji wake mwenyewe wa muundo** ambao unafanya kazi na madarasa ya data ya Python ya kawaida.
### Mtiririko wa Mchapishaji
```python
# 1. Get the configured backend from factory
pubsub = get_pubsub() # Returns PulsarBackend, MQTTBackend, etc.
# 2. Get schema class from the backend
# (Can be imported directly - backend-agnostic)
from trustgraph.schema.services.llm import TextCompletionRequest
# 3. Create a producer/publisher for a specific topic
producer = pubsub.create_producer(
topic="text-completion-requests",
schema=TextCompletionRequest # Tells backend what schema to use
)
# 4. Create message instances (same API regardless of backend)
`create_producer()` → huunda mtayarishaji (producer) wa Pulsar ukitumia schema ya JSON au rekodi iliyoundwa moja kwa moja.
`send(request)` → huhifadhi (hufanya serialization) darasa la data (dataclass) kuwa muundo wa JSON/Pulsar, na hutuma kwa Pulsar.
`receive()` → hupokea ujumbe wa Pulsar, na huhifadhi tena (hufanya deserialization) kurudi kuwa darasa la data.
**Kwa mfumo wa nyuma (backend) wa MQTT:**
`create_producer()` → huunganisha na programu (broker) ya MQTT, hakuna haja ya usajili wa schema.
`send(request)` → hubadilisha darasa la data kuwa JSON, na hutuma kwenye mada (topic) ya MQTT.
`receive()` → huhudhuria mada (topic) ya MQTT, na huhifadhi tena JSON kurudi kuwa darasa la data.
**Kwa mfumo wa nyuma (backend) wa Kafka:**
`create_producer()` → huunda mtayarishaji (producer) wa Kafka, na husajili schema ya Avro ikiwa inahitajika.
`send(request)` → huhifadhi darasa la data kuwa muundo wa Avro, na hutuma kwa Kafka.
`receive()` → hupokea ujumbe wa Kafka, na huhifadhi tena Avro kurudi kuwa darasa la data.
### Vipengele Muhimu vya Ubunifu
1.**Uundaji wa kitu (object) cha schema:** Kitu (object) cha darasa la data (dataclass) (`TextCompletionRequest(...)`) ni sawa bila kujali mfumo wa nyuma (backend).
2.**Mfumo wa nyuma (backend) hutunza uhifadhi:** Kila mfumo wa nyuma (backend) unajua jinsi ya kuhifadhi darasa lake la data kuwa muundo unaotumwa.
3.**Ufafanuzi wa schema wakati wa uundaji:** Unapounda mtayarishaji (producer)/mpokeaji (consumer), unataja aina ya schema.
4.**Usalama wa aina (type) unahifadhiwa:** Unapata kitu (object) sahihi cha `TextCompletionRequest`, sio kamusi (dict).
5.**Hakuna uvujaji wa mfumo wa nyuma (backend):** Msimbo wa programu kamwe hauingize maktaba maalum za mfumo wa nyuma (backend).
### Mfano wa Ubadilishaji
**Hali ya sasa (maalum kwa Pulsar):**
```python
# schema/services/llm.py
from pulsar.schema import Record, String, Boolean, Integer
class TextCompletionRequest(Record):
system = String()
prompt = String()
streaming = Boolean()
```
**Mpya (Sio tegemezi ya mfumo wa nyuma):**
```python
# schema/services/llm.py
from dataclasses import dataclass
@dataclass
class TextCompletionRequest:
system: str
prompt: str
streaming: bool = False
```
### Uunganisho wa Seva ya Nyuma (Backend)
Kila seva ya nyuma hushughulikia us serialization/deserialization wa madatakesi:
**Seva ya nyuma ya Pulsar:**
Huunda madatakesi `pulsar.schema.Record` moja kwa moja kutoka kwa madatakesi.
Au huserialize madatakesi hadi JSON na kutumia mfumo wa JSON wa Pulsar.
Inaendelea kudumisha utangamano na matumizi ya sasa ya Pulsar.
**Seva ya nyuma ya MQTT/Redis:**
Huserialize madatakesi ya aina ya JSON moja kwa moja.
Tumia `dataclasses.asdict()` / `from_dict()`.
Nyepesi, haihitaji usajili wa mfumo.
**Seva ya nyuma ya Kafka:**
Huunda mifumo ya Avro kutoka kwa maelezo ya madatakesi.
Tumia usajili wa mfumo wa Confluent.
Us serialization wa salama wa aina na udhamini wa mabadiliko ya mfumo.
### Muundo
```
┌─────────────────────────────────────┐
│ Application Code │
│ - Uses dataclass schemas │
│ - Backend-agnostic │
└──────────────┬──────────────────────┘
│
┌──────────────┴──────────────────────┐
│ PubSubFactory (configurable) │
│ - get_pubsub() returns backend │
└──────────────┬──────────────────────┘
│
┌──────┴──────┐
│ │
┌───────▼─────────┐ ┌────▼──────────────┐
│ PulsarBackend │ │ MQTTBackend │
│ - JSON schema │ │ - JSON serialize │
│ - or dynamic │ │ - Simple queues │
│ Record gen │ │ │
└─────────────────┘ └───────────────────┘
```
### Maelezo ya Utendaji
**1. Ufafanuzi wa muundo:** Darasa za data za kawaida na maelezo ya aina
`str`, `int`, `bool`, `float` kwa vipengele vya msingi
`list[T]` kwa safu
`dict[str, T]` kwa ramani
Darasa za data zilizounganishwa kwa aina ngumu
**2. Kila mfumo hutoa:**
Mfumo wa ubadilishaji: `dataclass → bytes/wire format`
Mfumo wa kurejesha: `bytes/wire format → dataclass`
Usajili wa muundo (ikiwa inahitajika, kama Pulsar/Kafka)
**3. Dhana ya mtumiaji/mtayarishaji:**
Tayari ipo (consumer.py, producer.py)
Sasisha ili kutumia ubadilishaji wa mfumo
Ondoa uingizaji wa moja kwa moja wa Pulsar
**4. Ulinganisho wa aina:**
Pulsar `String()` → Python `str`
Pulsar `Integer()` → Python `int`
Pulsar `Boolean()` → Python `bool`
Pulsar `Array(T)` → Python `list[T]`
Pulsar `Map(K, V)` → Python `dict[K, V]`
Pulsar `Double()` → Python `float`
Pulsar `Bytes()` → Python `bytes`
### Njia ya Uhamishaji
1.**Tengeneza matoleo ya darasa za data** ya muundo wote katika `trustgraph/schema/`
2.**Sasisha madarasa ya mfumo** (Mtumiaji, Mtayarishaji, Mchapishaji, Mwasili) ili kutumia ubadilishaji unaotolewa na mfumo
3.**Teleza PulsarBackend** na muundo wa JSON au uzalishaji wa Rekodi wa moja kwa moja
4.**Jaribu na Pulsar** ili kuhakikisha utangamano wa nyuma na matumizi yaliyopo
5.**Ongeza mifumo mipya** (MQTT, Kafka, Redis, n.k.) kama inahitajika
6.**Ondoa uingizaji wa Pulsar** kutoka kwa faili za muundo
### Faida
✅ **Hakuna utegemezi wa pub/sub** katika ufafanuzi wa muundo
✅ **Python ya kawaida** - rahisi kuelewa, kuangalia aina, na kutoa maelezo
✅ **Zana za kisasa** - inafanya kazi na mypy, kukamilisha kiotomatiki kwa IDE, na vichujio
✅ **Imeboreshwa kwa mfumo** - kila mfumo hutumia ubadilishaji wa asili
✅ **Hakuna gharama ya tafsiri** - ubadilishaji wa moja kwa moja, hakuna adapta
✅ **Usalama wa aina** - vitu halisi na aina sahihi
✅ **Uthibitisho rahisi** - inaweza kutumia Pydantic ikiwa inahitajika
### Changamoto na Suluhisho
**Changamoto:** `Record` ya Pulsar ina uthibitisho wa uwanja wakati wa utekelezaji
**Suluhisho:** Tumia darasa za data za Pydantic kwa uthibitisho ikiwa inahitajika, au vipengele vya darasa za data ya Python 3.10+ na `__post_init__`
**Changamoto:** Vipengele vingine maalum vya Pulsar (kama aina ya `Bytes`)
**Suluhisho:** Linganisha na aina ya `bytes` katika darasa ya data, mfumo hutunza uandikaji ipasavyo
**Changamoto:** Majina ya mada (`persistent://tenant/namespace/topic`)
**Suluhisho:** Dhani majina ya mada katika ufafanuzi wa muundo, mfumo hubadilisha kuwa muundo sahihi
**Changamoto:** Maendeleo na toleo la muundo
**Suluhisho:** Kila mfumo hushughulikia hii kulingana na uwezo wake (matoleo ya muundo ya Pulsar, rejista ya muundo ya Kafka, n.k.)
**Changamoto:** Aina ngumu zilizounganishwa
**Suluhisho:** Tumia darasa za data zilizounganishwa, mifumo inabadilisha/kurejesha kwa uangalifu
### Maamuzi ya Ubunifu
1.**Darasa za data za kawaida au Pydantic?**
✅ **Maamuzi: Tumia darasa za data za Python za kawaida**
Rahisi, hakuna utegemezi wa ziada
Uthibitisho hauhitajiki kwa mazoea
Rahisi kuelewa na kudumisha
2.**Maendeleo ya muundo:**
✅ **Maamuzi: Hakuna utaratibu wa toleo unaohitajika**
Miondoko ni thabiti na ya muda mrefu
Marekebisho kawaida huongeza sehemu mpya (utangamano wa nyuma)
Mifumo inashughulikia maendeleo ya muundo kulingana na uwezo wake
3.**Ulingano wa nyuma:**
✅ **Maamuzi: Mabadiliko makubwa ya toleo, utangamano wa nyuma hauhitajiki**
Itakuwa mabadiliko ya kuvunja na maagizo ya uhamishaji
Kutoa mtego huruhusu muundo bora
Mwongozo wa uhamishaji utatolewa kwa matumizi yaliyopo
4.**Aina zilizounganishwa na miundo ngumu:**
✅ **Maamuzi: Tumia darasa za data zilizounganishwa kwa asili**
Darasa za data za Python zinashughulikia uunganishaji kikamilifu
`list[T]` kwa safu, `dict[K, V]` kwa ramani
Mifumo inabadilisha/kurejesha kwa uangalifu
Mfano:
```python
@dataclass
class Value:
value: str
is_uri: bool
@dataclass
class Triple:
s: Value # Nested dataclass
p: Value
o: Value
@dataclass
class GraphQuery:
triples: list[Triple] # Array of nested dataclasses
metadata: dict[str, str]
```
5.**Maelezo ya msingi na sehemu za hiari:**
✅ **Uamuzi: Mchanganyiko wa sehemu za lazima, maelezo ya msingi, na sehemu za hiari**
Sehemu za lazima: Hakuna maelezo ya msingi
Sehemu zilizo na maelezo ya msingi: Zipo kila wakati, zina maelezo ya msingi yanayofaa
Sehemu za hiari kabisa: `T | None = None`, huachwa kutoka kwenye serialization wakati `None`
Mfano:
```python
@dataclass
class TextCompletionRequest:
system: str # Required, no default
prompt: str # Required, no default
streaming: bool = False # Optional with default value
metadata: dict | None = None # Truly optional, can be absent
```
**Maana muhimu ya usanifu:**
Wakati `metadata = None`:
```json
{
"system": "...",
"prompt": "...",
"streaming": false
// metadata field NOT PRESENT
}
```
Wakati `metadata = {}` (tupu wazi):
```json
{
"system": "...",
"prompt": "...",
"streaming": false,
"metadata": {} // Field PRESENT but empty
}
```
**Tofauti kuu:**
`None` → sehemu ambayo haina katika JSON (hairekebishwi)
Thamani tupu (`{}`, `[]`, `""`) → sehemu inayoonekana na thamani tupu
Hii ina umuhimu wa maana: "haiyapatikani" dhidi ya "tupu kwa uwazi"
Mifumo ya kurekebisha data lazima zisipite sehemu za `None`, badala ya kuzirekebisha kama `null`
## Mfumo wa Awali wa 3: Maelezo ya Utendaji
### Muundo wa Jina la Kawaida la Kundi
Badilisha majina ya kundi maalum ya kila mfumo na muundo wa kawaida ambao mifumo inaweza kulinganisha ipasavyo.
