{"id":23196255,"url":"https://github.com/kiss-ai-stack/kiss-ai-stack-server","last_synced_at":"2026-04-14T06:04:45.365Z","repository":{"id":268283919,"uuid":"895650454","full_name":"kiss-ai-stack/kiss-ai-stack-server","owner":"kiss-ai-stack","description":"Communication service for KISS AI stack.","archived":false,"fork":false,"pushed_at":"2024-12-21T17:47:19.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-10T16:52:04.556Z","etag":null,"topics":["ai","ai-agent","fastapi","llm","openai","python","websocket-server","yaml"],"latest_commit_sha":null,"homepage":"https://kiss-ai-stack.github.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiss-ai-stack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-28T15:55:31.000Z","updated_at":"2024-12-21T17:47:22.000Z","dependencies_parsed_at":"2024-12-15T19:38:20.788Z","dependency_job_id":"d8045d4a-ce62-4c0f-a1e6-63abfcdfc5ed","html_url":"https://github.com/kiss-ai-stack/kiss-ai-stack-server","commit_stats":null,"previous_names":["kiss-ai-stack/kiss-ai-stack-server"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiss-ai-stack%2Fkiss-ai-stack-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiss-ai-stack%2Fkiss-ai-stack-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiss-ai-stack%2Fkiss-ai-stack-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiss-ai-stack%2Fkiss-ai-stack-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiss-ai-stack","download_url":"https://codeload.github.com/kiss-ai-stack/kiss-ai-stack-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247308099,"owners_count":20917629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","fastapi","llm","openai","python","websocket-server","yaml"],"created_at":"2024-12-18T14:17:31.917Z","updated_at":"2026-04-14T06:04:45.327Z","avatar_url":"https://github.com/kiss-ai-stack.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv style=\"text-align: left; margin-bottom: 20px;\"\u003e\n  \u003cimg src=\"https://kiss-ai-stack.github.io/kissaistack.svg\" alt=\"KISS AI Stack Banner\" style=\"max-width: auto; height: 250px\"\u003e\n\u003c/div\u003e\n\n# KISS AI Stack - Server\n\nThe KISS AI Stack Server is a server stub designed to support RESTful and WebSocket APIs for handling AI-stack sessions with kiss-ai-stack-core tasks like stack lifecycle management, query execution, and document storage.\n\n## Features\n\n- REST API for authentication, session actions, queries, and document storage.\n- WebSocket API for real-time, event-driven interactions.\n- Built-in persistent and temporary session management.\n- Flexible architecture to handle server events through AI stack's lifecycle events.\n\n---\n\n### Stack's session lifecycle Events\n\n- `on_auth`: Authenticate a session.\n- `on_init`: Initialize a session.\n- `on_close`: Close a session.\n- `on_query`: Execute a query.\n- `on_store`: Store documents.\n\n---\n\n## Getting Started\n\n### Requirements\n\n- Python 3.12\n\n### Installation\n\n1. Install kiss-ai-stack-server package:\n```bash\npip install kiss-ai-stack-server~=0.1.0-alpha20\n```\n\n2. Set environment variables file\n```shell\nACCESS_TOKEN_SECRET_KEY = \"your-secure-random-secret-key\"\nACCESS_TOKEN_ALGORITHM = \"HS256\"\nACCESS_TOKEN_EXPIRE_MINUTES = 30\n\nSESSION_DB_URL=\"sqlite://sessions.db\"\n\nLOG_LEVEL=INFO\n\n```\n3. Add stack bootstrapping yaml configuration\n```yaml\nstack:\n  decision_maker: # Required for tool classification\n    name: decision_maker\n    role: classify tools for given queries\n    kind: prompt  # Choose from 'rag' or 'prompt', decision maker only supports 'prompt'\n    ai_client:\n      provider: openai\n      model: gpt-4\n      api_key: \u003cyour-api-key\u003e\n\n  tools:\n    - name: general_queries\n      role: process other queries if no suitable tool is found.\n      kind: prompt\n      ai_client:\n        provider: openai\n        model: gpt-4\n        api_key: \u003cyour-api-key\u003e\n\n    - name: document_tool\n      role: process documents and provide answers based on them.\n      kind: rag  # Retrieval-Augmented Generation\n      embeddings: text-embedding-ada-002\n      ai_client:\n        provider: openai\n        model: gpt-4\n        api_key: \u003cyour-api-key\u003e\n\n  vector_db:\n    provider: chroma\n    kind: remote # Choose in-memory, storage or remote options.\n    host: 0.0.0.0\n    port: 8000\n    secure: false\n```\n\n4. Start the server:\n```python\nimport asyncio\nimport uvicorn\n\nfrom kiss_ai_stack_server import bootstrap_session_schema, stacks_server, get_stack_server_app\n\n\nasync def start_server():\n    await bootstrap_session_schema()\n    server_app = get_stack_server_app()\n    await stacks_server(\n        config=uvicorn.Config(\n            app=server_app,\n            host='0.0.0.0',\n            port=8080\n        )\n    ).serve()\n\nasyncio.run(start_server())\n```\n---\n\n## REST API Endpoints\n\n### 1. Authentication\n\n**Endpoint:** `/auth`  \n**Method:** `POST`  \n**Request Body:**\n```json\n{\n   \"scope\": \"string\", // `temporary` or `persistent` to create a new session\n   \"client_id\": \"string\", // client_id and client_secret from previous session; for`persistant` scope only\n   \"client_secret\": \"string\"\n}\n```\n**Response:**\n```json\n{\n   \"access_token\": \"string\",\n   \"client_id\": \"string\", // for a `persistent` session keep the client_id and client_secret saved to refresh the access token\n   \"client_secret\": \"secret\"\n}\n```\n\n---\n\n### 2. Session Actions\n\n**Endpoint:** `/sessions?action={init|close}`  \n**Method:** `POST`  \n**Query Parameter:**\n- `action` (required): Action to perform on the session (`init` or `close`).\n- `init` - Will initialize the stack session\n- `close` - Will close the active session, if the scope is `temporary` stored docs will be cleaned\n\n**Request Body:**\n```json\n{\n  \"query\": \"Optional[string]\" // Your greeting message perhaps\n}\n```\n\n---\n\n### 3. Query Execution\n\n**Endpoint:** `/queries`  \n**Method:** `POST`  \n**Request Body:**\n```json\n{\n  \"query\": \"string\"\n}\n```\n**Response:** Generated answer.\n\n---\n\n### 4. Document Storage\n\n**Endpoint:** `/documents`  \n**Method:** `POST`  \n**Request Body:**\n```json\n{\n   \"files\": [\n      {\n         \"name\": \"string\", // file name\n         \"content\": \"string\" // base64 encoded file data\n      },\n      \"metadata\": \"Dictionary\" // Additional metadata\n   ]\n}\n```\n**Response:** Document storage confirmation.\n\n---\n\n## WebSocket API\n\n**Endpoint:** `/ws`\n\n### Workflow\n\n1. Establish a WebSocket connection:\n```bash\nws://localhost:8080/ws\n```\n\n2. Send a message:\n```json\n{\n   \"event\": \"life cycle event\",\n   \"data\": {\n      \"query\": \"example query\"\n   }\n}\n```\n\n3. Receive a response:\n```json\n{\n   \"stack_id\": \"response_value\",\n   \"result\": \"\",\n   \"extras\": \"Dictionary\"\n}\n```\n\n## License\n\nThis project is licensed under the MIT License.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiss-ai-stack%2Fkiss-ai-stack-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiss-ai-stack%2Fkiss-ai-stack-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiss-ai-stack%2Fkiss-ai-stack-server/lists"}