{"id":43920254,"url":"https://github.com/seamapi/seam-agent","last_synced_at":"2026-02-06T22:09:26.920Z","repository":{"id":326159343,"uuid":"1104256564","full_name":"seamapi/seam-agent","owner":"seamapi","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-26T01:19:32.000Z","size":473,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-26T21:08:57.125Z","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/seamapi.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-26T01:05:10.000Z","updated_at":"2025-11-26T01:19:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/seamapi/seam-agent","commit_stats":null,"previous_names":["seamapi/seam-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/seamapi/seam-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seamapi%2Fseam-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seamapi%2Fseam-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seamapi%2Fseam-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seamapi%2Fseam-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seamapi","download_url":"https://codeload.github.com/seamapi/seam-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seamapi%2Fseam-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29178699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T20:14:21.878Z","status":"ssl_error","status_checked_at":"2026-02-06T20:14:21.443Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-02-06T22:09:25.979Z","updated_at":"2026-02-06T22:09:26.915Z","avatar_url":"https://github.com/seamapi.png","language":"Python","readme":"# 🔐 Seam Agent\n\n**AI-Powered Customer Support Investigation Assistant**\n\nAn intelligent assistant that helps support agents debug customer issues by automatically gathering, analyzing, and presenting relevant data from multiple sources. Built for [Seam](https://www.seam.co/), the API for smart locks and access control.\n\n---\n\n## 🎯 The Problem\n\nCustomer support teams spend significant time (30%+ of cases) manually navigating through admin dashboards, job logs, and various data sources to debug customer issues:\n\n- **Multiple clicks** through complex admin interfaces\n- **Manual log analysis** with poor search capabilities\n- **Time-consuming triangulation** of timestamps across jobs, action attempts, and errors\n- **Inability to link** to specific logs, causing duplicated effort\n- **Manual timeline reconstruction** for issues reported days/weeks after occurrence\n\n## 💡 The Solution\n\nSeam Agent is an AI orchestrator that instantly gathers, analyzes, and presents debugging information from multiple data sources—reducing manual effort and improving response times from hours to minutes.\n\n```\nSupport Agent: \"What's wrong with device 267ed8d4-3933-4e71-921a-53ce3736879a?\"\n                                    ↓\n                            ┌───────────────┐\n                            │  Seam Agent   │\n                            │  Orchestrator │\n                            └───────────────┘\n                                    │\n            ┌───────────────────────┼───────────────────────┐\n            ↓                       ↓                       ↓\n    ┌───────────────┐      ┌───────────────┐      ┌───────────────┐\n    │   PostgreSQL  │      │   Quickwit    │      │   Seam API    │\n    │   Database    │      │     Logs      │      │   Endpoints   │\n    └───────────────┘      └───────────────┘      └───────────────┘\n            │                       │                       │\n            └───────────────────────┼───────────────────────┘\n                                    ↓\n                        ┌───────────────────────┐\n                        │  Formatted Analysis   │\n                        │  + Admin Links        │\n                        │  + Next Steps         │\n                        └───────────────────────┘\n```\n\n---\n\n## ✨ Features\n\n### 🔍 Intelligent Query Parsing\n- Extracts device IDs, workspace IDs, access codes, and time references from natural language\n- Classifies query types: `device_behavior`, `troubleshooting`, `api_help`, `account_issue`\n- Uses GPT-4o-mini for cost-efficient structured extraction\n\n### 🛠️ Dynamic Tool Selection\n- Automatically selects relevant investigation tools based on query type\n- Supports multi-round tool calling with configurable limits\n- Includes follow-up tool recommendations based on initial findings\n\n### 📊 Rich Data Gathering\n| Tool | Description |\n|------|-------------|\n| `get_device_info` | Device properties, status, capabilities, and errors |\n| `get_access_codes` | Access codes with managed/unmanaged status |\n| `get_action_attempts` | Operation history with success/failure patterns |\n| `get_device_events` | Event timeline including connectivity changes |\n| `get_audit_logs` | Access code INSERT/DELETE audit trail |\n| `get_admin_links` | Generated admin panel URLs for deeper investigation |\n\n### 📝 Formatted Output\nGenerates structured internal notes with:\n- 🔍 Device Analysis summary\n- ⚠️ Issue identification\n- 📋 Timeline reconstruction\n- 🔧 Root cause analysis\n- 🎯 Actionable next steps\n- 📎 Admin links for follow-up\n\n---\n\n## 🏗️ Architecture\n\n```\nsrc/seam_agent/\n├── assistant/                  # Core AI orchestration\n│   ├── simple_investigator.py  # Main investigation orchestrator\n│   ├── tool_orchestrator.py    # Tool execution and result summarization\n│   ├── tool_registry.py        # Maps issue types to required tools\n│   ├── dynamic_tool_selector.py # Intelligent tool selection\n│   ├── query_parser.py         # LLM-based query parsing\n│   ├── prompt_manager.py       # Investigation prompt templates\n│   ├── investigation_config.py # Limits and resource management\n│   └── investigation_logger.py # Structured logging\n├── connectors/                 # Data source integrations\n│   ├── db.py                   # PostgreSQL async client\n│   ├── quickwit.py             # Quickwit log search client\n│   ├── seam_api.py             # Seam REST API client\n│   └── admin_links.py          # Admin URL generator\n└── integrations/               # External service integrations\n    ├── slack.py                # Slack integration (planned)\n    └── unthread.py             # Unthread integration (planned)\n```\n\n### Key Components\n\n**SimpleInvestigator** — The main entry point that coordinates the entire investigation flow:\n1. Parses the support query to extract structured data\n2. Calls Claude with available tools based on query type\n3. Handles multi-round tool calling with configurable limits\n4. Formats findings into a structured support note\n\n**ToolOrchestrator** — Manages tool execution and result processing:\n- Executes database queries and API calls\n- Summarizes results to preserve critical debugging info\n- Caches results to prevent hallucinations in follow-up tools\n\n**DynamicToolSelector** — Intelligently chooses investigation paths:\n- Selects initial tools based on parsed query\n- Recommends follow-up tools based on findings\n- Respects configurable tool calling limits\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Python 3.10+\n- PostgreSQL database access (Seam production/staging)\n- API keys for Anthropic, OpenAI\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/seamapi/seam-agent.git\ncd seam-agent\n\n# Install with uv (recommended)\nuv sync\n```\n\n### Configuration\n\nCreate a `.env` file or export environment variables:\n\n```bash\n# Required\nANTHROPIC_API_KEY=sk-ant-...      # For Claude (investigation)\nOPENAI_API_KEY=sk-...             # For GPT-4o-mini (query parsing)\nDATABASE_URL=postgresql://...      # Seam PostgreSQL connection\n\n# Optional\nQUICKWIT_URL=http://localhost:7280  # Quickwit log search\nQUICKWIT_API_KEY=...               # Quickwit authentication\nSEAM_API_KEY=seam_...              # Seam API access\n```\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom seam_agent.assistant.simple_investigator import SimpleInvestigator\n\nasync def main():\n    investigator = SimpleInvestigator(debug_mode=True)\n\n    result = await investigator.investigate(\"\"\"\n        Hello team!\n        We are checking an Igloohome device that does not seem to be\n        connected to a bridge, so it only supports offline functionality.\n        However, the device response says that it can program online\n        access codes. Is that correct?\n\n        Device ID: 267ed8d4-3933-4e71-921a-53ce3736879a\n    \"\"\")\n\n    # Print formatted investigation\n    print(result[\"investigation\"])\n\n    # Export to markdown file\n    filename = investigator.export_investigation_to_md(result)\n    print(f\"Report saved to: {filename}\")\n\nasyncio.run(main())\n```\n\n---\n\n## 📖 Example Output\n\n```markdown\n🔍 **Device Analysis**: Igloohome Device (267ed8d4-3933-4e71-921a-53ce3736879a)\n\n⚠️ **Issue Identified**: Device shows conflicting capability flags - indicates\nonline access code support while offline and not bridge-connected\n\n📊 **Status**: Under investigation - potential platform capability reporting issue\n\n📋 **Timeline**:\n• Device last disconnected: 2025-07-27T13:06:05.495Z\n• Last 10 connection reports all show \"DEVICE_OFFLINE\"\n• Device remains offline with no bridge connectivity\n\n🔧 **Root Cause**: System showing `can_program_online_access_codes: true` based\non device model capabilities, but device is offline and not connected to bridge.\nCapability flags are not dynamically updated based on actual connectivity status.\n\n🎯 **Next Steps**:\n1. **Customer Communication**: Confirm online access codes require bridge\n   connectivity - currently only offline codes are functional\n2. **Technical Review**: Verify connectivity attempts through admin panel\n3. **Platform Escalation**: Consider engineering review of capability flag logic\n\n📎 **Admin Links for Further Investigation:**\n- [Device Details](https://connect.getseam.com/admin/view_device?device_id=...)\n- [Device Action History](https://connect.getseam.com/admin/view_device_action_attempts?device_id=...)\n```\n\n---\n\n## ⚙️ Configuration Options\n\n### Investigation Limits\n\n```python\nfrom seam_agent.assistant.investigation_config import InvestigationConfig\n\n# Production config (conservative)\nconfig = InvestigationConfig.create_production_config()\n# MAX_TOOL_ROUNDS: 2\n# MAX_TOOLS_PER_ROUND: 3\n# MAX_TOTAL_TOOLS: 6\n\n# Debug config (permissive)\nconfig = InvestigationConfig.create_debug_config()\n# MAX_TOOL_ROUNDS: 5\n# MAX_TOOLS_PER_ROUND: 8\n# MAX_TOTAL_TOOLS: 20\n\n# Custom config\nconfig = InvestigationConfig(\n    MAX_TOOL_ROUNDS=3,\n    MAX_TOOLS_PER_ROUND=5,\n    MAX_TOTAL_TOOLS=10,\n    TOTAL_INVESTIGATION_TIMEOUT=120\n)\n\ninvestigator = SimpleInvestigator(config=config)\n```\n\n### Logging Modes\n\n```python\n# Human-readable logs\ninvestigator = SimpleInvestigator(debug_mode=True, log_format=\"human\")\n\n# JSON logs (for parsing)\ninvestigator = SimpleInvestigator(debug_mode=True, log_format=\"json\")\n```\n\n---\n\n## 🎮 Running Examples\n\n### Demo Investigation (Mocked)\n\nRun a full investigation demo with mocked external services—no API keys required:\n\n```bash\nuv run python demo_investigation.py\n```\n\nThis demonstrates:\n- Dynamic tool selection based on issue type\n- Multi-round tool calling with limit enforcement\n- Structured analysis and recommendations\n\n### Live Investigation (Requires Credentials)\n\nRun a real investigation against production databases:\n\n```bash\n# Single investigation (loads .env automatically)\nuv run --env-file .env python -m seam_agent.assistant.simple_investigator\n\n# Or run the test suite with live data\nuv run --env-file .env pytest tests/test_investigator_live.py -v -s\n```\n\n### Query Parser Demo\n\nTest the LLM-based query parser in isolation:\n\n```bash\nuv run --env-file .env python -m seam_agent.assistant.query_parser\n```\n\n---\n\n## 🧪 Development\n\n### Running Tests\n\n```bash\n# Run unit tests (no credentials needed)\nuv run pytest tests/test_dynamic_tool_selector.py tests/test_investigation_config.py -v\n\n# Run all tests with env\nuv run --env-file .env pytest\n\n# Run with verbose output\nuv run --env-file .env pytest -v\n\n# Run live integration tests (requires credentials)\nuv run --env-file .env pytest tests/test_investigator_live.py -v -s\n```\n\n### Code Quality\n\n```bash\n# Format code\nuv run ruff format src tests\n\n# Lint\nuv run ruff check src tests\n\n# Fix lint issues automatically\nuv run ruff check src tests --fix\n\n# Type checking\nuv run pyright src tests\n```\n\n---\n\n## 🗺️ Roadmap\n\n- [x] Core investigation orchestration\n- [x] PostgreSQL database integration\n- [x] Dynamic tool selection\n- [x] Configurable investigation limits\n- [x] Admin link generation\n- [ ] Quickwit log search integration\n- [ ] Slack integration for triggering investigations\n- [ ] Unthread integration for posting internal notes\n- [ ] Timeline reconstruction with event correlation\n- [ ] Provider-specific issue detection\n- [ ] Proactive alerting for error patterns\n\n---\n\n## 📚 Related Documentation\n\n- [Product Requirements Document](docs/customer-support-agent-prd.md)\n- [Customer Conversation Analysis](docs/conversation-analysis.md)\n- [Task Tracking](task.md)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built with 🤖 by the Seam team\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseamapi%2Fseam-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseamapi%2Fseam-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseamapi%2Fseam-agent/lists"}