[docs] Add guide for implementing typescript agent

docs/examples/TypeScript/agent.ts

@@ -0,0 +1,126 @@
+import { client } from '@api/sc';
+import { ScAddr, ScConstruction, ScLinkContent, ScTemplate, ScType, ScLinkContentType } from 'ts-sc-client';
+
+
+export const check = async(action: ScAddr,keynodes: Record<string, ScAddr>) => {
+    const checkTemplate = new ScTemplate();
+    checkTemplate.triple(                        // класс_действия
+        keynodes["get_set_power_action"],  //   |
+        ScType.EdgeAccessVarPosPerm,             //   \/
+        action,                                  // действие
+    );
+    const checkResult = await client.templateSearch(checkTemplate);
+    if (checkResult.length==0)
+        {
+            return false;
+
+        }
+    return true;
+}
+
+export const getSetPowerAgent = async(subscribedAddr: ScAddr, foundEdge: ScAddr, actionNode: ScAddr) => {
+    const getSetPowerAction = "get_set_power_action";
+    const action = 'action';
+    const actionInitiated = 'action_initiated';
+    const actionFinished = 'action_finished';
+    const actionFinishedSuccessfully = 'action_finished_successfully';
+    const actionFinishedUnsuccessfully = 'action_finished_unsuccessfully';
+    const nrelResult = 'nrel_result';
+    const nrelSetPower="nrel_set_power";
+    const rrel1 = 'rrel_1';
+    const baseKeynodes = [
+        { id: getSetPowerAction, type: ScType.NodeConstClass },
+        { id: rrel1, type: ScType.NodeConstRole },
+        { id: nrelResult, type: ScType.NodeConstNoRole },
+        { id: nrelSetPower, type: ScType.NodeConstNoRole },
+        { id: actionFinished, type: ScType.NodeConstClass },
+        { id: actionFinishedSuccessfully, type: ScType.NodeConstClass },
+        { id: actionFinishedUnsuccessfully, type: ScType.NodeConstClass },
+        { id: action, type: ScType.NodeConstClass },
+        { id: actionInitiated, type: ScType.NodeConstClass },
+    ];   
+    const keynodes = await client.resolveKeynodes(baseKeynodes); //собрали все кейноды из БЗ
+    if(await check(actionNode,keynodes)===false) //сделали проверку на класс действия
+    {
+        return;
+    }
+
+    const setAlias = '_set'; //узел множества
+    const elAlias = '_el'; //узел элемента множества
+    const template = new ScTemplate(); 
+    template.triple(                            // класс_действия
+        keynodes[getSetPowerAction],            //   |
+        ScType.EdgeAccessVarPosPerm,            //   \/
+        actionNode,                             // действие
+    )
+    template.tripleWithRelation(
+        actionNode,                         // действие
+        ScType.EdgeAccessVarPosPerm,        //   ||<--rrel_1(аргумент)
+        [ScType.NodeVar, setAlias],         //   \/
+        ScType.EdgeAccessVarPosPerm,        // множество
+        keynodes[rrel1],
+    )
+    template.triple(                        // множество
+        setAlias,                           //   |
+        ScType.EdgeAccessVarPosPerm,        //   \/
+        [ScType.NodeVar, elAlias],          // элемент
+    )
+    const result=await client.templateSearch(template);
+    if (!result.length) { //если конструкция не найдена
+        const finalConstruction= new ScConstruction();
+        finalConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[actionFinished], actionNode);
+        finalConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[actionFinishedUnsuccessfully], actionNode);
+        await client.createElements(finalConstruction); 
+        return ;
+    }
+
+
+    const elements:ScAddr[] = [];
+    for (let i = 0; i < result.length; i++) {  //выбираем элемент множества из кажой найденной конструкции(!!!в одной конструкции у множества только один элемент)
+        elements.push(result[i].get(elAlias));
+    }
+    const set = result[0].get(setAlias); // выбираем узел самого множества из первой найденной конструкции, потому что узел множества он и в Африке узел множества
+    const power = elements.length.toString();;
+
+
+    const powerSetConstruction = new ScConstruction(); //конструкция,где будет только множество и его мощность
+    const setPowerLinkAlias="set_power_link"; //метки для всех будущих элементов
+    const edgeCommonSetPowerAlias="edge_common_set_power";
+    const edgePosPermSetPowerAlias="edge_pos_perm_set_power";
+    const resultConstructionNodeAlias="result_construction_node";
+    const edgePosPermResultAlias="edge_pos_perm_result";
+    const edgeCommonResultAlias="edge_common_result";
+    powerSetConstruction.createLink(ScType.LinkConst,new ScLinkContent(power, ScLinkContentType.String),setPowerLinkAlias);//создаем ссылку с числом                                              ссылка
+    powerSetConstruction.createEdge(ScType.EdgeDCommonConst,set,setPowerLinkAlias,edgeCommonSetPowerAlias); //соединяем ее с множеством дугой для отношений                                                       /\
+    powerSetConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[nrelSetPower],edgeCommonSetPowerAlias,edgePosPermSetPowerAlias); //соедиянемя nrel_set_power с предыдущей дугой          ||<--nrel_set_power
+    const powerSetRes = await client.createElements(powerSetConstruction);                                                                 //                                                    множестов
+    if (powerSetRes && powerSetRes.length > 0) {
+        const resultConstruction = new ScConstruction(); //конструкция,где действие будет соединяться с предыдущей конструкцией отношением nrel_result
+        resultConstruction.createNode(ScType.NodeConst,resultConstructionNodeAlias); //создаем узел-посредний
+        resultConstruction.createEdge(ScType.EdgeDCommonConst,actionNode,resultConstructionNodeAlias,edgePosPermResultAlias);// соединяем с действием дугой для отношений
+        resultConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[nrelResult],edgePosPermResultAlias,edgeCommonResultAlias); //соедиянемя nrel_result с предыдущей дугой
+        resultConstruction.createEdge(ScType.EdgeAccessConstPosPerm,resultConstructionNodeAlias,powerSetRes[powerSetConstruction.getIndex(setPowerLinkAlias)]);// соединяем узел-посредний со всеми элементами powerSetConstruction
+        resultConstruction.createEdge(ScType.EdgeAccessConstPosPerm,resultConstructionNodeAlias,set);
+        resultConstruction.createEdge(ScType.EdgeAccessConstPosPerm,resultConstructionNodeAlias,powerSetRes[powerSetConstruction.getIndex(edgeCommonSetPowerAlias)]);
+        resultConstruction.createEdge(ScType.EdgeAccessConstPosPerm,resultConstructionNodeAlias,powerSetRes[powerSetConstruction.getIndex(edgePosPermSetPowerAlias)]);
+        resultConstruction.createEdge(ScType.EdgeAccessConstPosPerm,resultConstructionNodeAlias,keynodes[nrelSetPower]);
+        const resultRes = await client.createElements(resultConstruction);
+        if (resultRes && resultRes.length > 0) {
+            const finalConstruction= new ScConstruction();
+            finalConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[actionFinished], actionNode);
+            finalConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[actionFinishedSuccessfully], actionNode);
+            await client.createElements(finalConstruction); 
+            return ;
+        }
+        const finalConstruction= new ScConstruction();
+        finalConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[actionFinished], actionNode);
+        finalConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[actionFinishedUnsuccessfully], actionNode);
+        await client.createElements(finalConstruction); 
+        return ;
+    }
+    const finalConstruction= new ScConstruction();
+    finalConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[actionFinished], actionNode);
+    finalConstruction.createEdge(ScType.EdgeAccessConstPosPerm,keynodes[actionFinishedUnsuccessfully], actionNode);
+    await client.createElements(finalConstruction); 
+    return ;
+};

docs/examples/TypeScript/client.ts

@@ -0,0 +1,23 @@
+import { SC_URL } from '@constants';
+import { ScClient,ScType,ScEventParams,ScEventType } from 'ts-sc-client';
+import { getSetPowerAgent } from "@agents/agent"
+
+async function testAgent() {
+    const actionInitiated = "action_initiated";
+    const keynodes = [
+        { id: actionInitiated, type: ScType.NodeConstNoRole },
+    ];
+
+    const keynodesAddrs = await client.resolveKeynodes(keynodes);
+
+    const eventParams = new ScEventParams(keynodesAddrs[actionInitiated], ScEventType.AddOutgoingEdge, getSetPowerAgent);
+    await client.eventsCreate([eventParams]); 
+}
+
+export const client = new ScClient(SC_URL);
+testAgent();
+
+
+
+
+

docs/index.md

@@ -8,46 +8,47 @@ At its core, sc-machine operates as a **graph database management system**, enab
 
 Table of contents:
 
-- [Quick Start](quick_start.md) - *get up and running with sc-machine quickly*
+- [Quick start](quick_start.md) - *get up and running with sc-machine quickly*
 - [Docker](docker.md) - *get up and running with sc-machine in docker*
-- **User Guides** - *detailed instructions on implementing agents*
+- **User guides** - *detailed instructions on implementing agents*
     * C++ Guides - *guidelines for implementing agents on C++*
-        * [C++ Simple Guide for Implementing Agent](sc-memory/api/cpp/guides/simple_guide_for_implementing_agent.md)
-    * [Migrate to New Agent API](sc-tools/migrate_to_new_agent_api.md) - *description of script that can be used to migrate to new C++ Agents API*
+        * [C++ Simple guide for implementing agent](sc-memory/api/cpp/guides/simple_guide_for_implementing_agent.md)
+    * [Migrate to new agent API](sc-tools/migrate_to_new_agent_api.md) - *description of script that can be used to migrate to new C++ Agents API*
 - **API** - *comprehensive documentation for C++, Python, and TypeScript APIs*
     * C++ API - *detailed guides on using the core and extended APIs for interacting with sc-memory*
         * [C++ Core API](sc-memory/api/cpp/core/api.md) - *documentation of C++ core API for creating, retrieving and erasing sc-elements in sc-memory*
         * C++ Extended API - *documentation of C++ extended API for manipulating with system identifiers of sc-elements and sc-templates*
-            * [C++ System Identifier API](sc-memory/api/cpp/extended/helper_api.md) - *documentation of C++ extended API for manipulating with system identifiers of sc-elements*
+            * [C++ System identifier API](sc-memory/api/cpp/extended/helper_api.md) - *documentation of C++ extended API for manipulating with system identifiers of sc-elements*
             * [C++ ScTemplate API](sc-memory/api/cpp/extended/template_api.md) - *documentation of C++ extended API for creating and retrieving graphs (it is very useful when you want to work big sc-constructions)* 
             * C++ Agents API - *documentation of C++ Agents API for creating agents*
                 * [C++ Events API](sc-memory/api/cpp/extended/agents/events.md) - *enables developers to create and manage events within the sc-machine, allowing agents to respond dynamically to various triggers*
-                * [C++ Event Subscriptions API](sc-memory/api/cpp/extended/agents/event_subscriptions.md) - *details how agents can subscribe to specific events and receive notifications when those events occur*
+                * [C++ Event subscriptions API](sc-memory/api/cpp/extended/agents/event_subscriptions.md) - *details how agents can subscribe to specific events and receive notifications when those events occur*
                 * [C++ Waiters API](sc-memory/api/cpp/extended/agents/waiters.md) - *allows developers to implement wait conditions that pause agent execution until specified conditions are met or events are triggered*
                 * [C++ Keynodes API](sc-memory/api/cpp/extended/agents/keynodes.md) - *provides functionality for creating, retrieving, and manipulating keynodes, which represent significant concepts within the knowledge graph*
                 * [C++ Actions API](sc-memory/api/cpp/extended/agents/actions.md) - *outlines how to define and initiate actions that agents can perform, detailing their arguments and results*
                 * [C++ Agents API](sc-memory/api/cpp/extended/agents/agents.md) - *focuses on agent creation and management*
-                * [C++ Agent Context API](sc-memory/api/cpp/extended/agents/agent_context.md) - *explains how to manage the context in which agents operate*
+                * [C++ Agent context API](sc-memory/api/cpp/extended/agents/agent_context.md) - *explains how to manage the context in which agents operate*
                 * [C++ Modules API](sc-memory/api/cpp/extended/agents/modules.md) - *describes how to register agents in an application*
     * Python API - *documentation on using the Python client for interacting with sc-memory*
         * [Python Core API](https://github.com/ostis-ai/py-sc-client) - *documentation of Python core API for creating, retrieving and erasing sc-elements and sc-events in sc-memory*
         * [Python Extended API](https://github.com/ostis-ai/py-sc-kpm) - *documentation of Python extended API for manipulating with large graphs*
     * TypeScript API - *documentation on using the TypeScript client for interacting with sc-memory*
         * [TypeScript Core API](https://github.com/ostis-ai/ts-sc-client) - *documentation of TypeScript core API for creating, retrieving and erasing sc-elements and sc-events in sc-memory*
-    * [sc-element Types](scs/sc_element_types.md) - *detailed description of supported element types*
+        * [Typescript Simple guide for implementing agent](sc-memory/api/typescript/ts_agent_guide.md) - *documentation of Typescript API provided by ts-sc-client*
+    * [sc-element types](scs/sc_element_types.md) - *detailed description of supported element types*
     * [SCs-code](scs/scs.md) - *documentation on SCs Language with examples*
 - **Tools** - *information on various tools that enhance your experience with sc-machine*
-    * [Knowledge Base Builder](sc-tools/sc_builder.md) - *description of options of sc-builder for knowledge base sources*
-    * [Knowledge Base Repo File](sc-tools/kb_repo_file.md) - *description of configuration of knowledge base sources*
+    * [Knowledge Base builder](sc-tools/sc_builder.md) - *description of options of sc-builder for knowledge base sources*
+    * [Knowledge Base repo file](sc-tools/kb_repo_file.md) - *description of configuration of knowledge base sources*
     * [sc-machine Runner](sc-tools/sc_machine.md) - *description of options of sc-machine runner*
-- **Build Instructions** - *guidelines for building the project, configuring settings*
-    * [Quick Start for Developers](build/quick_start.md) - *get up and start developing sc-machine quickly*
-    * [Build System](build/build_system.md) - *how to build the project and use it as a library*
+- **Build instructions** - *guidelines for building the project, configuring settings*
+    * [Quick start](build/quick_start.md) - *get up and start developing sc-machine quickly*
+    * [Build system](build/build_system.md) - *how to build the project and use it as a library*
     * [CMake Flags](build/cmake_flags.md) - *description of CMake flags used to configure sc-machine*
     * [Configuration File](build/config.md) - *description of a configuration file of sc-machine*
 - **Development** - *guidelines for contributing to development*
     * [Contributing Guide](https://github.com/ostis-ai/sc-machine/blob/main/CONTRIBUTING.md) - *guide for those who wants to make contribution into sc-machine*
-    * [Code Style Guide](dev/codestyle.md) - *guide for those who wants to write code for sc-machine*
+    * [Codestyle Guide](dev/codestyle.md) - *guide for those who wants to write code for sc-machine*
     * [Dev Container](dev/devcontainer.md) - *guide for those who wants to develop sc-machine via docker*
 - [License](https://github.com/ostis-ai/sc-machine/blob/main/COPYING.MIT)
 - [Changelog](changelog.md)