Dokumentacja microfunc - gRPC Service Framework

Spis treści

Wprowadzenie
Instalacja
Architektura systemu
Plik konfiguracyjny microfunc.yaml
Zarządzanie zadaniami
Komunikacja zewnętrzna
Integracja z LLM
Zarządzanie usługami
Środowiska uruchomieniowe
Integracja z CI/CD
Przykłady użycia
Lista plików frameworka
Rozwiązywanie problemów

Wprowadzenie

gRPC Service Framework to kompleksowe narzędzie do zarządzania mikrousługami opartymi na protokole gRPC. Framework umożliwia:

Definiowanie usług w jednym pliku konfiguracyjnym YAML
Pobieranie plików źródłowych z różnych lokalizacji (lokalnych, Git, generowanych przez LLM)
Automatyczne generowanie kodu usług gRPC
Zarządzanie zadaniami manualnymi i automatycznymi
Komunikację z zewnętrznymi systemami przez webhooks i API
Obsługę zabezpieczeń z wykorzystaniem TLS
Integrację z systemami CI/CD
funkcje zarządzania zadaniami i zewnętrznej komunikacji, które uzupełniają istniejącą integrację z modelami językowymi (LLM)

Instalacja

Wymagania wstępne

Python 3.8+
Git
OpenSSL (opcjonalnie dla generowania certyfikatów)
Dostęp do API modelu językowego (dla funkcji LLM)

Instalacja z repozytorium

git clone https://github.com/org/grpc-service-framework.git
cd grpc-service-framework
pip install -r requirements.txt
python setup.py install

Szybki start

# Inicjalizacja nowego projektu
microfunc.py init moj-projekt
cd moj-projekt

# Generowanie plików za pomocą LLM
export OPENAI_API_KEY="twój-klucz-api"
microfunc.py llm-generate

# Budowanie usług
microfunc.py build

# Uruchamianie usług
microfunc.py up

Architektura systemu

gRPC Service Framework składa się z kilku kluczowych komponentów:

Konfigurator projektu - obsługuje plik microfunc.yaml i zarządza wszystkimi aspektami projektu
Generator usług gRPC - tworzy kod serwerów, klientów i definicji protobuf na podstawie funkcji źródłowych
Integracja z LLM - umożliwia generowanie kodu i innych zasobów przy użyciu modeli językowych
Menedżer zadań - zarządza zadaniami manualnymi i automatycznymi
Menedżer komunikacji - obsługuje webhooks i integracje z zewnętrznymi API
Runner usług - uruchamia i monitoruje usługi gRPC

                  +-------------------+
                  |   microfunc.yaml  |
                  +-------------------+
                           |
                           v
                  +-------------------+
                  |  Konfigurator     |
                  |     Projektu      |
                  +-------------------+
                           |
          +----------------+----------------+
          |                |                |
+-----------------+ +---------------+ +---------------+
|  Generator      | |  Menedżer     | |  Menedżer     |
|  usług gRPC     | |  Zadań        | |  Komunikacji  |
+-----------------+ +---------------+ +---------------+
          |                |                |
          |                v                |
          |        +---------------+        |
          +------->|  Integracja   |<-------+
                   |  z LLM        |
                   +---------------+
                           |
                           v
                  +-------------------+
                  |     Runner        |
                  |     Usług         |
                  +-------------------+

Plik konfiguracyjny

Wszystkie aspekty projektu są definiowane w pliku microfunc.yaml. Plik ten ma następującą strukturę:

version: '1.2'

sources:
  local: { ... }  # Pliki lokalne
  git: { ... }    # Pliki z repozytoriów Git
  llm: { ... }    # Pliki generowane przez LLM

certificates: { ... }  # Konfiguracja certyfikatów TLS

tasks:               # sekcja do zarządzania zadaniami
  manual: [ ... ]    # Zadania do wykonania przez człowieka
  automated: [ ... ] # Zadania automatyczne

communication:       # sekcja do komunikacji zewnętrznej
  webhooks: [ ... ]  # Konfiguracja webhooków
  apis: [ ... ]      # Konfiguracja integracji z API

services: { ... }    # Definicje usług gRPC

global: { ... }      # Ustawienia globalne

Sekcja `sources`

Definiuje źródła plików dla projektu:

sources:
  # Pliki lokalne
  local:
    functions:
      path: "./functions"
      files:
        - "printer_service.py"
  
  # Pliki z repozytoriów Git
  git:
    common_lib:
      url: "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/org/common-grpc-lib.git"
      branch: "main"
      path: "src/functions"
      files:
        - "auth.py"
  
  # Pliki generowane przez LLM
  llm:
    provider: "openai"
    model: "gpt-4"
    api_key_env: "OPENAI_API_KEY"
    
    generated_functions:
      path: "./llm_generated/functions"
      prompts:
        data_validator:
          output_file: "data_validator.py"
          prompt: "Stwórz funkcję walidacji danych..."
          parameters:
            temperature: 0.2

Sekcja `tasks` (nowa)

Definiuje zadania do wykonania w ramach projektu:

tasks:
  # Zadania manualne do wykonania przez człowieka
  manual:
    - id: "configure-printers"
      title: "Konfiguracja drukarek fizycznych"
      description: "Skonfiguruj drukarki termiczne w systemie operacyjnym."
      assignee: "admin@example.com"
      due_date: "2025-03-15"
      status: "pending"  # pending, in_progress, completed, blocked
      priority: "high"   # low, medium, high, critical
      tags: ["hardware", "configuration"]
      
  # Zadania automatyczne wykonywane przez system
  automated:
    - id: "generate-test-data"
      title: "Generowanie danych testowych"
      description: "Wygeneruj zestaw testowych etykiet."
      executor: "data-generator-bot"
      schedule: "0 0 * * *"  # Codziennie o północy (format cron)
      status: "pending"
      priority: "medium"
      tags: ["testing", "data"]
      script: "./scripts/generate_test_data.py"
      parameters:
        count: 100
        types: ["product", "shipping", "info"]

Sekcja `communication` (nowa)

Definiuje integracje z zewnętrznymi systemami:

communication:
  # Konfiguracja webhooków do powiadamiania o zdarzeniach
  webhooks:
    - id: "slack-notifications"
      url: "https://hooks.slack.com/services/YOUR_WEBHOOK_URL"
      events: ["service.start", "service.stop", "task.completed", "error"]
      format: "json"
      headers:
        Content-Type: "application/json"
        Authorization: "Bearer ${SLACK_API_TOKEN}"
  
  # Konfiguracja API do komunikacji z innymi systemami
  apis:
    - id: "inventory-system"
      type: "rest"
      base_url: "https://inventory.example.com/api/v1"
      auth_type: "oauth2"
      auth_config:
        client_id: "${INVENTORY_CLIENT_ID}"
        client_secret: "${INVENTORY_CLIENT_SECRET}"
        token_url: "https://inventory.example.com/oauth/token"
      endpoints:
        - path: "/products"
          method: "GET"
          description: "Pobieranie listy produktów"

Zarządzanie zadaniami

Nowy moduł zarządzania zadaniami umożliwia śledzenie i zarządzanie pracą w projekcie.

Typy zadań

Zadania manualne - muszą być wykonane przez człowieka
Zadania automatyczne - mogą być wykonane automatycznie przez system

Komendy CLI do zarządzania zadaniami

# Wyświetlanie listy wszystkich zadań
microfunc.py tasks list

# Wyświetlanie listy zadań o określonym statusie
microfunc.py tasks list --status pending

# Wyświetlanie szczegółów zadania
microfunc.py tasks show configure-printers

# Aktualizacja statusu zadania
microfunc.py tasks update configure-printers in_progress \
  --comment "Rozpoczęto konfigurację drukarek"

# Ręczne uruchomienie zadania automatycznego
microfunc.py tasks execute generate-test-data

Automatyczne wykonywanie zadań

Zadania automatyczne mogą być uruchamiane:

Według harmonogramu (format cron)
Na podstawie wyzwalaczy (np. on_deploy, on_commit)
Ręcznie przez użytkownika

Każde zadanie automatyczne ma skojarzony skrypt, który jest wykonywany przy uruchomieniu zadania.

Komunikacja zewnętrzna

Nowy moduł komunikacji umożliwia integrację z zewnętrznymi systemami.

Webhooks

Webhooks służą do powiadamiania zewnętrznych systemów o zdarzeniach:

Uruchomienie/zatrzymanie usługi
Zmiana statusu zadania
Błędy w systemie

# Ręczne wywołanie webhooka
microfunc.py communicate webhook error \
  --data-file ./error_details.json

Integracje API

Komponenty systemu mogą komunikować się z zewnętrznymi API:

REST API
gRPC API

# Wywołanie metody API
microfunc.py communicate api inventory-system /products \
  --params-file ./api_params.json

Integracja z LLM

Framework umożliwia generowanie kodu i innych zasobów przy użyciu modeli językowych.

Konfiguracja dostawcy LLM

llm:
  provider: "openai"  # openai, anthropic, custom
  model: "gpt-4"      # model do wykorzystania
  api_key_env: "OPENAI_API_KEY"  # zmienna środowiskowa z kluczem

Generowanie zasobów

# Generowanie wszystkich zasobów zdefiniowanych w konfiguracji
microfunc.py llm-generate

# Wymuszenie regeneracji, ignorując cache
microfunc.py llm-generate --force

Typy generowanych zasobów

Funkcje (generated_functions) - implementacje funkcji w Pythonie
Konfiguracje (generated_configs) - pliki konfiguracyjne, np. reguły walidacji
Proto definicje (generated_protos) - schemat API w formacie Protocol Buffers

Zarządzanie usługami

Pełny cykl życia usług gRPC:

# Synchronizacja plików z różnych źródeł
microfunc.py sync

# Budowanie usług
microfunc.py build

# Uruchamianie usług
microfunc.py up

# Sprawdzanie statusu usług
microfunc.py status

# Zatrzymywanie usług
microfunc.py down

Środowiska uruchomieniowe

Framework umożliwia definiowanie różnych konfiguracji dla środowisk:

environments/
├── development/
│   └── microfunc.yaml
├── staging/
│   └── microfunc.yaml
└── production/
    └── microfunc.yaml

Użycie konfiguracji dla konkretnego środowiska:

# Budowanie dla środowiska produkcyjnego
microfunc.py build --config environments/production/microfunc.yaml

Integracja z CI/CD

Framework można łatwo zintegrować z GitLab CI i GitHub Actions.

GitLab CI

# .gitlab-ci.yml
stages:
  - generate
  - build
  - deploy
  - notify

generate-code:
  stage: generate
  script:
    - export OPENAI_API_KEY=$OPENAI_API_KEY
    - microfunc.py llm-generate
  artifacts:
    paths:
      - llm_generated/

build-services:
  stage: build
  script:
    - microfunc.py build
  artifacts:
    paths:
      - generated/

deploy-services:
  stage: deploy
  script:
    - microfunc.py up
  when: manual

notify-deployment:
  stage: notify
  script:
    - microfunc.py communicate webhook service.start --data-file ./deployment-info.json

GitHub Actions

# .github/workflows/build-deploy.yml
name: Build and Deploy

on:
  push:
    branches: [ main ]

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate code with LLM
        run: |
          export OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }}
          microfunc.py llm-generate
  
  build:
    needs: generate
    runs-on: ubuntu-latest
    steps:
      - name: Build services
        run: microfunc.py build
  
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy services
        run: microfunc.py up
      
      - name: Notify deployment
        run: microfunc.py communicate webhook service.start

Przykłady użycia

Projekt drukarki etykiet

# microfunc.yaml
services:
  printer-service:
    function: 
      source: "local.functions"
      name: "printer_service.py"
    
  data-validator-service:
    function:
      source: "llm.generated_functions"
      name: "data_validator.py"

Dodanie zadania manualnego

# Ręczne dodanie zadania
cat > task.json << EOF
{
  "id": "update-drivers",
  "title": "Aktualizacja sterowników drukarek",
  "description": "Zaktualizuj sterowniki do najnowszej wersji",
  "assignee": "admin@example.com",
  "status": "pending",
  "priority": "medium"
}
EOF

microfunc.py tasks add --file task.json

Wywołanie webhooka

# Powiadomienie o błędzie
cat > error.json << EOF
{
  "error_type": "hardware",
  "message": "Utracono połączenie z drukarką",
  "device": "lp0"
}
EOF

microfunc.py communicate webhook error --data-file error.json

Lista plików frameworka

Poniżej znajduje się lista kluczowych plików wchodzących w skład frameworka:

Główne skrypty

microfunc.py - Główne narzędzie CLI
grpc_generator.py - Generator kodu gRPC

Moduły integracyjne

llm_integration.py - Integracja z modelami językowymi
task_manager.py - Zarządzanie zadaniami
communication_manager.py - Komunikacja zewnętrzna

Pliki konfiguracyjne

microfunc.yaml - Główny plik konfiguracyjny projektu
requirements.txt - Zależności Pythona

Pliki generowane

generated/ - Katalog z wygenerowanymi usługami
- [nazwa-usługi]/ - Katalog usługi
  - proto/ - Definicje Protocol Buffers
  - server/ - Kod serwera gRPC
  - client/ - Kod klienta gRPC
  - function/ - Kopia funkcji źródłowej
  - service.json - Konfiguracja usługi
llm_generated/ - Katalog z plikami wygenerowanymi przez LLM
- functions/ - Wygenerowane funkcje
- proto/ - Wygenerowane definicje Protocol Buffers
- config/ - Wygenerowane pliki konfiguracyjne
.registry/ - Lokalny rejestr funkcji
.llm_cache/ - Cache wyników LLM
tasks.db - Baza danych SQLite z zadaniami

Rozwiązywanie problemów

Najczęstsze problemy

1. Błędy z API LLM

Błąd: Nie znaleziono klucza API w zmiennej środowiskowej OPENAI_API_KEY

Rozwiązanie: Ustaw zmienną środowiskową OPENAI_API_KEY z właściwym kluczem API.

2. Problemy z generowaniem kodu Proto

Błąd: Nie można skompilować pliku proto

Rozwiązanie: Zainstaluj grpcio-tools i sprawdź poprawność wygenerowanego pliku proto.

3. Błędy podczas uruchamiania zadań automatycznych

Błąd: Nie znaleziono skryptu ./scripts/generate_test_data.py

Rozwiązanie: Upewnij się, że ścieżka do skryptu jest poprawna i ma uprawnienia do wykonywania.

Logi diagnostyczne

Wszystkie logi są zapisywane w katalogu logs/:

# Wyświetlenie logów głównego procesu
cat logs/app.log

# Wyświetlenie logów konkretnej usługi
cat logs/printer-service/service.log

Tryb debugowania

Aby uruchomić framework w trybie debugowania, ustaw zmienną środowiskową:

export GRPC_DEBUG=true
microfunc.py build

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.gitignore		.gitignore
README.md		README.md

micro-func/docs

Folders and files

Latest commit

History

Repository files navigation