{"id":26061948,"url":"https://github.com/jabberjabberjabber/koboldapi-python","last_synced_at":"2025-06-22T00:38:25.202Z","repository":{"id":271637378,"uuid":"914099649","full_name":"jabberjabberjabber/koboldapi-python","owner":"jabberjabberjabber","description":"KoboldCpp API Helper","archived":false,"fork":false,"pushed_at":"2025-02-23T04:45:52.000Z","size":298,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T05:26:30.774Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jabberjabberjabber.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":"2025-01-09T00:23:57.000Z","updated_at":"2025-02-23T04:45:55.000Z","dependencies_parsed_at":"2025-02-23T05:23:34.147Z","dependency_job_id":"34e4babb-e65e-49b7-9389-f9185efcf798","html_url":"https://github.com/jabberjabberjabber/koboldapi-python","commit_stats":null,"previous_names":["jabberjabberjabber/koboldapi-python"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jabberjabberjabber%2Fkoboldapi-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jabberjabberjabber%2Fkoboldapi-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jabberjabberjabber%2Fkoboldapi-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jabberjabberjabber%2Fkoboldapi-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jabberjabberjabber","download_url":"https://codeload.github.com/jabberjabberjabber/koboldapi-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242573488,"owners_count":20151707,"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":[],"created_at":"2025-03-08T15:48:46.004Z","updated_at":"2025-03-08T15:48:46.631Z","avatar_url":"https://github.com/jabberjabberjabber.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KoboldAPI\n\nA Python library for interacting with KoboldCPP APIs, providing high-level abstractions for text processing, image handling, and generation tasks.\n\n## Features\n\n- **Text Processing**\n  - Intelligent text chunking \n  - Streaming generation capabilities\n  - Token counting and management\n\n- **Image Processing**\n  - Support for multiple image formats (JPEG, PNG, GIF, TIFF, WEBP, HEIF, RAW)\n  - Automatic image resizing and optimization\n  - RAW image processing with thumbnail extraction\n  - Base64 encoding for API transmission\n\n- **Template Management**\n  - Flexible template system for different LLM models\n  - Custom template directory support\n  - Built-in default templates\n  - Jinja2 templating integration\n\n- **API Integration**\n  - Robust error handling\n  - Connection management\n  - Streaming support\n  - Comprehensive API endpoint coverage\n\n## Installation\n\n```bash\npip install koboldapi\n```\n\n## Quick Start\n\n### Text Processing Example\n\n```python\nfrom koboldapi import KoboldAPICore, ChunkingProcessor\n\n# Initialize the API client\ncore = KoboldAPICore(api_url=\"http://localhost:5001\")\n\n# Create a chunking processor\nchunker = ChunkingProcessor(core.api_client, max_chunk_length=2048)\n\n# Process text\nchunks, metadata = chunker.chunk_file(\"document.txt\")\nfor chunk, token_count in chunks:\n    response = core.wrap_and_generate(\n        instruction=\"Summarize this text:\",\n        content=chunk\n    )\n    print(response)\n```\n\n### Image Processing Example\n\n```python\nfrom koboldapi import KoboldAPICore, ImageProcessor\n\n# Initialize processors\ncore = KoboldAPICore(api_url=\"http://localhost:5001\")\nprocessor = ImageProcessor(max_dimension=1024)\n\n# Process image\nencoded_image, img_path = processor.process_image(\"image.jpg\")\nresponse = core.wrap_and_generate(\n    instruction=\"Describe this image:\",\n    images=[encoded_image]\n)\nprint(response)\n```\n\n### Streaming Generation Example\n\n```python\nfrom koboldapi import KoboldAPICore\nimport asyncio\n\nasync def stream_example():\n    core = KoboldAPICore(api_url=\"http://localhost:5001\")\n    \n    # Stream tokens as they're generated\n    async for token in core.api_client.stream_generate(\n        prompt=\"Write a story about a robot:\",\n        max_length=200\n    ):\n        print(token, end='', flush=True)\n    \n    # Or collect all tokens into final result\n    result = await core.api_client.generate_sync(\n        prompt=\"Write a story about a robot:\",\n        max_length=200\n    )\n    print(result)\n\nif __name__ == \"__main__\":\n    asyncio.run(stream_example())\n\t\n```\n\n## Detailed Documentation\n\n### KoboldAPICore\n\nThe main interface for interacting with KoboldCPP APIs.\n\n```python\ncore = KoboldAPICore(\n    api_url=\"http://localhost:5001\",\n    api_password=None,  # Optional API password\n    generation_params={  # Optional generation parameters\n        'temp': 0.7,\n        'top_k': 40,\n        'top_p': 0.9\n    },\n    templates_directory=\"path/to/templates\"  # Optional custom templates\n)\n```\n\n### Text Processing\n\nThe ChunkingProcessor class handles text segmentation and processing:\n\n```python\nchunker = ChunkingProcessor(\n    api_client,  # KoboldAPI instance\n    max_chunk_length=2048,  # Maximum tokens per chunk\n    max_total_chunks=1000  # Maximum number of chunks\n)\n\n# Process a file\nchunks, metadata = chunker.chunk_file(\"document.txt\")\n\n# Process raw text\nchunks = chunker.chunk_text(\"Your text content here\")\n```\n\n### Image Processing\n\nThe ImageProcessor class handles image preparation and optimization:\n\n```python\nprocessor = ImageProcessor(\n    max_dimension=1024,  # Maximum image dimension\n    patch_sizes=[8, 14, 16, 32],  # Patch size options\n    max_file_size=50 * 1024 * 1024  # Maximum file size in bytes\n)\n\n# Process an image\nencoded_image, path = processor.process_image(\"image.jpg\")\n```\n\n### Template Management\n\nCustom templates can be provided in JSON format:\n\n```json\n{\n    \"template_name\": {\n        \"name\": [\"model_name_pattern\"],\n        \"system_start\": \"\\nSystem: \",\n        \"system_end\": \"\\n\",\n        \"user_start\": \"User: \",\n        \"user_end\": \"\\n\",\n        \"assistant_start\": \"Assistant: \"\n    }\n}\n```\n\n## Command Line Tools\n\nThe package includes example scripts for common tasks:\n\n### Text Processing Script\n\n```bash\npython text-example.py input.txt \\\n    --task translate \\\n    --api-url http://localhost:5001 \\\n    --language French \\\n    --max-chunk-size 8192\n```\n\nAvailable tasks:\n- translate: Translate text to specified language\n- summary: Generate text summary\n- correct: Fix grammar and spelling\n- distill: Create concise version\n\n### Image Processing Script\n\n```bash\npython image-example.py image.jpg \\\n    --api-url http://localhost:5001 \\\n    --instruction \"Describe the image in detail.\"\n```\n\n## Error Handling\n\nThe library provides custom exceptions for error handling:\n\n```python\ntry:\n    result = core.wrap_and_generate(instruction=\"Your instruction\")\nexcept KoboldAPIError as e:\n    print(f\"API Error: {e}\")\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the GPLv3 License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjabberjabberjabber%2Fkoboldapi-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjabberjabberjabber%2Fkoboldapi-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjabberjabberjabber%2Fkoboldapi-python/lists"}