Kusanya Ujuzi wa Mawakala wa Kuaminika Kuwa Mashine za Hali kwa HEXIS

HEXIS ni nini?

HEXIS ni kifurushi cha Python na zana ya mstari wa amri inayokusanya ujuzi wa wakala, unaowakilishwa na hati ya SKILL.md, kuwa mashine ya hali yenye kikomo iliyopanuliwa. Badala ya kuomba modeli ya lugha itafsiri ujuzi mzima na kuchagua kila hatua inayofuata, HEXIS hutumia hali, vigeu, walinzi na mipito ya kiprogramu ili kulazimisha mpangilio wa utendaji.

Modeli za lugha bado hufanya uelekezaji na uzalishaji ndani ya hali husika. Hata hivyo, mashine huamua operesheni inayofuata, vigeu vinavyopatikana, wakati mizunguko inapaswa kusimama, na matokeo ya mwisho yanayofikiwa. Muundo huu hupunguza hatari ya wakala kuruka, kubadilisha mpangilio, au kutumia isivyo sahihi masharti yaliyoandikwa kwenye ujuzi.

HEXIS imetolewa chini ya leseni ya MIT na kwa sasa imeainishwa kuwa programu ya alpha. Inaambatana na makala Compiling Agent Skills into Extended Finite State Machines.

Mtiririko mkuu wa kazi

Mtiririko wa kawaida wa HEXIS una hatua tatu:

1. Kusanya: Modeli husoma hati ya ujuzi, ingizo za kazi, ufafanuzi wa zana na sheria za ujuzi, kisha huandaa mashine ya efsm-v1. HEXIS hukagua skimu yake, walinzi, ufikikaji, ukomeshaji, ufunikaji wa vifungu na marejeleo ya zana. Rasimu zisizo sahihi hurudishwa kwa modeli ili zifanyiwe marekebisho.
2. Sasisha: Fuatiliaji mpya wa utekelezaji hubadilishwa kuwa matukio. Kwa kila hatua ya ufuatiliaji, modeli, faili la maamuzi au kipangaji cha kiotomatiki huamua iwapo itaendana na hali iliyopo, itaunda hali, itapuuza kelele, au itaondoa ufuatiliaji.
3. Tekeleza: Mazingira ya utekelezaji hufanya kitendo kinachohusishwa na hali ya sasa, huhifadhi matokeo yaliyotangazwa, na kuchukua mpito wa kwanza ambao mlinzi wake hutathminiwa kuwa kweli.

Mashine iliyosasishwa hukubaliwa tu inapopitisha ukaguzi unaohitajika na inaweza kucheza tena ufuatiliaji mpya pamoja na kila ufuatiliaji uliokubaliwa hapo awali. Uthibitishaji ukishindwa, mashine iliyopo hubaki bila kubadilishwa.

Vipengele muhimu

• Ukusanyaji unaooana na OpenAI: Chagua modeli, kituo cha mwisho na kigeu cha mazingira cha ufunguo wa API kutoka kwenye mstari wa amri.
• Sasisho zinazoegemea ufuatiliaji: Jumuisha tabia ya utekelezaji iliyofaulu uamuzi mmoja kwa wakati bila kubatilisha ufuatiliaji uliokubaliwa hapo awali.
• Mashine za JSON zinazosomwa: Mashine hutumia muundo wa kawaida wa JSON wa efsm-v1 wenye vigeu vilivyo na aina na mipito iliyo wazi.
• Aina nyingi za vitendo: Hali zinaweza kutekeleza vitendo vya tool, model, judge, user au end.
• Mtiririko wa udhibiti wenye mipaka: Walinzi waliopangwa na vihesabu vya mizunguko huwezesha matawi na mipaka ya majaribio tena.
• Nyaraka zinazozalishwa: Kila uundaji wa kawaida hujumuisha GUIDE.md na PROMPT.md.
• Tabia ya akiba: Hali ya akiba hujaribu tena kuanzia hatua ya hivi karibuni ya zana na inaweza kukabidhi kazi kwenye utekelezaji unaotafsiriwa wa ujuzi wa awali.
• Misingi ya zana: Mashine zinaweza kutumia zana za OpenCode, kitekelezaji cha Bash cha ndani, au zana zilizobainishwa kwenye sajili na kutekelezwa na modeli.
• Maj testing hermetic: Hazina ina zaidi ya majaribio 350 ambayo hayahitaji ufunguo wa API, kituo cha mwisho cha modeli au muunganisho wa mtandao.

Usakinishaji na mahitaji ya awali

Usakinishe kutoka PyPI

HEXIS inahitaji Python 3.11 au 3.12. Sakinisha kifurushi kwa pip:

pip install hexis-agent

Kifurushi huingizwa kwenye Python kama hexis, huku kitekelezi chake cha mstari wa amri kikiitwa hexis-agent.

Usakinishe kutoka kwenye checkout

pip install .

Kwa vitegemezi vya usanidi kama pytest, Ruff, build na Twine, tumia usakinishaji wa kuhaririwa:

pip install -e ".[dev]"

Mahitaji ya wakati wa utekelezaji

Kukusanya na kuendesha mashine zinazotegemea modeli kunahitaji kituo cha mwisho cha mazungumzo kinachoendana na OpenAI. Kihifadhi chaguo-msingi cha utekelezaji pia kinatarajia OpenCode iwe kwenye PATH. Ikiwa mashine inahitaji Bash pekee, chagua --executor local ili kuendesha amri katika subprocess ya ndani bila OpenCode.

Jaribu uanzishaji wa haraka nje ya mtandao

Kifurushi kinajumuisha mfano mdogo wa hermetic unaoitwa table_clean. Unatumia modeli iliyoandikwa, zana zilizoandikwa na mfumo wa faili wa kumbukumbu, hivyo unaweza kuendeshwa bila ufikiaji wa mtandao.

from hexis.execution import runtime
from hexis.examples import table_clean as tc

machine = tc.reference_machine()
task = tc.gen_tasks(1, seed=0)[0]

result = runtime.run_task(
    machine,
    task,
    model=tc.build_model(),
    tools=tc.build_registry(tc.MemFS(task["files"])),
    doc=tc.skill_doc(),
)

print(
    result.stopped,
    " -> ".join(result.path()),
    tc.verify(task, result.trace),
)

Mfano huo unapaswa kumalizia kwa matokeo ya mwisho, kuchapisha njia ya hali, na kuripoti iwapo ufuatiliaji uliotengenezwa unapita kithibitishaji cha mfano. Ni njia muhimu ya kuthibitisha kuwa usakinishaji umefaulu kabla ya kusanidi kituo cha mwisho cha nje.

Sanidi kituo cha mwisho cha modeli

HEXIS husoma kitambulisho cha modeli, URL ya msingi na ufunguo wa API kutoka kwenye chaguo za mstari wa amri au vigeu vya mazingira. Usanidi wa msingi wa shell unaonekana hivi:

export API_KEY=your-key
export MODEL=qwen3.6-flash
export BASE_URL=https://your-endpoint/v1

Pia unaweza kuweka MODEL, BASE_URL na API_KEY katika faili la .env. HEXIS hutafuta kuelekea juu kutoka kwenye saraka ya kazi, na vigeu ambavyo tayari vipo kwenye mazingira hupewa kipaumbele.

Ili kuhifadhi hoja za kituo cha mwisho zinazoweza kutumika tena katika kigeu cha shell:

M="--model qwen3.6-flash --base-url https://your-endpoint/v1"

Chaguo la --api-key-env NAME huchagua kigezo tofauti cha mazingira kwa ajili ya ufunguo. Funguo za API hazipitishwi kwenye mstari wa amri wala kuhifadhiwa kwenye manifesti ya uundaji.

Kusanya ujuzi kuwa mashine

Elekeza mkusanyaji kwenye njia ya ujuzi na uchague saraka ya matokeo:

hexis-agent compile \
  --skill path/to/skill \
  --out build/ \
  $M

Saraka ya ujuzi inapaswa kuwa na SKILL.md. Inaweza pia kuwa na compile.json, ambayo inaweza kutangaza vituo, lebo za matukio zilizotokana, mahitaji, na masharti ya vituo. Kila kanuni katika faili hilo hunukuu sentensi iliyotumika kuitoa.

Ikiwa compile.json haipo, mkusanyaji huiomba modeli itoe kanuni kutoka kwenye ujuzi na hukagua maandishi yaliyonukuliwa dhidi ya hati. Kisha usanidi unaotumika huhifadhiwa kama rules.json.

Yaliyomo kwenye saraka ya uundaji

• machine.json huhifadhi mashine ya sasa.
• machine_init.json huhifadhi mashine ya awali iliyokusanywa.
• build.json hurekodi maelezo ya chanzo, mipangilio ya amri, maelezo ya modeli, matokeo, na matumizi ya tokeni, lakini kamwe si ufunguo wa API.
• skill/SKILL.md, tools.json, na rules.json huhifadhi vipengele vya kuingiza vilivyotumika katika mkusanyaji.
• traces/ huwa na nakala zenye heshi za ufuatiliaji zilizotumiwa na uundaji.
• progress.json hurekodi matokeo ya ufuatiliaji na ufuatiliaji uliokubaliwa unaolinda mashine.
• decisions.jsonl huhifadhi kwa muda maswali na majibu ya masasisho.
• report.md, context.json, na faili za kumbukumbu hutoa taarifa za uchunguzi.
• GUIDE.md hueleza vipengele vya kuingiza, zana, hali, mabadiliko, mizunguko, na tabia ya kurejea.
• PROMPT.md hutoa kidokezo cha mfumo kwa wakala anayetumia zana ili kutekeleza hali za mashine moja baada ya nyingine.

Kuelewa modeli ya mashine

Mashine ya HEXIS ni hati ya JSON inayotumia umbizo la efsm-v1. Vipengele vyake vikuu ni vigezo, hali, vitendo, mabadiliko, vituo, na hali ya kurejea.

Vigezo

Vigezo vinaweza kuanzishwa kutoka kwenye sehemu za ingizo la kazi kwa kutumia init_from, au kutoka kwenye thamani thabiti kwa kutumia init. Vitendo huandika matokeo yake kwenye vigezo vilivyotangazwa pekee.

Vitendo

• Modeli: Hutengeneza vigezo vilivyotangazwa kutoka kwenye kidokezo maalum cha hali na vigezo vya ingizo vilivyochaguliwa.
• Zana: Huita zana iliyopewa jina. Marejeo kama ${command} hubadilishwa wakati wa utekelezaji.
• Jaji: Huchagua lebo kutoka kwenye seti isiyobadilika au kurudisha lebo ya abstain.
• Mtumiaji: Huomba ingizo kutoka kwa mtumiaji.
• Maliza: Husimamisha utekelezaji kwa matokeo ya kituo.

Mabadiliko na masharti

Mabadiliko hutathminiwa kwa mpangilio baada ya kitendo cha hali kumaliza. Wakati wa utekelezaji huchukua mabadiliko ya kwanza ambayo sharti lake limetimia. Sharti tupu halina masharti na linapaswa kuwa la mwisho. Mabadiliko yanaweza pia kuongeza kihesabu kupitia inc, hivyo kuwezesha mizunguko ya majaribio yenye kikomo.

Masharti hutumia lugha ya vielezi yenye vikwazo inayotekelezwa na hexis.machine.cond. Inaauni uchanganuzi tuli wa sifa kama vile kutotegemeana na mipaka ya mizunguko, na haitumii eval ya Python.

Kusasisha mashine kutoka kwenye ufuatiliaji

Ufuatiliaji wa utekelezaji ni faili za JSON Lines. Huanzia na metadata ya kazi na uamuzi, ikifuatiwa na tukio moja kwa kila mstari. Ufuatiliaji unaweza kuwa na miito ya zana, matokeo ya modeli, na tukio la mwisho.

Kwanza hakiki ufuatiliaji unaosubiri bila kufanya miito ya modeli au kuandika mabadiliko:

hexis-agent update \
  --build build/ \
  --traces traces/ \
  --show 3

Kisha fanya sasisho:

hexis-agent update \
  --build build/ \
  --traces traces/ \
  $M

Kwa kila hatua ya ufuatiliaji, mtoa uamuzi huchagua mojawapo ya matokeo manne:

• match hutumia tena hali iliyopo na kuongeza mabadiliko ikihitajika.
• new huunda hali kulingana na madhumuni yaliyotajwa.
• ignore huondoa kelele za mfumo wa majaribio kwenye uzingatiaji.
• exclude huacha ufuatiliaji mzima nje.

Jibu la modeli pia hutambua hali inayopendekezwa, hueleza madhumuni ya hatua, na linaweza kuihusisha na kifungu cha ujuzi. HEXIS huidhinisha mashine inayopendekezwa na kuendesha tena ufuatiliaji wote uliolindwa kabla ya kuikubali.

Kuendelea na kudhibiti gharama za sasisho

Majibu ya modeli huhifadhiwa kwenye decisions.jsonl. Kurudia amri ileile hutumia tena majibu hayo, huku uendeshaji uliokatizwa wenye hali ya kutoka 3 ukiweza kuendelea kutoka kwenye maendeleo yaliyohifadhiwa. Tumia --no-cache tu unapokusudia modeli ijibu tena.

Sasisho kwa kawaida hugharimu karibu mwito mmoja wa modeli kwa kila hatua ya ufuatiliaji. Tumia --max-traces N kuweka kikomo cha uendeshaji. Kwa njia mbadala zisizotumia modeli, toa maamuzi ya binadamu au ya nje kupitia --decisions FILE, au chagua ulinganishaji unaobainishwa kwa kutumia --decider align.

Kabla ya kuchakata ufuatiliaji mpya, HEXIS hukagua mashine ya sasa na kuendesha tena kila ufuatiliaji uliokubaliwa. Ikiwa uhariri wa mkono au ufafanuzi wa zana uliobadilishwa umevunja uundaji, amri hutoka ikiwa na hali 2 bila kuubadilisha.

Kuendesha mashine iliyokusanywa

Kagua build/GUIDE.md kabla ya utekelezaji. Hati hiyo inaeleza ingizo za kazi zinazohitajika, zana zinazopatikana, vitendo vya hali, mpangilio wa mabadiliko, mipaka ya majaribio tena, na tabia ya kurejea.

Endesha mashine kwa kutumia ingizo za kazi za jozi ya ufunguo na thamani:

hexis-agent run \
  --machine build/ \
  --input request="Process this task" \
  --workdir work/ \
  --executor local \
  $M

Pitisha chaguo za ziada za --input KEY=VALUE kwa kila ingizo linalotarajiwa na mashine. Ili kuhifadhi utekelezaji kama ufuatiliaji wa JSON Lines unaoweza kutumika tena, ongeza:

--json run-trace.jsonl

Kitekelezaji chaguo-msingi hutumia zana za OpenCode. Kitekelezaji cha ndani huendesha amri za Bash katika mchakato mdogo. Wakati wa utekelezaji, mashine inaweza kutumia tu zana zinazotolewa na mfumo wake wa nyuma au zilizobainishwa katika sajili ya zana; HEXIS haibadilishi kimya kimya zana zinazokosekana.

Tumia mashine kutoka Python

Sehemu kuu ya kuanzia wakati wa utekelezaji ni hexis.execution.runtime.run_task. Toa mashine iliyopakiwa, jukumu lenye kitu cha input, adapta ya modeli, sajili ya zana, na hati ya ujuzi wakati utekelezaji wa akiba unaweza kuhitaji hati hiyo.

from hexis.execution import runtime

result = runtime.run_task(
    machine,
    {"input": {
        "request": "Answer the question",
        "output_path": "answer.txt",
    }},
    model=model,
    tools=tools,
    doc=skill_document,
)

print(result.stopped)
print(result.path())
print(result.trace)

API zinazohusiana zinajumuisha hexis.machine.schema.load_machine kwa kupakia mashine, hexis.llm.llm_client.client_from_env kwa kusanidi kituo cha mwisho, na vitendaji vya hexis.guide kwa kutoa miongozo, vidokezo, na michoro ya Mermaid.

Fanya kazi na mashine za mifano zilizotolewa

Hifadhi hii inajumuisha mashine nne zilizokusanywa katika examples/machines/:

• dabench: Hujibu swali la uchanganuzi wa data kuhusu faili ya data kwa kutumia hesabu.
• livemath: Hujibu swali la hisabati la chaguo nyingi linalotegemea nadharia.
• sealqa: Hujibu swali kutoka kwenye mkusanyo wa ndani na kujumuisha ushahidi.
• spreadsheet: Huhariri kitabu cha kazi bila kubadilisha muundo wake.

Mashine hizi kwa kawaida hutumia hali ya modeli kuandika amri ya ganda, hali ya zana kuitekeleza, majaribio ya kurudia yaliyolindwa kulingana na returncode, hatua ya zana inayosoma jibu, na hali ya mwamuzi inayochagua kituo cha mwisho kilichothibitishwa au kisichothibitishwa.

Kwa mfano, endesha mashine ya LiveMath kwa:

hexis-agent run \
  --machine examples/machines/livemath \
  --input request="..." \
  --input output_path=answer.txt \
  --workdir work/ \
  --executor local \
  $M

Mashine za mifano zinaweza kupakiwa na kukaguliwa kimuundo bila modeli, lakini kuziendesha kunahitaji kituo cha mwisho cha modeli kilichosanidiwa.

Vidokezo vya kina

Tengeneza upya nyaraka

Ukusanyaji na masasisho hutengeneza nyaraka kiotomatiki isipokuwa --no-guide itumike. Zitenge upya kwa mikono kwa:

hexis-agent guide --build build/

Unaweza pia kuelekeza amri moja kwa moja kwenye machine.json. Ongeza --embed-skill unapotaka kidokezo cha wakala kilichozalishwa kijumuishe ujuzi wa asili, hivyo kuruhusu utekelezaji uliotafsiriwa baada ya utekelezaji wa akiba.

Toa ufafanuzi dhahiri wa zana

Pitisha --tools registry.json wakati mashine inatumia zana maalum. Majina ya zana hushughulikiwa kama vitambulishi visivyo na maana maalum wakati wa ukusanyaji. Wakati wa utekelezaji, zana zilizobainishwa kwenye sajili zinaweza kutekelezwa kama amri za ganda na modeli, huku zana asili zikihitaji kutolewa na mfumo wa nyuma uliochaguliwa.

Rekebisha maombi ya modeli

Ukusanyaji na masasisho yanaunga mkono chaguo zikiwemo --temperature, --max-tokens, --llm-timeout, --llm-retries, --stream, na --extra-body JSON. Kwa vituo vya mwisho vinavyooana na Qwen, hoja za wakati wa utekelezaji zinaweza kudhibitiwa kwa --no-think, --think-budget, na --judge-think-budget.

Tumia vigezo vya mazingira maalum kwa mtoa huduma

Chaguo la --provider NAME husoma NAME_MODEL, NAME_BASE_URL, na NAME_API_KEY. Chaguo-msingi zilizojengewa ndani zinapatikana kwa majina ya watoa huduma MiniMax na DeepSeek.

Jua hali za kutoka

• 0 huonyesha mafanikio.
• 2 huonyesha tatizo la matumizi, usanidi, au ujenzi.
• 3 huonyesha hitilafu au kukatizwa kwa kituo cha mwisho cha modeli; maendeleo huhifadhiwa ili kuendelezwa tena.

Endesha ukaguzi wa uendelezaji

pytest
ruff check src tests
python -m build && twine check --strict dist/*

Seti ya majaribio ni hermetiki. Majaribio mahususi ya OpenCode hurukwa wakati kitekelezi cha opencode hakipatikani.

Usalama na faragha

HEXIS inaweza kutekeleza hoja za zana zinazozalishwa na modeli za lugha, zikiwemo amri za ganda. Endesha mizigo ya kazi isiyoaminika katika mazingira yaliyotengwa, na tumia tu mashine, ujuzi, sajili, na faili za majukumu unazoziamini.

Mchakato wa kusasisha hutuma hatua za ufuatiliaji, matokeo mafupi ya zana, na vifungu vya ujuzi kwenye kituo cha mwisho cha modeli kilichosanidiwa. Saraka za ujenzi huhifadhi nakala za ufuatiliaji na maswali ya modeli. Aidha, PROMPT.md ina mashine kamili na vidokezo vilivyotokana na ujuzi. Kagua vitu hivi kabla ya kuvishiriki.

Muda wa utekelezaji huwekea kila mwito wa modeli kikomo cha kidokezo cha hali inayotekelezwa kwa sasa, badala ya kufichua mashine nzima kwa kila mwito.

Hitimisho

HEXIS hubadilisha maagizo ya wakala yaliyo katika lugha asilia kuwa mtiririko wa kazi ulio wazi na uliothibitishwa. Kwa kuchanganya hoja za modeli ndani ya hali na mabadiliko ya kiprogramu, uchezaji upya wa ufuatiliaji, majaribio ya kurudia yenye mipaka, vizuizi vya zana, miongozo iliyozalishwa, na ushughulikiaji wa utekelezaji wa akiba, inatoa njia iliyopangwa ya kufanya utekelezaji wa ujuzi uwe wa kutabirika zaidi. Anza na mfano wa nje ya mtandao, kusanya ujuzi mdogo unaoaminika, kagua mwongozo uliotengenezwa, kisha anzisha ufuatiliaji hatua kwa hatua huku ukifuatilia matokeo ya uthibitishaji.