{"id":23536201,"url":"https://github.com/bgunyel/ragnar","last_synced_at":"2026-04-12T01:35:58.272Z","repository":{"id":269303341,"uuid":"906511846","full_name":"bgunyel/ragnar","owner":"bgunyel","description":"Retrieval AuGmented kNowledge AdviseR","archived":false,"fork":false,"pushed_at":"2025-08-08T09:45:06.000Z","size":860,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T10:05:01.469Z","etag":null,"topics":["agentic-ai","ai","business-intelligence","groq","langchain","langgraph","llm","rag","retrieval-augmented-generation","streamlit","tavily"],"latest_commit_sha":null,"homepage":"","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/bgunyel.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":"2024-12-21T05:29:58.000Z","updated_at":"2025-08-08T09:45:09.000Z","dependencies_parsed_at":"2024-12-22T15:38:13.812Z","dependency_job_id":"321221fa-8a22-4d37-9ec0-85bf69f14ce3","html_url":"https://github.com/bgunyel/ragnar","commit_stats":null,"previous_names":["bgunyel/ragnar"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bgunyel/ragnar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgunyel%2Fragnar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgunyel%2Fragnar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgunyel%2Fragnar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgunyel%2Fragnar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bgunyel","download_url":"https://codeload.github.com/bgunyel/ragnar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgunyel%2Fragnar/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269740700,"owners_count":24467830,"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","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agentic-ai","ai","business-intelligence","groq","langchain","langgraph","llm","rag","retrieval-augmented-generation","streamlit","tavily"],"created_at":"2024-12-26T02:17:27.741Z","updated_at":"2025-10-23T22:17:50.679Z","avatar_url":"https://github.com/bgunyel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RAGNAR\n\n## Retrieval AuGmented kNowledge AdviseR\n\nA powerful business intelligence agent that combines web research capabilities with database storage for comprehensive company and person analysis.\n\n## 🚀 Features\n\n- **Intelligent Business Research**: Automated research on companies and individuals using web search and AI analysis\n- **Database-First Architecture**: Smart caching system that checks local database before performing web searches\n- **Multi-LLM Support**: Compatible with multiple language model providers (Groq, OpenAI, Anthropic, etc.)\n- **Interactive CLI**: User-friendly command-line interface with rich formatting\n- **Comprehensive Tool Suite**: Six specialized tools for research and data management\n- **Token Usage Tracking**: Built-in monitoring of LLM token consumption\n- **LangSmith Integration**: Advanced tracing and debugging capabilities\n\n## 📋 Table of Contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Architecture](#architecture)\n- [Tools](#tools)\n- [Database Schema](#database-schema)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n## 🛠 Installation\n\n### Prerequisites\n\n- Python 3.13 or higher\n- Supabase account for database storage\n- API keys for LLM providers and web search\n\n### Install from Source\n\n```bash\ngit clone https://github.com/bgunyel/ragnar.git\ncd ragnar\npip install -e .\n```\n\n### Dependencies\n\nRAGNAR depends on several custom packages:\n- `ai-common`: Common utilities for AI applications\n- `business-researcher`: Web research and data extraction engine\n- `supabase`: Database connectivity and operations\n\n## ⚙️ Configuration\n\nCreate a `.env` file in the project root with the following variables:\n\n```env\n# LLM Providers\nGROQ_API_KEY=your_groq_api_key\nOPENAI_API_KEY=your_openai_api_key\nANTHROPIC_API_KEY=your_anthropic_api_key\n\n# Web Search\nTAVILY_API_KEY=your_tavily_api_key\n\n# Database\nSUPABASE_URL=your_supabase_url\nSUPABASE_SECRET_KEY=your_supabase_secret_key\n\n# Monitoring\nLANGSMITH_API_KEY=your_langsmith_api_key\nLANGSMITH_TRACING=true\n```\n\n## 🎯 Usage\n\n### Interactive Mode\n\nStart the interactive CLI:\n\n```bash\npython src/main_dev.py\n```\n\nExample conversation:\n```\nYou: Research Apple Inc\nRagnar: [Provides comprehensive company information from database or web research]\n\nYou: Find information about Tim Cook at Apple\nRagnar: [Returns detailed person profile with professional background]\n\nYou: Insert the Apple research into database\nRagnar: [Stores company information in database for future queries]\n```\n\n### Programmatic Usage\n\n```python\nfrom ragnar import BusinessIntelligenceAgent\nfrom ai_common import LlmServers\n\n# Configure LLM settings\nllm_config = {\n    'language_model': {\n        'model': 'llama-3.3-70b-versatile',\n        'model_provider': LlmServers.GROQ.value,\n        'api_key': 'your_api_key',\n        'model_args': {\n            'temperature': 0,\n            'max_tokens': 32768\n        }\n    },\n    'reasoning_model': {\n        'model': 'llama-3.3-70b-versatile',\n        'model_provider': LlmServers.GROQ.value,\n        'api_key': 'your_api_key',\n        'model_args': {\n            'temperature': 0,\n            'max_tokens': 32768\n        }\n    }\n}\n\n# Initialize agent\nagent = BusinessIntelligenceAgent(\n    llm_config=llm_config,\n    web_search_api_key='your_tavily_key',\n    database_url='your_supabase_url',\n    database_key='your_supabase_key'\n)\n\n# Run research query\nresult = agent.run(\"Research Microsoft Corporation\")\nprint(result['content'])\nprint(f\"Tokens used: {result['token_usage']}\")\n```\n\n## 🏗 Architecture\n\nRAGNAR uses a modern agent architecture built on LangGraph with a clean inheritance hierarchy:\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   User Input    │───▶│   LLM Call Node  │───▶│  Tools Call     │\n└─────────────────┘    └──────────────────┘    │     Node        │\n                                ▲               └─────────────────┘\n                                │                        │\n                                │                        ▼\n                       ┌─────────────────┐    ┌─────────────────┐\n                       │   Final Output  │◀───│ Conditional     │\n                       └─────────────────┘    │ Decision        │\n                                              └─────────────────┘\n```\n\n### Class Hierarchy\n\n```\nBaseAgent (Abstract)\n├── Tool dispatcher pattern\n├── LangGraph workflow management\n├── State and memory handling\n└── Token usage tracking\n\nBusinessIntelligenceAgent (Concrete)\n├── Inherits from BaseAgent\n├── Business research capabilities\n├── Database operations\n└── 11 specialized tool handlers\n```\n\n### Key Components\n\n- **BaseAgent**: Abstract base class with dispatcher pattern for tool handling\n- **StateGraph**: Manages conversation flow and state transitions\n- **Memory Saver**: Persists conversation history across sessions\n- **Business Researcher**: Handles web search and content analysis\n- **Supabase Client**: Manages database operations and caching\n- **Tool Handlers**: Clean, testable methods for each tool operation\n- **Token Tracker**: Monitors LLM usage and costs\n\n## 🔧 Tools\n\nRAGNAR provides six specialized tools:\n\n### Research Tools\n1. **ResearchPerson**: Research individuals with company context\n2. **ResearchCompany**: Comprehensive company analysis\n\n### Database Tools\n1. **FetchCompanyFromDataBase**: Retrieve company records\n2. **FetchPersonFromDataBase**: Retrieve person records\n3. **InsertCompanyToDataBase**: Store company information\n4. **InsertPersonToDataBase**: Store person information\n\n### Smart Workflow\n\nThe agent implements a database-first approach:\n1. Check local database for existing information\n2. If found, return cached data instantly\n3. If not found, perform web research\n4. Optionally store results for future use\n\n## 🗄 Database Schema\n\n### Companies Table\n```sql\nCREATE TABLE companies (\n    id SERIAL PRIMARY KEY,\n    name VARCHAR NOT NULL,\n    description TEXT,\n    industry VARCHAR,\n    founded_year INTEGER,\n    headquarters VARCHAR,\n    website VARCHAR,\n    employee_count INTEGER,\n    revenue DECIMAL,\n    created_by_id INTEGER,\n    updated_by_id INTEGER,\n    created_at TIMESTAMP DEFAULT NOW(),\n    updated_at TIMESTAMP DEFAULT NOW()\n);\n```\n\n### Persons Table\n```sql\nCREATE TABLE persons (\n    id SERIAL PRIMARY KEY,\n    name VARCHAR NOT NULL,\n    title VARCHAR,\n    current_company_id INTEGER REFERENCES companies(id),\n    bio TEXT,\n    education TEXT,\n    experience TEXT,\n    skills TEXT[],\n    created_by_id INTEGER,\n    updated_by_id INTEGER,\n    created_at TIMESTAMP DEFAULT NOW(),\n    updated_at TIMESTAMP DEFAULT NOW()\n);\n```\n\n## 🔬 Development\n\n### Project Structure\n\n```\nragnar/\n├── src/\n│   ├── config.py                 # Configuration management\n│   ├── main_dev.py              # Development CLI interface\n│   └── ragnar/\n│       ├── __init__.py\n│       ├── agents/\n│       │   ├── __init__.py\n│       │   ├── base_agent.py               # Abstract base agent with dispatcher pattern\n│       │   ├── business_intelligence_agent.py\n│       │   ├── configuration.py\n│       │   ├── enums.py\n│       │   ├── state.py\n│       │   ├── tools.py\n│       │   └── utils.py\n│       └── apps/\n│           └── __init__.py\n├── pyproject.toml               # Project configuration\n├── uv.lock                      # Dependency lock file\n└── README.md\n```\n\n### Key Design Patterns\n\n- **Agent Pattern**: Autonomous decision-making with tool selection\n- **Dispatcher Pattern**: Clean tool handler mapping instead of large match-case blocks\n- **Inheritance**: BaseAgent provides common functionality, child classes specialize\n- **State Management**: Immutable state transitions via LangGraph\n- **Dependency Injection**: Configurable LLM and database providers\n- **Separation of Concerns**: Distinct modules for research, storage, and UI\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest tests/\n\n# Run with coverage\npytest --cov=ragnar tests/\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/\nisort src/\n\n# Lint code\nflake8 src/\nmypy src/\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Follow PEP 8 style guidelines\n- Add type hints to all functions\n- Include docstrings for public methods\n- Write unit tests for new features\n- Update documentation as needed\n\n## 📊 Monitoring and Observability\n\nRAGNAR includes comprehensive monitoring:\n\n- **LangSmith Integration**: Request tracing and debugging\n- **Token Usage Tracking**: Cost monitoring across models\n- **Error Handling**: Graceful degradation and recovery\n- **Performance Metrics**: Response time and throughput tracking\n\n## 🔒 Security Considerations\n\n- API keys stored in environment variables\n- Database credentials encrypted at rest\n- Input validation on all user inputs\n- Rate limiting on external API calls\n- Audit logging for database operations\n\n## 📈 Performance Optimization\n\n- **Database-first caching** reduces redundant web searches\n- **Parallel processing** for multiple tool calls\n- **Connection pooling** for database efficiency\n- **Streaming responses** for improved user experience\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **API Key Errors**: Verify all required environment variables are set\n2. **Database Connection**: Check Supabase URL and key configuration\n3. **Model Timeouts**: Adjust timeout settings in LLM configuration\n4. **Memory Issues**: Monitor token usage and implement batching\n\n### Debug Mode\n\nEnable verbose logging:\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [LangChain](https://langchain.com/) and [LangGraph](https://langgraph.com/)\n- Database powered by [Supabase](https://supabase.com/)\n- Web search via [Tavily](https://tavily.com/)\n- CLI interface enhanced with [Rich](https://rich.readthedocs.io/)\n\n## 📞 Support\n\nFor questions, issues, or contributions:\n- 📧 Email: bertan.gunyel@gmail.com\n- 🐛 Issues: [GitHub Issues](https://github.com/bgunyel/ragnar/issues)\n- 💬 Discussions: [GitHub Discussions](https://github.com/bgunyel/ragnar/discussions)\n\n---\n\n**RAGNAR** - *Empowering business intelligence through AI-driven research and knowledge management.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgunyel%2Fragnar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbgunyel%2Fragnar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgunyel%2Fragnar/lists"}