trustgraph/docs/tech-specs/large-document-loading.sw.md

# Vipimo vya Utekelezaji wa Teknolojia ya Kupakia Hati Kubwa

## Muhtasari

Maelekezo haya yanaeleza masuala ya uwezo wa kufanya kazi na uzoefu wa mtumiaji wakati wa kupakia
hati kubwa katika TrustGraph. Muundo wa sasa hutumia kupakia hati kama operesheni moja, na kusababisha
shinikizo la kumbukumbu katika hatua nyingi za mchakato na kutoa maelezo au chaguo za kurejesha kwa watumiaji.


Utaratibu huu unalenga matumizi yafuatayo:

1. **Uchakataji wa Hati za PDF Kubwa**: Kupakia na kuchakata faili za PDF zenye mamia ya megabytes
   bila kutumia kumbukumbu yote.
2. **Kupakia Ambayo Inaweza Kuendelea**: Kuruhusu kupakia ambacho kimetokea kukatika kuendelea kutoka
   ambapo kilisimama badala ya kuanza tena.
3. **Maelezo ya Maendeleo**: Kutoa kwa watumiaji maelezo ya muda halisi kuhusu maendeleo ya
   kupakia na uchakataji.
4. **Uchakataji Wenye Ufanisi wa Kumbukumbu**: Kuchakata hati kwa njia ya mtiririko
   bila kuhifadhi faili zilizokamilika katika kumbukumbu.

## Lengo

**Kupakia kwa Awamu**: Kusaidia kupakia hati kwa sehemu kupitia REST na WebSocket
**Uhamisho Unaoweza Kuendelea**: Kuruhusu kurejesha kutoka kupakia ambacho kimetokea kukatika
**Uonekana wa Maendeleo**: Kutoa maelezo ya maendeleo ya kupakia/uchakataji kwa wateja
**Ufanisi wa Kumbukumbu**: Kuondoa uhifadhi wa hati zilizokamilika katika mchakato wote
**Ulinganifu na Mifumo ya Zamani**: Mchakato wa sasa wa hati ndogo unaendelea bila mabadiliko
**Uchakataji wa Mtiririko**: Ufichuzi na uainishaji wa maandishi hufanywa kwa kutumia mitiririko

## Asili

### Muundo wa Sasa

Hati zinatumiwa kupitia njia ifuatayo:

1. **Mteja** hutuma hati kupitia REST (`POST /api/v1/librarian`) au WebSocket
2. **Lango la API** linapokea ombi kamili lenye maudhui ya hati yaliyokuzwa kwa msingi 64
3. **LibrarianRequestor** huongeza ombi kwenye ujumbe wa Pulsar
4. **Huduma ya Librarian** inapokea ujumbe, huondoa maudhui ya hati katika kumbukumbu
5. **BlobStore** huhamisha hati kwenye Garage/S3
6. **Cassandra** huhifadhi metadata pamoja na rejea ya kitu
7. Kwa uchakataji: hati inavyolewa kutoka S3, huondoa maudhui, huainishwa—yote katika kumbukumbu

Faili muhimu:
Ingizo la REST/WebSocket: `trustgraph-flow/trustgraph/gateway/service.py`
Msingi wa Librarian: `trustgraph-flow/trustgraph/librarian/librarian.py`
Uhifadhi wa blob: `trustgraph-flow/trustgraph/librarian/blob_store.py`
Jedwali la Cassandra: `trustgraph-flow/trustgraph/tables/library.py`
Mpango wa API: `trustgraph-base/trustgraph/schema/services/library.py`

### Mapungufu ya Sasa

Muundo wa sasa una masuala kadhaa ambayo huathiri kumbukumbu na uzoefu wa mtumiaji:

1. **Operesheni ya Kupakia ya Atomiki**: Hati nzima lazima ihamishwe katika
   ombi moja. Hati kubwa zinahitaji ombi linalodumu kwa muda mrefu bila
   maelezo ya maendeleo na hakuna njia ya kujaribu tena ikiwa muunganisho utakatika.

2. **Muundo wa API**: API za REST na WebSocket zinatarajia hati
   nzima katika ujumbe mmoja. Mpango (`LibrarianRequest`) una `content`
   ambayo ina maudhui ya hati nzima yaliyokuzwa kwa msingi 64.

3. **Kumbukumbu ya Librarian**: Huduma ya librarian huondoa maudhui ya hati
   katika kumbukumbu kabla ya kuihamisha kwenye S3. Kwa PDF ya 500MB, hii inamaanisha
   kuhifadhi 500MB+ katika kumbukumbu ya mchakato.

4. **Kumbukumbu ya Kufichua PDF**: Wakati wa uchakataji, programu ya kufichua PDF
   huhamisha hati nzima katika kumbukumbu ili kuchimbua maandishi. Maktaba kama vile PyPDF
   zinaweza kuhitaji upataji wa hati nzima.

5. **Kumbukumbu ya Kifaa cha Kuchakata**: Kifaa cha kuchakata maandishi hupokea maandishi
   yaliyochimbuliwa na kuhifadhi katika kumbukumbu huku huchakata na kuunda sehemu.

**Mfano wa Athari ya Kumbukumbu** (PDF ya 500MB):
Lango: ~700MB (maudhui yaliyokuzwa)
Librarian: ~500MB (bytes zilizofichuliwa)
Kifaa cha Kufichua PDF: ~500MB + buffers za uchimbaji
Kifaa cha Kuchakata: maandishi yaliyochimbuliwa (hubadilika, inaweza kuwa 100MB+)

Kumbukumbu ya juu inaweza kuzidi 2GB kwa hati kubwa moja.

## Muundo wa Kiufundi

### Kanuni za Muundo

1. **Uhusiano wa API**: Mwingiliano wote wa mteja hupitia API ya librarian. Wateja
   hawana upataji wa moja kwa moja au kujua kuhusu uhifadhi wa S3/Garage.

2. **Kupakia kwa Sehemu ya S3**: Tumia kupakia kwa sehemu ya S3.
   Hii inasaidiwa kwa mfumo wowote unaolingana na S3 (AWS S3, MinIO, Garage,
   Ceph, DigitalOcean Spaces, Backblaze B2, n.k.) kuhakikisha uwezekano wa kuhamishwa.

3. **Kukamilika kwa Atomiki**: Kupakia kwa sehemu ya S3 kunaweza kukamilika kwa atomiki - sehemu
   zilizopakiwa hazionekani hadi `CompleteMultipartUpload` itakapopigwa.
   Hakuna faili za muda au operesheni za kubadilisha.

4. **Hali Inayoweza Kufuatiliwa**: Vipindi vya kupakia hufuatiliwa katika Cassandra, kutoa
   uonevu kuhusu kupakia ambacho hakikamilika na kuruhusu uwezo wa kuanza tena.

### Mchakato wa Kupakia kwa Sehemu

```
Client                    Librarian API                   S3/Garage
  │                            │                              │
  │── begin-upload ───────────►│                              │
  │   (metadata, size)         │── CreateMultipartUpload ────►│
  │                            │◄── s3_upload_id ─────────────│
  │◄── upload_id ──────────────│   (store session in          │
  │                            │    Cassandra)                │
  │                            │                              │
  │── upload-chunk ───────────►│                              │
  │   (upload_id, index, data) │── UploadPart ───────────────►│
  │                            │◄── etag ─────────────────────│
  │◄── ack + progress ─────────│   (store etag in session)    │
  │         ⋮                  │         ⋮                    │
  │   (repeat for all chunks)  │                              │
  │                            │                              │
  │── complete-upload ────────►│                              │
  │   (upload_id)              │── CompleteMultipartUpload ──►│
  │                            │   (parts coalesced by S3)    │
  │                            │── store doc metadata ───────►│ Cassandra
  │◄── document_id ────────────│   (delete session)           │
```

Mteja hawezi kuwasiliana na S3 moja kwa moja. Msimamizi (librarian) hutafsiri kati ya
API yetu ya kupakia vipande na operesheni za S3 za sehemu nyingi (multipart) kwa ndani.

### Operesheni za API ya Msimamizi (Librarian)

#### `begin-upload`

Anzisha kipindi cha kupakia vipande.

Ombi:
```json
{
  "operation": "begin-upload",
  "document-metadata": {
    "id": "doc-123",
    "kind": "application/pdf",
    "title": "Large Document",
    "user": "user-id",
    "tags": ["tag1", "tag2"]
  },
  "total-size": 524288000,
  "chunk-size": 5242880
}
```

Jibu:
```json
{
  "upload-id": "upload-abc-123",
  "chunk-size": 5242880,
  "total-chunks": 100
}
```

Msimamizi wa maktaba:
1. Huunda nambari ya kipekee `upload_id` na `object_id` (UUID kwa uhifadhi wa data).
2. Huita `CreateMultipartUpload` ya S3, na kupokea `s3_upload_id`.
3. Huunda rekodi ya kikao katika Cassandra.
4. Hurudisha `upload_id` kwa mteja.

#### `upload-chunk`

Pakia kipande kimoja.

Ombi:
```json
{
  "operation": "upload-chunk",
  "upload-id": "upload-abc-123",
  "chunk-index": 0,
  "content": "<base64-encoded-chunk>"
}
```

Jibu:
```json
{
  "upload-id": "upload-abc-123",
  "chunk-index": 0,
  "chunks-received": 1,
  "total-chunks": 100,
  "bytes-received": 5242880,
  "total-bytes": 524288000
}
```

Msimamizi wa maktaba:
1. Tafuta kikao kwa kutumia `upload_id`
2. Thibitisha umiliki (mtumiaji lazima awe yule aliyeunda kikao)
3. Piga simu kwa S3 `UploadPart` pamoja na data ya sehemu, na upokee `etag`
4. Sasisha rekodi ya kikao na fahirisi ya sehemu na etag
5. Rejesha maelezo ya maendeleo kwa mteja

Sehemu ambazo hazijafaulu zinaweza kujaribiwa tena - tuma tu `chunk-index` tena.

#### `complete-upload`

Hakisha upakiaji na uunde hati.

Ombi:
```json
{
  "operation": "complete-upload",
  "upload-id": "upload-abc-123"
}
```

Jibu:
```json
{
  "document-id": "doc-123",
  "object-id": "550e8400-e29b-41d4-a716-446655440000"
}
```

Msimamizi wa maktaba:
1. Tafuta kikao, thibitisha kwamba vipande vyote vimepokelewa
2. Anapiga S3 `CompleteMultipartUpload` na etags za sehemu (S3 huunganisha sehemu
   ndani - hakuna gharama ya kumbukumbu kwa msimamizi)
3. Huunda rekodi ya hati katika Cassandra na metadata na rejeleo la kitu
4. Huondoa rekodi ya kikao cha kupakia
5. Hurudisha kitambulisho cha hati kwa mteja

#### `abort-upload`

Kuacha kupakia ambacho kinaendelea.

Ombi:
```json
{
  "operation": "abort-upload",
  "upload-id": "upload-abc-123"
}
```

Msimamizi wa maktaba:
1. Anapiga simu kwa S3 `AbortMultipartUpload` ili kusafisha sehemu.
2. Anafuta rekodi ya kikao kutoka Cassandra.

#### `get-upload-status`

Angalia hali ya kupakia (kwa uwezo wa kuendelea).

Ombi:
```json
{
  "operation": "get-upload-status",
  "upload-id": "upload-abc-123"
}
```

Jibu:
```json
{
  "upload-id": "upload-abc-123",
  "state": "in-progress",
  "chunks-received": [0, 1, 2, 5, 6],
  "missing-chunks": [3, 4, 7, 8],
  "total-chunks": 100,
  "bytes-received": 36700160,
  "total-bytes": 524288000
}
```

#### `list-uploads`

Orodha ya vipakuliwa ambavyo havijakamilika kwa mtumiaji.

Ombi:
```json
{
  "operation": "list-uploads"
}
```

Jibu:
```json
{
  "uploads": [
    {
      "upload-id": "upload-abc-123",
      "document-metadata": { "title": "Large Document", ... },
      "progress": { "chunks-received": 43, "total-chunks": 100 },
      "created-at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

### Hifadhi ya Kipindi cha Uipakaji

Fuatilia uipakaji unaoendelea katika Cassandra:

```sql
CREATE TABLE upload_session (
    upload_id text PRIMARY KEY,
    user text,
    document_id text,
    document_metadata text,      -- JSON: title, kind, tags, comments, etc.
    s3_upload_id text,           -- internal, for S3 operations
    object_id uuid,              -- target blob ID
    total_size bigint,
    chunk_size int,
    total_chunks int,
    chunks_received map<int, text>,  -- chunk_index → etag
    created_at timestamp,
    updated_at timestamp
) WITH default_time_to_live = 86400;  -- 24 hour TTL

CREATE INDEX upload_session_user ON upload_session (user);
```

**Tabia ya TTL:**
Vikao hupotea baada ya saa 24 ikiwa havijakamilika.
Wakati TTL ya Cassandra inapita, rekodi ya kikao inafutwa.
Sehemu zisizo na uhusiano za S3 huondolewa na sera ya maisha ya S3 (sanidi kwenye ndoo).

### Usimamizi wa Hitilafu na Uadilifu

**Hitilafu ya kupakia sehemu:**
Mteja hurudia kupakia sehemu iliyoshindwa (na `upload_id` na `chunk-index` sawa).
`UploadPart` ya S3 ni sawa kwa nambari sawa ya sehemu.
Kikao kinafuatilia sehemu zipi zilizofanikiwa.

**Mteja hukatika wakati wa kupakia:**
Kikao kinaendelea katika Cassandra na sehemu zilizopokelewa zimeandikwa.
Mteja anaweza kupiga `get-upload-status` ili kuona nini kinakosekana.
Anza tena kwa kupakia sehemu ambazo hazijapakiwa, kisha `complete-upload`.

**Hitilafu ya kupakia kikamilifu:**
`CompleteMultipartUpload` ya S3 ni ya uadilifu - inaweza kufanikiwa kikamilifu au kushindwa.
Katika hali ya kushindwa, sehemu zinaendelea na mteja anaweza kujaribu tena `complete-upload`.
Hati yoyote ya nusu haionekani.

**Kumalizika kwa kikao:**
TTL ya Cassandra inafuta rekodi ya kikao baada ya saa 24.
Sera ya maisha ya ndoo ya S3 husafisha kupakia kwa sehemu nyingi ambazo hazijakamilika.
Hakuna usafishaji wa mwongozo unaohitajika.

### Uadilifu wa Sehemu Nyingi za S3

Kupakia kwa sehemu nyingi za S3 hutoa uadilifu uliopo:

1. **Sehemu hazionekani:** Sehemu zilizopakuliwa haziwezi kupatikana kama vitu.
   Zipo tu kama sehemu za kupakia kwa sehemu nyingi ambazo hazijakamilika.

2. **Kukamilisha kwa uadilifu:** `CompleteMultipartUpload` inaweza kufanikiwa (kitu
   kinaonekana kwa uadilifu) au kushindwa (hakuna kitu kilichoanzishwa). Hakuna hali ya nusu.

3. **Hakuna jina tena linalohitajika:** Ufunguo wa mwisho wa kitu unaonyeshwa wakati
   `CreateMultipartUpload`. Sehemu huunganishwa moja kwa moja kwenye ufunguo huo.

4. **Uunganishaji wa upande wa seva:** S3 inaunganisha sehemu ndani. Msimamizi
   haisomi sehemu - hakuna gharama ya kumbukumbu bila kujali ukubwa wa hati.

### Upanuzi wa BlobStore

**Faili:** `trustgraph-flow/trustgraph/librarian/blob_store.py`

Ongeza mbinu za kupakia sehemu nyingi:

```python
class BlobStore:
    # Existing methods...

    def create_multipart_upload(self, object_id: UUID, kind: str) -> str:
        """Initialize multipart upload, return s3_upload_id."""
        # minio client: create_multipart_upload()

    def upload_part(
        self, object_id: UUID, s3_upload_id: str,
        part_number: int, data: bytes
    ) -> str:
        """Upload a single part, return etag."""
        # minio client: upload_part()
        # Note: S3 part numbers are 1-indexed

    def complete_multipart_upload(
        self, object_id: UUID, s3_upload_id: str,
        parts: List[Tuple[int, str]]  # [(part_number, etag), ...]
    ) -> None:
        """Finalize multipart upload."""
        # minio client: complete_multipart_upload()

    def abort_multipart_upload(
        self, object_id: UUID, s3_upload_id: str
    ) -> None:
        """Cancel multipart upload, clean up parts."""
        # minio client: abort_multipart_upload()
```

### Mambo Yanayohusiana na Ukubwa wa Sehemu

**Kiwango cha chini cha S3**: 5MB kwa kila sehemu (isipokuwa sehemu ya mwisho)
**Kiwango cha juu cha S3**: Sehemu 10,000 kwa kila upakiaji
**Kiwango cha kawaida kinachopendekezwa**: Sehemu za 5MB
  Hati ya 500MB = sehemu 100
  Hati ya 5GB = sehemu 1,000
**Ufuatiliaji wa maendeleo**: Sehemu ndogo = taarifa za maendeleo bora
**Ufanisi wa mtandao**: Sehemu kubwa = safari ndogo

Ukubwa wa sehemu unaweza kupangwa na mtumiaji ndani ya mipaka (5MB - 100MB).

### Ufuatiliaji wa Hati: Upakiaji wa Kiasi

Mchakato wa upakiaji unalenga kuweka hati kwenye hifadhi kwa ufanisi. Mchakato
wa ufuatiliaji unalenga kuchuja na kugawanya hati bila kuzipakia
zote kwenye kumbukumbu.

#### Kanuni ya Ubunifu: Kitambulisho, Sio Yaliyomo

Kwa sasa, wakati mchakato unaanza, yaliyomo kwenye hati huhamishwa kupitia
ujumbe wa Pulsar. Hii inapakia hati zote kwenye kumbukumbu. Badala yake:

Ujumbe wa Pulsar unaonyesha tu **kitambulisho cha hati**
Vifaa vya ufuatiliaji hupata yaliyomo kwenye hati moja kwa moja kutoka kwa mfumo
Kupata hufanyika kama **mtiririko kwenye faili ya muda**
Ufuatiliaji maalum wa hati (PDF, maandishi, n.k.) hufanya kazi na faili, sio
mipaka ya kumbukumbu

Hii inahakikisha kwamba mfumo wa hati hautegemei muundo wa hati. Ufuatiliaji
wa PDF, ufuatiliaji wa maandishi, na mantiki nyingine maalum ya muundo
inabaki katika vichujio husika.

```
Pulsar              PDF Decoder                Librarian              S3
  │                      │                          │                  │
  │── doc-id ───────────►│                          │                  │
  │  (processing msg)    │                          │                  │
  │                      │                          │                  │
  │                      │── stream-document ──────►│                  │
  │                      │   (doc-id)               │── GetObject ────►│
  │                      │                          │                  │
  │                      │◄── chunk ────────────────│◄── stream ───────│
  │                      │   (write to temp file)   │                  │
  │                      │◄── chunk ────────────────│◄── stream ───────│
  │                      │   (append to temp file)  │                  │
  │                      │         ⋮                │         ⋮        │
  │                      │◄── EOF ──────────────────│                  │
  │                      │                          │                  │
  │                      │   ┌──────────────────────────┐              │
  │                      │   │ temp file on disk        │              │
  │                      │   │ (memory stays bounded)   │              │
  │                      │   └────────────┬─────────────┘              │
  │                      │                │                            │
  │                      │   PDF library opens file                    │
  │                      │   extract page 1 text ──►  chunker          │
  │                      │   extract page 2 text ──►  chunker          │
  │                      │         ⋮                                   │
  │                      │   close file                                │
  │                      │   delete temp file                          │
```

#### API ya Mfumo wa Maktaba

Ongeza operesheni ya upataji wa hati kwa njia ya mtiririko:

**`stream-document`**

Ombi:
```json
{
  "operation": "stream-document",
  "document-id": "doc-123"
}
```

Jibu: Vipande vya binary vilivyotumwa (si jibu moja).

Kwa API ya REST, hii hurudisha jibu linaloendelea kwa kutumia `Transfer-Encoding: chunked`.

Kwa simu za ndani kati ya huduma (kwa mfumo wa uprosesa hadi mfumo wa kumbukumbu), hii inaweza kuwa:
Uhamisho wa moja kwa moja wa S3 kupitia URL iliyosainiwa (ikiwa mtandao wa ndani unaruhusu).
Majibu yaliyogawanywa kupitia itifaki ya huduma.
Kituo maalum cha utumaji wa data.

Mahitaji muhimu: data inatiririka kwa vipande, haijahifadhiwa kikamilifu katika mfumo wa kumbukumbu.

#### Mabadiliko ya Kipanguli cha PDF

**Utendaji wa sasa** (unaotumia kumbukumbu nyingi):

```python
def decode_pdf(document_content: bytes) -> str:
    reader = PdfReader(BytesIO(document_content))  # full doc in memory
    text = ""
    for page in reader.pages:
        text += page.extract_text()  # accumulating
    return text  # full text in memory
```

**Utekelezaji mpya** (faili ya muda, hatua kwa hatua):

```python
def decode_pdf_streaming(doc_id: str, librarian_client) -> Iterator[str]:
    """Yield extracted text page by page."""

    with tempfile.NamedTemporaryFile(delete=True, suffix='.pdf') as tmp:
        # Stream document to temp file
        for chunk in librarian_client.stream_document(doc_id):
            tmp.write(chunk)
        tmp.flush()

        # Open PDF from file (not memory)
        reader = PdfReader(tmp.name)

        # Yield pages incrementally
        for page in reader.pages:
            yield page.extract_text()

        # tmp file auto-deleted on context exit
```

Profaili ya kumbukumbu:
Faili ya muda kwenye diski: ukubwa wa faili ya PDF (diski ni rahisi).
Katika kumbukumbu: ukurasa mmoja wa maandishi kwa wakati.
Kumbukumbu ya juu: imepunguzwa, haitegemei saizi ya hati.

#### Mabadiliko ya Kipanguli cha Hati za Nakshata

Kwa hati za nakshata, rahisi zaidi - hakuna faili ya muda inayohitajika:

```python
def decode_text_streaming(doc_id: str, librarian_client) -> Iterator[str]:
    """Yield text in chunks as it streams from storage."""

    buffer = ""
    for chunk in librarian_client.stream_document(doc_id):
        buffer += chunk.decode('utf-8')

        # Yield complete lines/paragraphs as they arrive
        while '\n\n' in buffer:
            paragraph, buffer = buffer.split('\n\n', 1)
            yield paragraph + '\n\n'

    # Yield remaining buffer
    if buffer:
        yield buffer
```

Hati za maandishi zinaweza kutiririka moja kwa moja bila faili ya muda kwa sababu zina
muundo wa mstari.

#### Jumuisho la Kifaa cha Kugawa (Chunker)

Kifaa cha kugawa hupokea mfuatiliaji wa maandishi (kurasa au aya) na hutoa
vipande kwa hatua kwa hatua:

```python
class StreamingChunker:
    def __init__(self, chunk_size: int, overlap: int):
        self.chunk_size = chunk_size
        self.overlap = overlap

    def process(self, text_stream: Iterator[str]) -> Iterator[str]:
        """Yield chunks as text arrives."""
        buffer = ""

        for text_segment in text_stream:
            buffer += text_segment

            while len(buffer) >= self.chunk_size:
                chunk = buffer[:self.chunk_size]
                yield chunk
                # Keep overlap for context continuity
                buffer = buffer[self.chunk_size - self.overlap:]

        # Yield remaining buffer as final chunk
        if buffer.strip():
            yield buffer
```

#### Mchakato Kamili wa Uendeshaji

```python
async def process_document(doc_id: str, librarian_client, embedder):
    """Process document with bounded memory."""

    # Get document metadata to determine type
    metadata = await librarian_client.get_document_metadata(doc_id)

    # Select decoder based on document type
    if metadata.kind == 'application/pdf':
        text_stream = decode_pdf_streaming(doc_id, librarian_client)
    elif metadata.kind == 'text/plain':
        text_stream = decode_text_streaming(doc_id, librarian_client)
    else:
        raise UnsupportedDocumentType(metadata.kind)

    # Chunk incrementally
    chunker = StreamingChunker(chunk_size=1000, overlap=100)

    # Process each chunk as it's produced
    for chunk in chunker.process(text_stream):
        # Generate embeddings, store in vector DB, etc.
        embedding = await embedder.embed(chunk)
        await store_chunk(doc_id, chunk, embedding)
```

Katika hakuna hatua, hati kamili au maandishi yaliyotolewa kamili hayahifadhiwi kwenye kumbukumbu.

#### Mambo Yanayohusiana na Faili za Muda

**Mahali:** Tumia saraka ya muda ya mfumo (`/tmp` au sawa). Kwa
matumizi yaliyojumuishwa, hakikisha saraka ya muda ina nafasi ya kutosha
na iko kwenye uhifadhi wa haraka (si iliyounganishwa kwenye mtandao, ikiwezekana).

**Usafishaji:** Tumia menejeria wa muktadha (`with tempfile...`) ili kuhakikisha usafishaji
hata wakati wa hitilafu.

**Uchakataji sambamba:** Kazi kila moja ya uchakataji hupata faili yake ya muda.
Hakuna migogoro kati ya uchakataji wa hati sambamba.

**Nafasi ya diski:** Faili za muda zina muda mfupi (muda wa uchakataji). Kwa
hati ya PDF ya 500MB, inahitaji nafasi ya muda ya 500MB wakati wa uchakataji. Kikomo cha ukubwa
kinaweza kutekelezwa wakati wa kupakia ikiwa nafasi ya diski ni mdogo.

### Kiolesura Kimoja cha Uchakataji: Hati za Mtoto

Uchimbaji wa hati za PDF na uchakataji wa hati za maandishi lazima ziingie katika
mstari mmoja wa baadaye (kugawanya → embeddings → uhifadhi). Ili kufanikisha hili kwa
"kupata kwa ID" kiolesura, vipande vya maandishi vilivyochimbwa huhifadhiwa tena
kwenye mfumo kama hati za mtoto.

#### Mchakato wa Uchakataji na Hati za Mtoto

```
PDF Document                                         Text Document
     │                                                     │
     ▼                                                     │
pdf-extractor                                              │
     │                                                     │
     │ (stream PDF from librarian)                         │
     │ (extract page 1 text)                               │
     │ (store as child doc → librarian)                    │
     │ (extract page 2 text)                               │
     │ (store as child doc → librarian)                    │
     │         ⋮                                           │
     ▼                                                     ▼
[child-doc-id, child-doc-id, ...]                    [doc-id]
     │                                                     │
     └─────────────────────┬───────────────────────────────┘
                           ▼
                       chunker
                           │
                           │ (receives document ID)
                           │ (streams content from librarian)
                           │ (chunks incrementally)
                           ▼
                    [chunks → embedding → storage]
```

Kifaa cha kuainisha (chunker) kina muundo mmoja wa kiungo:
Pokea kitambulisho cha hati (kupitia Pulsar)
Pumua yaliyomo kutoka kwa mfumo wa kumbukumbu (librarian)
Igawanye katika sehemu ndogo

Haijulishi au hajali kama kitambulisho kinarejelea:
Hati ya maandishi iliyopakiwa na mtumiaji
Sehemu ya maandishi iliyochimbwa kutoka kwa ukurasa wa PDF
Aina yoyote ya hati ya siku zijazo

#### Meta-data ya Hati Ndogo

Panua muundo wa hati ili kufuatilia uhusiano wa mzazi/mtoto:

```sql
-- Add columns to document table
ALTER TABLE document ADD parent_id text;
ALTER TABLE document ADD document_type text;

-- Index for finding children of a parent
CREATE INDEX document_parent ON document (parent_id);
```

**Aina za nyaraka:**

| `document_type` | Maelezo |
|-----------------|-------------|
| `source` | Nyaraka zilizopakiwa na mtumiaji (PDF, maandishi, n.k.) |
| `extracted` | Zilizotokana na nyaraka asili (k.m., maandishi ya ukurasa wa PDF) |

**Nafasi za metadata:**

| Nafasi | Nyaraka Asili | Nyaraka Zilizotokana |
|-------|-----------------|-----------------|
| `id` | Zilizotolewa na mtumiaji au zilizoundwa | Zilizoundwa (k.m., `{parent-id}-page-{n}`) |
| `parent_id` | `NULL` | Kitambulisho cha nyaraka asili |
| `document_type` | `source` | `extracted` |
| `kind` | `application/pdf`, n.k. | `text/plain` |
| `title` | Zilizotolewa na mtumiaji | Zilizoundwa (k.m., "Ukurasa wa 3 wa Ripoti.pdf") |
| `user` | Mtumiaji aliyeidhinishwa | Sawa na nyaraka asili |

#### API ya Maktaba kwa Nyaraka Zilizotokana

**Kuunda nyaraka zilizotokana** (ya ndani, hutumiwa na pdf-extractor):

```json
{
  "operation": "add-child-document",
  "parent-id": "doc-123",
  "document-metadata": {
    "id": "doc-123-page-1",
    "kind": "text/plain",
    "title": "Page 1"
  },
  "content": "<base64-encoded-text>"
}
```

Kwa maandishi madogo ambayo yamechukuliwa (maandishi ya kawaida ya ukurasa ni chini ya 100KB), kupakia kwa operesheni moja ni sawa. Kwa matamshi makubwa sana ya maandishi, kupakia kwa sehemu kunaweza kutumika.

**Orodha ya hati za watoto** (kwa ajili ya utatuzi/utawala):



```json
{
  "operation": "list-children",
  "parent-id": "doc-123"
}
```

Jibu:
```json
{
  "children": [
    { "id": "doc-123-page-1", "title": "Page 1", "kind": "text/plain" },
    { "id": "doc-123-page-2", "title": "Page 2", "kind": "text/plain" },
    ...
  ]
}
```

#### Tabia inayoonwa na mtumiaji

**Tabia ya kawaida ya `list-documents`:**

```sql
SELECT * FROM document WHERE user = ? AND parent_id IS NULL;
```

Tuandishi kuu (vyanzo) pekee ndivyo yanavyoonekana kwenye orodha ya vyanzo vya mtumiaji.
Vyanzo vidogo huondolewa kwa chaguo-msingi.

**Bendera ya hiari ya kujumuisha-vyanzo-vidogo** (kwa wasimamizi/uchunguzi):

```json
{
  "operation": "list-documents",
  "include-children": true
}
```

#### Ufutilishaji wa Kuondoa Data kwa Kadirio

Wakati hati mama inapoondolewa, watoto wote lazima waondolewe:

```python
def delete_document(doc_id: str):
    # Find all children
    children = query("SELECT id, object_id FROM document WHERE parent_id = ?", doc_id)

    # Delete child blobs from S3
    for child in children:
        blob_store.delete(child.object_id)

    # Delete child metadata from Cassandra
    execute("DELETE FROM document WHERE parent_id = ?", doc_id)

    # Delete parent blob and metadata
    parent = get_document(doc_id)
    blob_store.delete(parent.object_id)
    execute("DELETE FROM document WHERE id = ? AND user = ?", doc_id, user)
```

#### Mawazo Kuhusu Uhifadhi

Matini yaliyotolewa yana nakala sawa:
Nakala asili ya PDF inahifadhiwa katika "Garage"
Nakala iliyotolewa kwa kila ukurasa pia inahifadhiwa katika "Garage"

Hii inaruhusu:
**Kiolesura sawa cha "chunker"**: "Chunker" daima hupata data kwa kutumia kitambulisho
**Uendelezaji/jaribio tena**: Inaweza kuanza tena katika hatua ya "chunker" bila kuhariri tena PDF
**Urekebishaji**: Nakala iliyotolewa inaweza kuchunguzwa
**Tofauti ya majukumu**: Huduma ya kuchimbua PDF na "chunker" ni huduma tofauti

Kwa PDF ya 500MB yenye kurasa 200, kwa wastani ya matini ya 5KB kwa kila ukurasa:
Uhifadhi wa PDF: 500MB
Uhifadhi wa matini iliyotolewa: ~1MB jumla
Gharama ya ziada: ndogo sana

#### Matokeo ya Kuchimbua PDF

Kichunguzi cha kuchimbua PDF, baada ya kuchakata hati:

1. Hupata PDF kutoka kwa "librarian" hadi kwenye faili ya muda
2. Huchimbua matini ukurasa kwa ukurasa
3. Kwa kila ukurasa, huhifadhi matini iliyotolewa kama hati ndogo kupitia "librarian"
4. Hutuma kitambulisho cha hati ndogo kwa folyo ya "chunker"

```python
async def extract_pdf(doc_id: str, librarian_client, output_queue):
    """Extract PDF pages and store as child documents."""

    with tempfile.NamedTemporaryFile(delete=True, suffix='.pdf') as tmp:
        # Stream PDF to temp file
        for chunk in librarian_client.stream_document(doc_id):
            tmp.write(chunk)
        tmp.flush()

        # Extract pages
        reader = PdfReader(tmp.name)
        for page_num, page in enumerate(reader.pages, start=1):
            text = page.extract_text()

            # Store as child document
            child_id = f"{doc_id}-page-{page_num}"
            await librarian_client.add_child_document(
                parent_id=doc_id,
                document_id=child_id,
                kind="text/plain",
                title=f"Page {page_num}",
                content=text.encode('utf-8')
            )

            # Send to chunker queue
            await output_queue.send(child_id)
```

Kifaa cha kuainisha vitapokea kitambulisho hivi vya watoto na vitawatumia kwa njia ile ile
ambayo kingetumia hati ya maandishi iliyopakiwa na mtumiaji.

### Sasizi za Mteja

#### SDK ya Python

SDK ya Python (`trustgraph-base/trustgraph/api/library.py`) inapaswa kushughulikia
vipakio vilivyogawanywa kwa njia ya moja kwa moja. Muundo wa umma haubadiliki:

```python
# Existing interface - no change for users
library.add_document(
    id="doc-123",
    title="Large Report",
    kind="application/pdf",
    content=large_pdf_bytes,  # Can be hundreds of MB
    tags=["reports"]
)
```

Kwa ndani, SDK hugundua ukubwa wa hati na hubadilisha mkakati:

```python
class Library:
    CHUNKED_UPLOAD_THRESHOLD = 2 * 1024 * 1024  # 2MB

    def add_document(self, id, title, kind, content, tags=None, ...):
        if len(content) < self.CHUNKED_UPLOAD_THRESHOLD:
            # Small document: single operation (existing behavior)
            return self._add_document_single(id, title, kind, content, tags)
        else:
            # Large document: chunked upload
            return self._add_document_chunked(id, title, kind, content, tags)

    def _add_document_chunked(self, id, title, kind, content, tags):
        # 1. begin-upload
        session = self._begin_upload(
            document_metadata={...},
            total_size=len(content),
            chunk_size=5 * 1024 * 1024
        )

        # 2. upload-chunk for each chunk
        for i, chunk in enumerate(self._chunk_bytes(content, session.chunk_size)):
            self._upload_chunk(session.upload_id, i, chunk)

        # 3. complete-upload
        return self._complete_upload(session.upload_id)
```

**Arifa za maendeleo** (ongezeko la hiari):

```python
def add_document(self, ..., on_progress=None):
    """
    on_progress: Optional callback(bytes_sent, total_bytes)
    """
```

Hii inaruhusu programu za kiutengenezaji kuonyesha maendeleo ya kupakia bila kubadilisha API ya msingi.

#### Zana za CLI (Command Line Interface)

**`tg-add-library-document`** inaendelea kufanya kazi bila kubadilika:

```bash
# Works transparently for any size - SDK handles chunking internally
tg-add-library-document --file large-report.pdf --title "Large Report"
```

Onyesho la maendeleo la hiari linaweza kuongezwa:

```bash
tg-add-library-document --file large-report.pdf --title "Large Report" --progress
# Output:
# Uploading: 45% (225MB / 500MB)
```

**Vifaa vya zamani vimetoolewa:**

`tg-load-pdf` - imepitwa na wakati, tumia `tg-add-library-document`
`tg-load-text` - imepitwa na wakati, tumia `tg-add-library-document`

**Amri za utawala/uchunguzi** (hiari, kipaumbele cha chini):

```bash
# List incomplete uploads (admin troubleshooting)
tg-add-library-document --list-pending

# Resume specific upload (recovery scenario)
tg-add-library-document --resume upload-abc-123 --file large-report.pdf
```

Haya yanaweza kuwa maboresho kwenye amri iliyopo badala ya zana tofauti.

#### Masuala ya Mabadiliko ya Vipimo vya API

Vipimo vya OpenAPI (`specs/api/paths/librarian.yaml`) vinahitaji mabadiliko kwa:

**Utendaji mpya:**

`begin-upload` - Anzisha kipindi cha kupakia kwa sehemu
`upload-chunk` - Pakia sehemu moja
`complete-upload` - Kamilisha kupakia
`abort-upload` - Ghairi kupakia
`get-upload-status` - Angalia maendeleo ya kupakia
`list-uploads` - Orodha ya kupakia ambayo hayaja kamili kwa mtumiaji
`stream-document` - Kuchukua hati kwa njia ya utiririshaji
`add-child-document` - Hifadhi maandishi yaliyotolewa (ya ndani)
`list-children` - Orodha ya hati za chini (ya msimamizi)

**Utendaji uliorekebishwa:**

`list-documents` - Ongeza parameter `include-children`

**Muundo mpya:**

`ChunkedUploadBeginRequest`
`ChunkedUploadBeginResponse`
`ChunkedUploadChunkRequest`
`ChunkedUploadChunkResponse`
`UploadSession`
`UploadProgress`

**Mabadiliko ya vipimo vya WebSocket** (`specs/websocket/`):

Nakala utendaji wa REST kwa wateja wa WebSocket, na kuwezesha
maendeleo ya muda halisi wakati wa kupakia.

#### Mambo ya Kuzingatia ya Uzoefu wa Mtumiaji

Mabadiliko ya vipimo vya API yanawezesha maboresho ya upande wa mbele:

**Kiolesura cha maendeleo ya kupakia:**
Pampu ya maendeleo ya kuonyesha sehemu zilizopakwa
Muda uliokadiri wa kupakia
Uwezo wa kusitisha/kuendeleza

**Kupona kwa makosa:**
Chaguo la "Endeleza kupakia" kwa kupakia ambacho kimekatika
Orodha ya kupakia ambayo hayaja kamili wakati wa kuunganisha tena

**Ushughulikiaji wa faili kubwa:**
Uchunguzi wa ukubwa wa faili kwenye upande wa mteja
Kupakia kwa sehemu kiotomatiki kwa faili kubwa
Maelezo wazi wakati wa kupakia kwa muda mrefu

Maboresho haya ya uzoefu wa mtumiaji yanahitaji kazi ya upande wa mbele inayong'wa na vipimo vya API vilivyoboreshwa.