{"id":28951308,"url":"https://github.com/sppdd/forms-agent","last_synced_at":"2025-06-23T14:38:29.682Z","repository":{"id":300754874,"uuid":"1007036471","full_name":"Sppdd/forms-agent","owner":"Sppdd","description":"google forms automation agent kit. ","archived":false,"fork":false,"pushed_at":"2025-06-23T11:50:57.000Z","size":4136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-23T12:39:38.323Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sppdd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-06-23T11:15:18.000Z","updated_at":"2025-06-23T11:51:00.000Z","dependencies_parsed_at":"2025-06-23T12:51:10.661Z","dependency_job_id":null,"html_url":"https://github.com/Sppdd/forms-agent","commit_stats":null,"previous_names":["sppdd/forms-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Sppdd/forms-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sppdd%2Fforms-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sppdd%2Fforms-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sppdd%2Fforms-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sppdd%2Fforms-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sppdd","download_url":"https://codeload.github.com/Sppdd/forms-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sppdd%2Fforms-agent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261496009,"owners_count":23167414,"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-06-23T14:38:29.004Z","updated_at":"2025-06-23T14:38:29.661Z","avatar_url":"https://github.com/Sppdd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Google Forms Agent Pipeline\n\nA comprehensive Google Forms management system built with Google ADK (Agent Development Kit) that can create, edit, validate, and manage Google Forms from documents or direct input.\n\n## 🚀 Features\n\n- **Document Processing**: Parse PDF, DOCX, TXT, and MD files to extract form questions\n- **Form Creation**: Create Google Forms with intelligent auto-completion\n- **Form Editing**: Edit existing forms with batch operations\n- **Form Validation**: Validate form structures and auto-fix issues\n- **Service Account Integration**: Secure Google Forms API authentication\n- **Pipeline Architecture**: Modular subagent system for specialized tasks\n- **ADK Callback Optimizations**: Performance, caching, and monitoring capabilities\n\n## 📁 Project Structure\n\n```\nforms_agent/\n├── forms_agent/                    # Main agent package\n│   ├── agent.py                   # Root agent with subagent tools\n│   ├── service_account.json       # Google service account credentials\n│   └── subagents/                 # Specialized subagents\n│       ├── document_parser/       # Document parsing and extraction\n│       ├── form_creator/          # Form creation and configuration\n│       ├── form_editor/           # Form editing and management\n│       └── form_validator/        # Form validation and quality control\n├── google_forms_api.py            # Standalone Google Forms API client\n├── google_forms_tool.py           # Google ADK tool wrappers\n├── google_forms_agent.py          # Google ADK agent implementation\n├── requirements.txt               # Python dependencies\n└── README.md                     # This file\n```\n\n## 🛠️ Installation\n\n1. **Clone the repository**:\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd forms_agent\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Set up Google Service Account**:\n   - Create a Google Cloud Project\n   - Enable Google Forms API\n   - Create a service account\n   - Download the JSON credentials file as `service_account.json`\n   - Place it in the `forms_agent/` directory\n\n4. **Configure environment**:\n   ```bash\n   # Set your Google API key (optional, for additional features)\n   export GOOGLE_API_KEY=\"your-api-key-here\"\n   ```\n\n## 🎯 Quick Start\n\n### Using the Standalone API\n\n```python\nfrom google_forms_api import GoogleFormsAPI\n\n# Initialize the API\napi = GoogleFormsAPI()\n\n# Create a form\nresult = api.create_form(\n    title=\"My Test Form\",\n    description=\"A test form created with the API\"\n)\n\nif result[\"result\"] == \"success\":\n    form_id = result[\"form_id\"]\n    print(f\"Form created: {result['form_url']}\")\n```\n\n### Using the ADK Agent\n\n```python\nfrom forms_agent.agent import root_agent\n\n# The agent is ready to use in your ADK workflows\n# It provides comprehensive form management capabilities\n```\n\n### Testing the Pipeline\n\n```bash\n# Test the service account\npython simple_test.py\n\n# Test the subagents\npython test_subagents.py\n\n# Test the standalone forms API\npython test_standalone_forms.py\n```\n\n## 🔧 Usage Examples\n\n### 1. Create a Form from Document\n\n```python\n# The agent can parse documents and create forms automatically\n# Upload a document and the agent will:\n# 1. Parse the document content\n# 2. Extract questions and structure\n# 3. Create a Google Form\n# 4. Add questions and configure settings\n```\n\n### 2. Edit Existing Forms\n\n```python\n# The agent can edit existing forms:\n# - Update titles and descriptions\n# - Add, modify, or delete questions\n# - Configure form settings\n# - Retrieve form responses\n```\n\n### 3. Validate Form Structure\n\n```python\n# The agent can validate forms:\n# - Check question types and compatibility\n# - Suggest improvements\n# - Auto-fix common issues\n# - Ensure Google Forms API compliance\n```\n\n## 🏗️ Architecture\n\n### Subagent System\n\nThe project uses a modular subagent architecture:\n\n- **Document Parser Agent**: Handles document processing and content extraction\n- **Form Creator Agent**: Manages form creation and initial configuration\n- **Form Editor Agent**: Handles form editing and updates\n- **Form Validator Agent**: Validates form structure and quality\n\n### Service Account Integration\n\nThe system uses Google service account authentication for secure API access:\n\n- Automatic authentication handling\n- Secure credential management\n- API rate limiting and error handling\n- Session state management\n\n### ADK Callback Optimizations\n\nThe system includes comprehensive callback optimizations:\n\n- **Caching**: Automatic caching of LLM responses and tool results\n- **Validation**: Enhanced input validation and error recovery\n- **Monitoring**: Comprehensive performance monitoring and logging\n- **Safety**: Content filtering and guardrails\n- **Performance**: Optimized API calls and batch processing\n\n## 📊 Performance Features\n\n- **Caching**: 50-80% faster response times through intelligent caching\n- **Rate Limiting**: Prevents API overload and ensures reliable operation\n- **Error Recovery**: Automatic retry logic and graceful error handling\n- **Monitoring**: Real-time performance tracking and analytics\n- **Validation**: Input validation and data quality checks\n\n## 🔒 Security\n\n- **Service Account Authentication**: Secure Google API access\n- **Content Filtering**: Protection against sensitive data processing\n- **Input Validation**: Comprehensive input sanitization\n- **Error Handling**: Secure error messages without data leakage\n- **Rate Limiting**: Protection against API abuse\n\n## 🧪 Testing\n\nThe project includes comprehensive test suites:\n\n- **Unit Tests**: Individual component testing\n- **Integration Tests**: End-to-end workflow testing\n- **Performance Tests**: Caching and optimization validation\n- **Security Tests**: Authentication and validation testing\n\nRun tests with:\n```bash\npython test_subagents.py\npython test_standalone_forms.py\npython simple_test.py\n```\n\n## 📈 Monitoring and Analytics\n\nThe system provides comprehensive monitoring:\n\n- **Performance Metrics**: Response times and throughput\n- **Cache Analytics**: Hit rates and optimization effectiveness\n- **Error Tracking**: Error patterns and resolution\n- **API Usage**: Call frequency and optimization opportunities\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🆘 Support\n\nFor support and questions:\n\n1. Check the documentation in the `README_standalone_forms.md` file\n2. Review the optimization guide in `ADK_CALLBACK_OPTIMIZATION_GUIDE.md`\n3. Test the examples in the test files\n4. Check the Google ADK documentation for callback usage\n\n## 🚀 Roadmap\n\n- [ ] Enhanced caching strategies\n- [ ] Advanced form templates\n- [ ] Batch form operations\n- [ ] Real-time collaboration features\n- [ ] Advanced analytics dashboard\n- [ ] Multi-language support\n- [ ] Mobile optimization\n- [ ] Advanced security features\n\n---\n\n**Built with Google ADK and Google Forms API** ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsppdd%2Fforms-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsppdd%2Fforms-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsppdd%2Fforms-agent/lists"}