{"id":24084663,"url":"https://github.com/level09/neuronic","last_synced_at":"2025-04-30T20:47:12.816Z","repository":{"id":263694520,"uuid":"891218662","full_name":"level09/neuronic","owner":"level09","description":"Create functions that can understand context, extract insights, and solve complex problems - all while maintaining the reliability and predictability of traditional programming. With built-in validation, type checking, and caching.","archived":false,"fork":false,"pushed_at":"2025-01-13T09:07:24.000Z","size":1826,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T23:38:07.731Z","etag":null,"topics":["agentic-ai","gpt","llm","openai","python"],"latest_commit_sha":null,"homepage":"","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/level09.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-20T00:01:31.000Z","updated_at":"2025-01-13T09:07:28.000Z","dependencies_parsed_at":"2024-11-20T00:15:59.219Z","dependency_job_id":"b46e9f10-352e-4cda-8951-f57d6d8deefe","html_url":"https://github.com/level09/neuronic","commit_stats":null,"previous_names":["level09/neuronic"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/level09%2Fneuronic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/level09%2Fneuronic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/level09%2Fneuronic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/level09%2Fneuronic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/level09","download_url":"https://codeload.github.com/level09/neuronic/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251780428,"owners_count":21642772,"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":["agentic-ai","gpt","llm","openai","python"],"created_at":"2025-01-10T00:39:46.232Z","updated_at":"2025-04-30T20:47:12.809Z","avatar_url":"https://github.com/level09.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Neuronic 🧠\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/level09/neuronic/main/.github/images/neuronic.png\" alt=\"Neuronic Logo\" width=\"440\"/\u003e\n\u003c/p\u003e\n\nImagine Python functions that can think, reason, and create - functions that understand natural language, analyze complex data patterns, and generate creative solutions. Welcome to Neuronic - where we transform ordinary Python code into intelligent, AI-powered modules that bring GPT's cognitive capabilities directly into your codebase, complete with enterprise-grade validation, caching, and error handling.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/level09/neuronic/main/.github/images/neuronic-features.png\" alt=\"Neuronic chart\" width=\"440\"/\u003e\n\u003c/p\u003e\n\n## ✨ Magic in Three Lines\n\n```python\nfrom neuronic import Neuronic\n\n@neuronic.function(output_type=\"json\")\ndef convert_to_vegetarian(recipe: str) -\u003e dict:\n    \"\"\"Convert any food recipe to its vegetarian version while maintaining the flavor profile.\"\"\"\n    pass\n\n# That's it! Your function is now AI-powered 🌱\nveggie_recipe = convert_to_vegetarian(\"Classic Beef Burger with bacon\")\n```\n\n## 🌟 Real-Time Streaming\n\nWatch your AI functions generate responses in real-time:\n\n```python\n@neuronic.function(output_type=\"string\", stream=True)\ndef write_story(prompt: str) -\u003e str:\n    \"\"\"Write a creative story based on the given prompt.\"\"\"\n    pass\n\n# See the story being written in real-time\nfor chunk in write_story(\"A curious robot discovers an ancient library\"):\n    print(chunk, end=\"\")\n\n# Or use the transform method directly\nneuronic = Neuronic()\nfor chunk in neuronic.transform(\n    data=\"Explain quantum computing\",\n    instruction=\"Write a clear, step-by-step explanation\",\n    stream=True\n):\n    print(chunk, end=\"\")\n```\n\n## 🌟 What is Neuronic?\n\nNeuronic is your gateway to building intelligent Python applications powered by GPT-4o. Create functions that can understand context, extract insights, and solve complex problems - all while maintaining the reliability and predictability of traditional programming. With built-in validation, type checking, and caching, Neuronic makes AI as dependable as any other Python module.\n\n## 🚀 Features\n\n- **🎯 Smart Function Decorator:** Transform any Python function into an AI-powered one with a simple decorator\n- **🧠 Real-Time Streaming:** Watch AI responses generate in real-time with built-in streaming support\n- **🧠 Intelligent Understanding:** Create functions that truly understand your data, extracting meaning and insights\n- **🗣️ Natural Language Processing:** Process text like a human - analyze sentiment, extract key information, and understand context\n- **✍️ Creative Generation:** Generate human-quality content, from documentation to test data, tailored to your specifications\n- **🔍 Pattern Recognition:** Uncover hidden patterns and relationships in your data through GPT-powered analysis\n- **📦 Multiple Output Types:** Get results in any format you need - strings, numbers, JSON, lists, booleans, or Python structures\n- **🏢 Enterprise Ready:** Built-in validation, type checking, and caching ensure production-ready outputs\n- **⚡ Performance Optimized:** Automatic chunking for large inputs and smart caching for repeated operations\n\n## 🛠️ Quick Start\n\n### Installation\n\n```bash\npip install neuronic\n```\n\n### Configuration\n\n```python\n# Option 1: Use environment variables (.env file)\nOPENAI_API_KEY=your-openai-api-key-here\n\n# Option 2: Pass API key directly\nneuronic = Neuronic(api_key=\"your-api-key-here\")\n```\n\n## 🎮 Cool Examples\n\n### 🪄 Smart Function Decorator\nTransform any Python function into an AI-powered one:\n\n```python\n@neuronic.function(output_type=\"string\")\ndef generate_mini_story(character: str, setting: str, mood: str) -\u003e str:\n    \"\"\"Create a three-sentence story based on the given character, setting, and mood.\"\"\"\n    pass\n\nstory = generate_mini_story(\n    character=\"a curious robot\",\n    setting=\"ancient library\",\n    mood=\"mysterious\"\n)\n```\n\n### 🧹 Smart Data Cleaning\nClean and standardize messy data:\n\n```python\n@neuronic.function(output_type=\"json\")\ndef clean_user_data(users: List[Dict]) -\u003e List[Dict]:\n    \"\"\"\n    Clean and standardize user data:\n    - Properly capitalize names\n    - Validate and fix email addresses\n    - Convert age to numbers\n    \"\"\"\n    pass\n\nclean_data = clean_user_data(messy_data)\n```\n\n### 🎨 Creative Generation\nGenerate emoji-based character profiles:\n\n```python\nemoji_personas = neuronic.generate(\n    spec=\"\"\"Create unique emoji-based character profiles with:\n    - Emoji combination for appearance\n    - Personality trait\n    - Favorite hobby\n    - Life motto\"\"\",\n    n=3\n)\n```\n\n### 📊 Smart Analysis\nAnalyze text with context and reasoning:\n\n```python\nanalysis = neuronic.analyze(\n    data=movie_review,\n    question=\"What aspects of the movie did the reviewer focus on?\"\n)\nprint(f\"Answer: {analysis['answer']}\")\nprint(f\"Confidence: {analysis['confidence']}\")\nprint(f\"Reasoning: {analysis['reasoning']}\")\n```\n\n## 🎯 Perfect For\n\n- **🔄 Data Processing:** Format conversion, cleaning, normalization\n- **📝 Content Creation:** Documentation, test data, sample content\n- **📊 Analysis:** Pattern recognition, sentiment analysis, trend detection\n- **🛠️ Development:** Code transformation, API handling, validation\n\n## 🧰 API Reference\n\n### Core Methods\n\n```python\n# Transform data with streaming\nresult = neuronic.transform(\n    data=input_data,               # What to transform\n    instruction=\"your instruction\", # How to transform it\n    output_type=\"string\",          # What format you want\n    stream=True,                   # Enable streaming\n    example=None,                  # Optional example\n    context=None                   # Optional context\n)\nfor chunk in result:\n    print(chunk, end=\"\")\n\n# Analyze data\ninsights = neuronic.analyze(\n    data=your_data,      # What to analyze\n    question=\"your question\"  # What to find out\n)\n\n# Generate data\nnew_data = neuronic.generate(\n    spec=\"what to generate\",  # What you want\n    n=1                      # How many items\n)\n```\n\n### Streaming Functions\n\n```python\n# Create streaming functions for long-form content\n@neuronic.function(output_type=\"string\", stream=True)\ndef write_blog_post(topic: str, style: str) -\u003e str:\n    \"\"\"Write a detailed blog post in the specified style.\"\"\"\n    pass\n\n# Watch the blog post being written in real-time\nfor chunk in write_blog_post(\n    topic=\"The Future of AI\",\n    style=\"conversational\"\n):\n    print(chunk, end=\"\")\n\n# Stream JSON responses\n@neuronic.function(output_type=\"json\", stream=True)\ndef analyze_text_stream(text: str) -\u003e dict:\n    \"\"\"Analyze text and return structured data with streaming.\"\"\"\n    pass\n\n# Note: JSON streaming ensures valid JSON output\nfor chunk in analyze_text_stream(\"Your text here\"):\n    print(chunk, end=\"\")\n```\n\n## 🎓 Best Practices\n\n1. **🔐 Security First**\n   - Keep API keys in environment variables\n   - Never commit sensitive data\n\n2. **⚡ Performance Tips**\n   - Use caching for repeated operations\n   - Enable streaming for long-running operations\n   - Batch similar requests when possible\n   - Be mindful of token limits when streaming\n\n3. **🛡️ Error Handling**\n   - Always handle exceptions gracefully\n   - Validate outputs match expected formats\n   - Handle streaming interruptions properly\n\n4. **🔄 Streaming Guidelines**\n   - Use streaming for long-form content generation\n   - Handle partial outputs appropriately\n   - Consider disabling streaming for small, quick operations\n   - Remember streaming bypasses caching\n\n## 📜 License\n\nMIT License - feel free to use in your own projects!\n\n## 🤝 Contributing\n\nGot ideas? Found a bug? Contributions are welcome! Feel free to:\n- Open an issue\n- Submit a pull request\n- Share your cool use cases\n\n## 🌟 Star Us!\nIf you find Neuronic useful, give us a star! It helps others discover the project.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevel09%2Fneuronic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flevel09%2Fneuronic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevel09%2Fneuronic/lists"}