A semantic AI founder network powered by LinkedIn data, AI-native agents, and ZeroDB's vector intelligence.
PublicFounders is a build-in-public platform that uses AI agents to intelligently connect founders, facilitate introductions, and accelerate growth through semantic matching.
- Backend Framework: Python 3.9+ with FastAPI
- Database: ZeroDB (unified NoSQL + vector storage)
- Authentication: LinkedIn OAuth 2.0
- Embeddings: OpenAI text-embedding-3-small (1536 dimensions)
- Testing: pytest with 80% minimum coverage
- Code Quality: Ruff, Black, MyPy, pre-commit hooks
- CI/CD: GitHub Actions
PublicFounders implements a unified semantic architecture:
Single Platform (ZeroDB): All data in one place - relational NoSQL tables + vector embeddings for semantic intelligence, eliminating the complexity of managing multiple databases while maintaining full auditability and AI capabilities.
- Python 3.9 or higher
- ZeroDB account (sign up at https://zerodb.ai)
- OpenAI API key
- Git
- Clone the repository:
git clone https://github.com/AINative-Studio/PublicFounders.git
cd PublicFounders- Create and activate virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies:
pip install -r requirements.txt
pip install -r requirements-dev.txt # For development-
Set up ZeroDB project:
- Create a project at https://zerodb.ai
- Get your API key and project ID
- Tables are already created (8 NoSQL tables)
-
Set up environment variables:
# Create .env file in project root
cat > .env << EOF
# ZeroDB Configuration
ZERODB_API_KEY=your_zerodb_api_key_here
ZERODB_PROJECT_ID=your_zerodb_project_id_here
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
# JWT Configuration
JWT_SECRET_KEY=your-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=10080
# LinkedIn OAuth (optional for development)
LINKEDIN_CLIENT_ID=your_linkedin_client_id
LINKEDIN_CLIENT_SECRET=your_linkedin_client_secret
LINKEDIN_REDIRECT_URI=http://localhost:8000/api/v1/auth/linkedin/callback
# Application Settings
ENVIRONMENT=development
API_V1_PREFIX=/api/v1
PROJECT_NAME=PublicFounders
EOF- Install pre-commit hooks (recommended for development):
pre-commit installDevelopment server:
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000Access the API:
- API Documentation: http://localhost:8000/api/docs
- ReDoc: http://localhost:8000/api/redoc
- Health Check: http://localhost:8000/health
No database migrations needed! ZeroDB tables are managed directly via the API.
cd backend
pytestpytest --cov=app --cov-report=html --cov-report=term-missingCoverage reports are generated in htmlcov/index.html.
# Unit tests only
pytest -m unit
# Integration tests only
pytest -m integration
# E2E tests only
pytest -m e2eThis project enforces 80% minimum test coverage. PRs that drop coverage below this threshold will fail CI checks.
Linting and Formatting:
# Run Ruff linter
ruff check backend/app tests
# Auto-fix issues
ruff check --fix backend/app tests
# Format code with Ruff
ruff format backend/app testsType Checking:
mypy backend/app --ignore-missing-importsSecurity Scanning:
bandit -r backend/appPre-commit hooks automatically run on every commit:
- Trailing whitespace removal
- End-of-file fixer
- YAML/JSON validation
- Ruff linting and formatting
- MyPy type checking
- Pytest with coverage check
Bypass hooks (not recommended):
git commit --no-verifyNo migrations needed! ZeroDB uses schema-less NoSQL tables that adapt automatically.
Working with data:
from app.services.zerodb_client import zerodb_client
# Insert data
await zerodb_client.insert_rows("users", [{
"id": str(uuid4()),
"email": "founder@example.com",
"name": "Jane Founder"
}])
# Query data
users = await zerodb_client.query_rows(
"users",
filter={"email": "founder@example.com"},
limit=10
)
# Update data
await zerodb_client.update_rows(
"users",
filter={"id": user_id},
update={"$set": {"name": "New Name"}}
)PublicFounders/
├── backend/
│ ├── alembic/ # Database migrations
│ │ └── versions/ # Migration files
│ ├── app/
│ │ ├── api/ # API endpoints
│ │ │ └── v1/
│ │ │ └── endpoints/ # Route handlers
│ │ ├── core/ # Core configuration
│ │ │ ├── config.py # Settings management
│ │ │ └── database.py # Database setup
│ │ ├── models/ # SQLAlchemy models
│ │ ├── schemas/ # Pydantic schemas
│ │ ├── services/ # Business logic
│ │ │ ├── embedding_service.py
│ │ │ └── zerodb_service.py
│ │ └── main.py # FastAPI app entry point
│ ├── alembic.ini # Alembic configuration
│ └── pytest.ini # Pytest configuration
├── tests/
│ ├── conftest.py # Shared test fixtures
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── .env # Environment variables (not in git)
├── .env.example # Example environment file
├── .pre-commit-config.yaml # Pre-commit hooks config
├── pyproject.toml # Python project configuration
├── requirements.txt # Production dependencies
├── requirements-dev.txt # Development dependencies
└── README.md # This file
- users: User authentication and profile data
- founder_profiles: Founder-specific preferences and bio
- companies: Company information
- company_roles: User-company relationships
- goals: Founder goals and objectives
- asks: Help requests from founders
- posts: Build-in-public content
- introductions: AI-facilitated connections
All tables automatically support vector embeddings for semantic search:
- Founder embeddings: Composite of bio + experience + goals
- Goal embeddings: Intent vectors for matching
- Ask embeddings: Help requests with urgency weighting
- Post embeddings: Content for discovery
Key Benefit: NoSQL data + vector embeddings in a single platform - no synchronization issues!
This project follows an agile sprint methodology:
- Sprint 0 (Foundation Setup): Database, API, testing framework ✅
- Sprint 1: Authentication, LinkedIn OAuth, profile management ✅
- Sprint 2: Goals, asks, and posts ✅
- Sprint 3: Semantic intelligence and embeddings
- Sprint 4: Virtual advisor and intro suggestions
- Sprint 5: Introduction execution and outcomes
- Sprint 6: Feed and discovery
- Sprint 7: Permissions, audit, and safety
- Sprint 8: KPI tracking and reporting
See sprintplan.md for detailed sprint breakdown.
GET /health
Returns API health status and version information.
{
"status": "healthy",
"service": "PublicFounders API",
"version": "1.0.0",
"environment": "development"
}/api/v1/auth/*- Authentication endpoints/api/v1/profile/*- Profile management/api/v1/goals/*- Goal CRUD operations/api/v1/asks/*- Ask management/api/v1/posts/*- Content posting/api/v1/introductions/*- Introduction workflows
Full API documentation available at /api/docs when running the server.
Required environment variables for PublicFounders:
| Variable | Description | Required |
|---|---|---|
ZERODB_API_KEY |
ZeroDB API key for database access | Yes |
ZERODB_PROJECT_ID |
ZeroDB project identifier | Yes |
OPENAI_API_KEY |
OpenAI API key for embeddings | Yes |
JWT_SECRET_KEY |
JWT signing key (change in prod!) | Yes |
JWT_ALGORITHM |
JWT algorithm (HS256) | Yes |
JWT_ACCESS_TOKEN_EXPIRE_MINUTES |
Token expiry (7 days = 10080) | Yes |
LINKEDIN_CLIENT_ID |
LinkedIn OAuth client ID | Optional |
LINKEDIN_CLIENT_SECRET |
LinkedIn OAuth secret | Optional |
LINKEDIN_REDIRECT_URI |
OAuth callback URL | Optional |
ENVIRONMENT |
Environment (development/production) | Yes |
Note: No PostgreSQL or Redis required - everything runs on ZeroDB!
- One Platform: NoSQL tables + vector embeddings in a single database
- No Syncing: Relational data and semantic vectors always in sync
- Fewer Dependencies: No PostgreSQL, no Redis, no connection pooling complexity
- No Migrations: Schema-less NoSQL adapts automatically
- Simple API: MongoDB-style queries, not SQL or ORM
- Fast Development: No database setup, just API credentials
- Easy Testing: Direct HTTP API calls, no database containers
- Lower Latency: Direct REST API, no ORM overhead
- Built-in Caching: ZeroDB handles caching internally
- Cost Effective: Single subscription vs. multiple database services
- Auto Scaling: Distributed architecture handles growth
- Semantic Search: Vector embeddings built-in, no separate store
- RLHF Support: Event streams for reinforcement learning
- Agent Memory: Long-term learning capabilities
- Quantum Ready: Future-proof for advanced AI workloads
Issue: ZERODB_API_KEY not found
- Solution: Make sure
.envfile exists in project root with valid API key
Issue: httpx.HTTPStatusError: 401 Unauthorized
- Solution: Check that your ZeroDB API key is valid and not expired
Issue: Table not found error
- Solution: Verify your
ZERODB_PROJECT_IDis correct and tables are created
Issue: OpenAI embeddings failing
- Solution: Check
OPENAI_API_KEYis valid and has available credits
Need help? Open an issue on GitHub or contact support@ainative.studio
GitHub Actions automatically run on all PRs and pushes to main/develop:
- Lint Check: Ruff linting and formatting
- Type Check: MyPy static analysis
- Tests: Full test suite with 80% coverage requirement
- Security Scan: Bandit security analysis
- Build Check: Verify application builds
- Create a feature branch from
develop - Make your changes following code standards
- Ensure all tests pass and coverage >= 80%
- Submit a pull request to
develop
Copyright (c) 2025 AINative Studio. All rights reserved.
See LICENSE for details.
For issues and questions:
- GitHub Issues: https://github.com/AINative-Studio/PublicFounders/issues
- Documentation: See
docs/directory - Email: support@ainative.studio
Built with ❤️ by the AINative team