{"id":51325636,"url":"https://github.com/lostluffyz/irtiqa-intelligence","last_synced_at":"2026-07-01T18:01:31.768Z","repository":{"id":362217240,"uuid":"1256118240","full_name":"lostluffyz/Irtiqa-Intelligence","owner":"lostluffyz","description":"AI-powered lead intelligence platform for technographic analysis, intent detection, and personalized outreach generation.","archived":false,"fork":false,"pushed_at":"2026-06-10T10:23:31.000Z","size":402,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T12:14:07.809Z","etag":null,"topics":["ai","automation","b2b","fastapi","lead-intelligence","python","sales-intelligence","technographics"],"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/lostluffyz.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-01T13:30:59.000Z","updated_at":"2026-06-10T10:23:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lostluffyz/Irtiqa-Intelligence","commit_stats":null,"previous_names":["lostluffyz/irtiqa-intelligence"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lostluffyz/Irtiqa-Intelligence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostluffyz%2FIrtiqa-Intelligence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostluffyz%2FIrtiqa-Intelligence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostluffyz%2FIrtiqa-Intelligence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostluffyz%2FIrtiqa-Intelligence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lostluffyz","download_url":"https://codeload.github.com/lostluffyz/Irtiqa-Intelligence/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostluffyz%2FIrtiqa-Intelligence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35017091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"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":["ai","automation","b2b","fastapi","lead-intelligence","python","sales-intelligence","technographics"],"created_at":"2026-07-01T18:01:16.755Z","updated_at":"2026-07-01T18:01:31.762Z","avatar_url":"https://github.com/lostluffyz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Irtiqa Intelligence\n\n[![CI](https://github.com/Luffyz/irtiqa-intelligence/actions/workflows/ci.yml/badge.svg)](https://github.com/Luffyz/irtiqa-intelligence/actions/workflows/ci.yml)\n[![Tests](https://img.shields.io/badge/tests-633%20passing-success)](https://github.com/Luffyz/irtiqa-intelligence)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688)](https://fastapi.tiangolo.com/)\n\n**Production-grade lead intelligence platform for B2B sales teams.**\n\nIrtiqa Intelligence automates lead discovery, enrichment, and prioritization through intelligent web scraping, technographic analysis, intent signal detection, and personalized outreach generation. Built with FastAPI, SQLAlchemy, and a modular agent-based architecture.\n\n---\n\n## What is Irtiqa?\n\nIrtiqa transforms raw company data into actionable sales intelligence through a **multi-agent pipeline**:\n\n1. **Discover** companies matching your ideal customer profile (ICP)\n2. **Scrape** and analyze company websites for technology signals\n3. **Detect** buying intent from hiring, funding, and technology changes\n4. **Score** leads using multi-factor intelligence scoring\n5. **Personalize** outreach messages based on company intelligence\n\n**Result:** Prioritized, scored leads with context-aware outreach recommendations.\n\n---\n\n## Architecture\n\n```mermaid\ngraph TD\n    subgraph Client[\"Client Layer\"]\n        UI[Web UI / API Client]\n    end\n    \n    subgraph API[\"API Layer (FastAPI)\"]\n        Routes[REST Endpoints\u003cbr/\u003e70+ endpoints]\n        Auth[JWT Authentication\u003cbr/\u003eMulti-Tenancy]\n    end\n    \n    subgraph Service[\"Service Layer\"]\n        Services[Business Logic\u003cbr/\u003eTransaction Boundaries]\n    end\n    \n    subgraph Intelligence[\"Intelligence Layer\"]\n        Workflows[3 Workflows\u003cbr/\u003eOrchestration]\n        Agents[6 Agents\u003cbr/\u003eSpecialized Intelligence]\n    end\n    \n    subgraph Data[\"Data Layer\"]\n        Repos[Repositories\u003cbr/\u003eTenant Filtering]\n        ORM[SQLAlchemy ORM\u003cbr/\u003e19 Tables]\n    end\n    \n    subgraph Storage[\"Storage Layer\"]\n        SQLite[(SQLite Dev)]\n        Postgres[(PostgreSQL Prod)]\n    end\n    \n    subgraph Jobs[\"Background Jobs\"]\n        Scheduler[Job Scheduler]\n        Runner[Job Runner]\n    end\n    \n    UI --\u003e|HTTP + JWT| Routes\n    Routes --\u003e|Verify \u0026 Inject| Auth\n    Auth --\u003e|Call Methods| Services\n    Services --\u003e|Orchestrate| Workflows\n    Services --\u003e|Execute| Agents\n    Workflows --\u003e|Chain| Agents\n    Agents --\u003e|Query/Persist| Repos\n    Services --\u003e|Query/Persist| Repos\n    Repos --\u003e|Map Entities| ORM\n    ORM --\u003e|Connect| SQLite\n    ORM --\u003e|Connect| Postgres\n    \n    Services -.-\u003e|Schedule Async| Scheduler\n    Scheduler --\u003e|Poll \u0026 Execute| Runner\n    Runner --\u003e|Invoke| Workflows\n    Runner --\u003e|Invoke| Agents\n    \n    style API fill:#e1f5ff\n    style Service fill:#fff4e1\n    style Intelligence fill:#ffe1e1\n    style Data fill:#f0e1ff\n    style Storage fill:#e1ffe1\n    style Jobs fill:#ffe1f5\n```\n\n**[📖 Complete Architecture Guide](docs/architecture_overview.md)**\n\n---\n\n## Features\n\n### 🔐 Authentication \u0026 Multi-Tenancy\n- **RS256 JWT Authentication** with JWKS endpoint for secure API access\n- **Email Verification** and password reset workflows\n- **Organization Management** with role-based access control (Owner, Admin, Member, Viewer)\n- **Tenant Isolation** across all data and API endpoints\n- **Rate Limiting** with database-backed tracking\n\n**[📖 Authentication Design](docs/authentication_multitenancy_v2_design.md)**\n\n### 🔍 Lead Discovery Engine\n\n```mermaid\nflowchart LR\n    ICP[ICP Search\u003cbr/\u003eIndustry + Size + Tech] --\u003e Discovery[Discovery Agent]\n    \n    Discovery --\u003e|Query| EDGAR[SEC EDGAR\u003cbr/\u003eUS Companies]\n    Discovery --\u003e|Query| News[Google News RSS\u003cbr/\u003eFunding Signals]\n    Discovery --\u003e|Query| OC[OpenCorporates\u003cbr/\u003eGlobal Registry]\n    \n    EDGAR --\u003e Dedupe[Deduplication\u003cbr/\u003eDomain Matching]\n    News --\u003e Dedupe\n    OC --\u003e Dedupe\n    \n    Dedupe --\u003e Score[Discovery Score\u003cbr/\u003e0.0-1.0]\n    Score --\u003e Companies[(Companies\u003cbr/\u003eneeds_review)]\n    \n    Companies -.-\u003e|Manual Trigger| Pipeline[Intelligence Pipeline]\n    \n    style Discovery fill:#e1f5ff\n    style Dedupe fill:#fff4e1\n    style Score fill:#ffe1e1\n    style Companies fill:#e1ffe1\n```\n\n- **ICP Search Management**: Define and save ideal customer profile criteria\n- **Multi-Source Discovery**: Automated searches across SEC EDGAR, Google News RSS, and OpenCorporates\n- **Smart Deduplication**: Domain-based duplicate detection with fuzzy matching\n- **Discovery Scoring**: Lightweight match quality scores (0.0-1.0) for prioritization\n- **Evidence Provenance**: Full audit trail of discovery sources\n\n**[📖 Discovery Engine Design](docs/lead_discovery_engine_final.md)**\n\n### 🤖 Intelligence Pipeline\n\n```mermaid\nflowchart LR\n    Input[Company Domain] --\u003e DS[Deep Scraper\u003cbr/\u003eWeb Extraction]\n    DS --\u003e|HTML + Text| Tech[Technographic\u003cbr/\u003eTech Detection]\n    Tech --\u003e|40+ Signatures| Intent[Intent Signal\u003cbr/\u003eBuying Signals]\n    Intent --\u003e|8 Signal Types| Score[Intelligence Scoring\u003cbr/\u003eMulti-Factor]\n    Score --\u003e|Weighted Score| Person[Personalization\u003cbr/\u003eOutreach Generation]\n    Person --\u003e Output[Scored Lead\u003cbr/\u003e+ Messages]\n    \n    style DS fill:#e1f5ff\n    style Tech fill:#fff4e1\n    style Intent fill:#ffe1e1\n    style Score fill:#f0e1ff\n    style Person fill:#e1ffe1\n```\n\n**6 Production Agents:**\n1. **Deep Scraper Agent**: Web content extraction and parsing\n2. **Technographic Agent**: Technology detection (40+ signatures across 8 categories)\n3. **Intent Signal Agent**: Buying signal detection (8 signal families with deterministic rules)\n4. **Intelligence Scoring Agent**: Multi-factor lead scoring (fit, intent, technographic, engagement)\n5. **Personalization Agent**: Multi-variant outreach message generation\n6. **Discovery Agent**: ICP-based company discovery from external sources\n\n**[📖 Agent System](docs/agents.md)** | **[📖 Workflow System](docs/workflows.md)**\n\n### 📊 Lead Retrieval API\n- **Aggregated Intelligence**: Single endpoint returns companies with technologies, intent signals, scores, and outreach messages\n- **Smart Filtering**: Filter by minimum score, pagination support\n- **Tenant-Scoped**: Automatic organization isolation\n- **N+1 Prevention**: Batch loading strategy for optimal performance\n\n### ⚙️ Background Job System\n- **Async Execution**: Agent and workflow scheduling with status tracking\n- **Retry Policies**: Exponential backoff with configurable limits\n- **Job Management**: Schedule, cancel, retry, and monitor background tasks\n\n**[📖 Background Jobs Design](docs/background_job_foundation_design.md)**\n\n### 📈 Evidence Records\n- **Provenance Tracking**: Full audit trail for all intelligence data\n- **Source Linking**: Evidence tied to agent runs, URLs, and API responses\n- **Confidence Scoring**: Evidence quality metrics\n\n### 🔄 Workflow Orchestration\n- **Score Refresh**: Deterministic intelligence score recomputation\n- **Intelligence Pipeline**: End-to-end enrichment (scrape → analyze → score → personalize)\n- **Discovery Pipeline**: Company discovery orchestration (search → discover → deduplicate → create)\n\n---\n\n## Database Schema\n\n```mermaid\nerDiagram\n    organizations ||--o{ companies : owns\n    organizations ||--o{ contacts : owns\n    companies ||--o{ websites : has\n    companies ||--o{ technologies : uses\n    companies ||--o{ intent_signals : emits\n    companies ||--o{ intelligence_scores : receives\n    companies ||--o{ outreach_messages : targeted_by\n    \n    agent_runs ||--o{ technologies : detects\n    agent_runs ||--o{ intent_signals : finds\n    agent_runs ||--o{ intelligence_scores : computes\n    agent_runs ||--o{ outreach_messages : generates\n    agent_runs ||--o{ evidence_records : produces\n    \n    discovery_searches ||--o{ discovery_runs : executes\n    discovery_searches ||--o{ companies : discovers\n    \n    jobs ||--o{ agent_runs : triggers\n```\n\n**19 Tables:**\n- 8 core intelligence tables (companies, contacts, websites, technologies, intent_signals, intelligence_scores, outreach_messages, evidence_records)\n- 2 system tables (agent_runs, jobs)\n- 2 discovery tables (discovery_searches, discovery_runs)\n- 3 auth tables (users, organizations, memberships)\n- 4 token tables (refresh_tokens, email_verification_tokens, password_reset_tokens, failed_login_attempts)\n\n**[📖 Database Design](docs/database.md)** | **[📖 Entity Relationships](docs/entity_relationships.md)**\n\n---\n\n## Project Structure\n\n```\nirtiqa-intelligence/\n├── app/\n│   ├── agents/              # 6 production agents\n│   │   ├── deep_scraper/    # Web scraping \u0026 content extraction\n│   │   ├── technographic/   # Technology detection (40+ signatures)\n│   │   ├── intent_signal/   # Buying signal detection (8 families)\n│   │   ├── intelligence_scoring/  # Lead scoring\n│   │   ├── personalization/ # Outreach generation\n│   │   └── discovery/       # Company discovery (3 sources)\n│   ├── api/                 # REST API endpoints (70+)\n│   ├── core/                # Configuration, logging, errors\n│   ├── database/            # Engine, session management\n│   ├── jobs/                # Background job system\n│   ├── models/              # SQLAlchemy ORM models (19 tables)\n│   ├── repositories/        # Data access layer (15 repositories)\n│   ├── schemas/             # Pydantic request/response schemas\n│   ├── services/            # Business logic layer (15 services)\n│   └── workflows/           # Multi-agent orchestration (3 workflows)\n├── database/\n│   └── migrations/          # Alembic migration scripts (8 revisions)\n├── docs/                    # Architecture \u0026 design documentation\n├── tests/\n│   ├── integration/         # End-to-end tests\n│   └── unit/                # Component tests\n└── README.md\n```\n\n---\n\n## Tech Stack\n\n| Layer | Technology | Purpose |\n|-------|-----------|---------|\n| **Framework** | FastAPI 0.115+ | Async web framework with OpenAPI |\n| **ORM** | SQLAlchemy 2.0 | Database abstraction \u0026 query building |\n| **Migrations** | Alembic 1.18+ | Schema versioning \u0026 evolution |\n| **Validation** | Pydantic v2 | Request/response schemas |\n| **Database (Dev)** | SQLite 3.x | Local development with WAL mode |\n| **Database (Prod)** | PostgreSQL 18+ | Production-grade relational database |\n| **HTTP Client** | httpx | Async HTTP for external API calls |\n| **Parsing** | BeautifulSoup4, feedparser | HTML \u0026 RSS feed parsing |\n| **Testing** | pytest, pytest-asyncio | Test framework with async support |\n| **CI/CD** | GitHub Actions | Automated testing \u0026 validation |\n\n---\n\n## Testing\n\n```mermaid\nflowchart LR\n    Push[Git Push/PR] --\u003e CI[GitHub Actions]\n    \n    CI --\u003e Validate[Validation]\n    CI --\u003e Test[Testing]\n    \n    Validate --\u003e Ruff[Ruff Lint\u003cbr/\u003eAdvisory]\n    Validate --\u003e Mypy[Mypy Types\u003cbr/\u003eAdvisory]\n    Validate --\u003e Compile[compileall\u003cbr/\u003eBLOCKING]\n    \n    Test --\u003e Migrate[Alembic Upgrade\u003cbr/\u003eBLOCKING]\n    Test --\u003e Drift[Schema Drift Check\u003cbr/\u003eBLOCKING]\n    Test --\u003e SQLiteTests[SQLite Tests\u003cbr/\u003e606 tests\u003cbr/\u003eBLOCKING]\n    Test --\u003e PGTests[PostgreSQL Tests\u003cbr/\u003e27 tests\u003cbr/\u003eBLOCKING]\n    \n    Compile --\u003e Result{All Pass?}\n    Migrate --\u003e Result\n    Drift --\u003e Result\n    SQLiteTests --\u003e Result\n    PGTests --\u003e Result\n    \n    Result --\u003e|Yes| Success[✓ CI Pass]\n    Result --\u003e|No| Failure[✗ CI Fail]\n    \n    style Success fill:#e1ffe1\n    style Failure fill:#ffe1e1\n```\n\n**633 Tests** (606 SQLite, 27 PostgreSQL compatibility)  \n**100% Pass Rate** on main branch\n\n**Test Coverage:**\n- Unit tests for agents, services, schemas, workflows\n- Integration tests for API endpoints, repositories, pipelines\n- Database tests for migrations, constraints, transactions\n- PostgreSQL compatibility verification\n\n---\n\n## Development\n\n### Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/Luffyz/irtiqa-intelligence.git\ncd irtiqa-intelligence\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # Linux/Mac\n.venv\\Scripts\\activate      # Windows\n\n# Install dependencies\npip install -e .[dev]\n\n# For PostgreSQL support\npip install \"psycopg[binary]\u003e=3.2.0\"\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your settings\n```\n\n### Run Migrations\n\n```bash\n# Apply database schema\npython -m alembic upgrade head\n\n# Check for schema drift\npython -m alembic check\n```\n\n### Run Development Server\n\n```bash\n# Start FastAPI server\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n**API Documentation:**\n- Swagger UI: http://localhost:8000/docs\n- ReDoc: http://localhost:8000/redoc\n\n### Run Tests\n\n```bash\n# Execute full test suite\npython -m pytest\n\n# Run with coverage\npython -m pytest --cov=app --cov-report=html\n\n# Run specific test categories\npython -m pytest tests/unit/\npython -m pytest tests/integration/\n```\n\n---\n\n## Documentation Map\n\n### Getting Started\n- **[README](README.md)** — This file (overview, setup, quick start)\n- **[Architecture Overview](docs/architecture_overview.md)** — System layers, request lifecycle, patterns\n\n### Core Systems\n- **[Database Design](docs/database.md)** — Schema, tables, constraints, migrations\n- **[Entity Relationships](docs/entity_relationships.md)** — FK relationships, cascade rules\n- **[Agent System](docs/agents.md)** — All 6 agents, responsibilities, lifecycles\n- **[Workflow System](docs/workflows.md)** — Workflow orchestration, implementations\n- **[Background Jobs](docs/background_job_foundation_design.md)** — Async execution, retry policies\n\n### Features\n- **[Discovery Engine](docs/lead_discovery_engine_final.md)** — ICP search, external sources, deduplication\n- **[Authentication](docs/authentication_multitenancy_v2_design.md)** — JWT, multi-tenancy, RBAC\n- **[Evidence System](docs/evidence_records_system_design.md)** — Provenance tracking\n\n### Specialized Documentation\n- **[Agent Interface Design](docs/agent_interface_design.md)** — BaseAgent pattern details\n- **[Deep Scraper Design](docs/deep_scraper_design.md)** — Web scraping architecture\n- **[Technographic Agent Design](docs/technographic_agent_design.md)** — Technology detection\n- **[Intent Signal Agent Design](docs/intent_signal_agent_design.md)** — Buying signal rules\n- **[Personalization Agent Design](docs/personalization_agent_design.md)** — Outreach generation\n\n---\n\n## Roadmap\n\n### ✅ Current Status: Backend Complete\n\nThe backend is production-ready with all planned features implemented:\n- ✅ Authentication \u0026 multi-tenancy\n- ✅ Lead discovery engine\n- ✅ Intelligence pipeline (6 agents)\n- ✅ Workflow orchestration\n- ✅ Background job system\n- ✅ REST API (70+ endpoints)\n- ✅ 633 automated tests\n\n### 🎯 Next Milestones\n\n**Phase 1: Frontend Development**\n- React/Vue.js web application\n- ICP search builder UI\n- Discovery run monitoring dashboard\n- Lead review \u0026 enrichment interface\n- Intelligence score visualization\n\n**Phase 2: Production Deployment**\n- Docker containerization\n- PostgreSQL database migration\n- Kubernetes/cloud deployment manifests\n- CI/CD pipeline for releases\n- Monitoring \u0026 observability (Grafana, Prometheus)\n\n**Phase 3: Advanced Features**\n- Scheduled discovery runs (daily/weekly ICP searches)\n- ML-based lead scoring models\n- CRM integrations (Salesforce, HubSpot)\n- Email automation \u0026 outreach tracking\n- Advanced analytics \u0026 reporting\n\n---\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Ensure all tests pass (`python -m pytest`)\n5. Check for schema drift (`python -m alembic check`)\n6. Commit with descriptive messages\n7. Push to your fork and submit a pull request\n\n---\n\n## License\n\nThis project is proprietary software. All rights reserved.\n\n---\n\n## Acknowledgments\n\nBuilt with:\n- [FastAPI](https://fastapi.tiangolo.com/) — Modern Python web framework\n- [SQLAlchemy](https://www.sqlalchemy.org/) — Python SQL toolkit\n- [Alembic](https://alembic.sqlalchemy.org/) — Database migrations\n- [Pydantic](https://docs.pydantic.dev/) — Data validation\n- [pytest](https://pytest.org/) — Testing framework\n\n---\n\n**Production-Ready Backend · 633 Tests · 19 Database Tables · 6 Intelligence Agents · 70+ API Endpoints**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flostluffyz%2Firtiqa-intelligence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flostluffyz%2Firtiqa-intelligence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flostluffyz%2Firtiqa-intelligence/lists"}