{"id":31195662,"url":"https://github.com/aidecentralized/registry-master","last_synced_at":"2025-09-20T03:50:01.579Z","repository":{"id":315630696,"uuid":"1056884029","full_name":"aidecentralized/registry-master","owner":"aidecentralized","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-19T17:09:18.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-19T19:51:19.193Z","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/aidecentralized.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-09-15T01:29:07.000Z","updated_at":"2025-09-19T17:09:24.000Z","dependencies_parsed_at":"2025-09-19T20:08:24.110Z","dependency_job_id":null,"html_url":"https://github.com/aidecentralized/registry-master","commit_stats":null,"previous_names":["aidecentralized/registry-master"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aidecentralized/registry-master","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidecentralized%2Fregistry-master","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidecentralized%2Fregistry-master/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidecentralized%2Fregistry-master/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidecentralized%2Fregistry-master/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aidecentralized","download_url":"https://codeload.github.com/aidecentralized/registry-master/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidecentralized%2Fregistry-master/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276042128,"owners_count":25575000,"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-09-20T02:00:10.207Z","response_time":63,"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":[],"created_at":"2025-09-20T03:49:58.546Z","updated_at":"2025-09-20T03:50:01.574Z","avatar_url":"https://github.com/aidecentralized.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Global Registry Master\n\nA distributed agent registry service that acts as the entry point for finding and resolving agents globally. Stores namespaces and direct agent entries, returning lightweight pointers for full metadata resolution.\n\n## Architecture\n\n- **MongoDB**: Stores registry data with global replication\n- **FastAPI**: REST API service for agent discovery and management  \n- **Redis**: Caching layer (optional)\n- **Docker**: Containerized deployment\n\n## API Endpoints\n\n### Public (Read)\n- `GET /v1/index/search?searchparam=\u003cjson\u003e` - Search agents using structured key-value pairs\n- `GET /v1/agents/resolve?agent_name=\u003curn\u003e` - Resolve agent URN to address\n- `GET /healthz` - Health check\n\n### Admin (Write, Secured)\n- `POST /v1/admin/agent` - Add/update direct agent entry\n- `POST /v1/admin/namespace` - Add/update federated namespace\n- `POST /v1/admin/revoke` - Revoke an agent\n\n## Data Structure\n\n### Direct Agent Entry\n```json\n{\n  \"_id\": \"agent:nanda:uuid-1111\",\n  \"type\": \"direct\",\n  \"agent_id\": \"nanda:uuid-1111\", \n  \"agent_name\": \"urn:agent:nanda:TaxBot\",\n  \"facts_url\": \"https://nanda.com/.well-known/agent-facts/1111\",\n  \"resolver_url\": \"https://resolver.nanda.com/dispatch\",\n  \"tags\": [\"tax.calculate\", \"finance.reports\"],\n  \"ttl\": 3600,\n  \"signature\": \"ed25519:abcdef123...\",\n  \"publisher\": \"nanda\",\n  \"created_at\": \"2025-09-11T12:00:00Z\",\n  \"last_updated\": \"2025-09-11T12:00:00Z\"\n}\n```\n\n### Federated Namespace Entry\n```json\n{\n  \"_id\": \"ns:acme\",\n  \"type\": \"federated\", \n  \"namespace\": \"acme\",\n  \"sub_index_url\": \"https://registry.acme.com\",\n  \"registry_id\": \"REG003\",\n  \"ttl\": 7200,\n  \"signature\": \"ed25519:fed-sig-123...\",\n  \"created_at\": \"2025-09-11T12:00:00Z\",\n  \"last_updated\": \"2025-09-11T12:00:00Z\"\n}\n```\n\n### Search Keys (MongoDB Fields)\n- Multiple fields are combined with AND logic.\n- Provide the fields which are required only. \n```json\n{\n  \"agent_name\": \"string\",   // Search by agent name (partial match, case-insensitive)\n  \"agent_id\": \"string\",     // Search by agent ID (exact match)\n  \"tags\": \"string\",         // Search within tags array (partial match, case-insensitive)\n  \"publisher\": \"string\"     // Search by publisher (exact match)\n}\n```\n\n**Valid Search Keys:**\n- **agent_name**: Partial match with regex, case-insensitive (e.g., \"urn:agent:nanda\" matches agents with that prefix)\n- **agent_id**: Exact match (e.g., \"nanda:uuid-1111\")\n- **tags**: Partial match within tags array (e.g., \"tax\" matches \"tax.calculate\")\n- **publisher**: Exact match (e.g., \"nanda\")\n \n\n## Quick Start\n\n### Using Docker Compose (Recommended)\n\n1. **Clone and setup**:\n   ```bash\n   git clone \u003crepository\u003e\n   cd register-master\n   cp .env.example .env\n   # Edit .env with your configuration\n   ```\n\n2. **Start services**:\n   ```bash\n   docker-compose up -d\n   ```\n\n3. **Initialize database** (optional, with sample data):\n   ```bash\n   docker-compose up db-init\n   ```\n\n4. **Access API**:\n   - API: http://localhost:8000\n   - Documentation: http://localhost:8000/docs\n   - Health: http://localhost:8000/healthz\n\n### Manual Development Setup\n\n1. **Install dependencies**:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n2. **Start MongoDB**:\n   ```bash\n   # Using Docker\n   docker run -d -p 27017:27017 --name mongodb mongo:7.0\n   ```\n\n3. **Initialize database**:\n   ```bash\n   python init_db.py --seed\n   ```\n\n4. **Start API server**:\n   ```bash\n   uvicorn main:app --reload --port 8000\n   ```\n\n## Database Indexes\n\nThe system creates these indexes for optimal performance:\n\n- `agent_id` (unique, sparse) - Fast agent resolution\n- `agent_name` (unique, sparse) - URN lookup  \n- `namespace` (unique, sparse) - Federated namespace lookup\n- `tags` - Capability search\n- `type` - Entry type filtering\n- `[type, tags]` - Compound index for search optimization\n- `last_updated` - Maintenance queries\n\n## Authentication\n\nAdmin endpoints require Bearer token authentication:\n\n```bash\n# Set admin token in .env\nADMIN_TOKEN=your-secure-token\n\n# Use in requests\ncurl -H \"Authorization: Bearer your-secure-token\" \\\n  -X POST http://localhost:8000/v1/admin/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agent_id\": \"test:123\", ...}'\n```\n\n## Multi-VM Replica Set Deployment\n\n### Deploy on Each VM\nDeploy the same setup on all VMs (no configuration changes needed):\n```bash\n# On each VM (VM1, VM2, VM3, etc.)\ngit clone \u003crepository\u003e\ncd register-master\n\n# Start MongoDB and Redis\ndocker-compose up -d\n```\n\n### Initialize Replica Set\nSSH into any one VM and initialize the replica set:\n```bash\n# For 3 VMs\n./replica-init.sh 10.0.1.10:27017 10.0.1.11:27017 10.0.1.12:27017\n\n# For 2 VMs  \n./replica-init.sh 10.0.1.10:27017 10.0.1.11:27017\n```\n\n### Start API Service (Optional)\nOn VMs where you want the API service running:\n```bash\n# Update .env with replica set connection string\nMONGODB_URI=mongodb://admin:password@10.0.1.10:27017,10.0.1.11:27017/registry_master?replicaSet=rs0\u0026authSource=admin\n\n# Start API service\ndocker-compose --profile api up -d registry-service\n```\n\n### Initialize Database (Optional)\nAfter replica set is ready:\n```bash\ndocker-compose --profile init up db-init\n```\n\n### Service Profiles\n- **Default**: `docker-compose up -d` → MongoDB + Redis only\n- **API**: `--profile api` → Adds registry-service  \n- **Init**: `--profile init` → Runs database initialization\n\n## Monitoring\n\n- Health checks: `/healthz` endpoint\n- Database status included in health response\n- Ready for Route 53 health check integration\n- Container health checks configured\n\n## Example Usage\n\n### Search for agents\n\n**Structured search using MongoDB field names:**\n```bash\n# Search by agent name\ncurl \"http://localhost:8000/v1/index/search?searchparam={\\\"agent_name\\\":\\\"urn:agent:nanda\\\"}\"\n\n# Search by agent ID\ncurl \"http://localhost:8000/v1/index/search?searchparam={\\\"agent_id\\\":\\\"nanda:uuid-1111\\\"}\"\n\n# Search by capability tags\ncurl \"http://localhost:8000/v1/index/search?searchparam={\\\"tags\\\":\\\"tax.calculate\\\"}\"\n\n# Search by publisher\ncurl \"http://localhost:8000/v1/index/search?searchparam={\\\"publisher\\\":\\\"nanda\\\"}\"\n\n# Combined search with limit\ncurl \"http://localhost:8000/v1/index/search?searchparam={\\\"publisher\\\":\\\"nanda\\\",\\\"tags\\\":\\\"tax\\\"}\u0026limit=5\"\n```\n\n### Resolve agent\n```bash  \ncurl \"http://localhost:8000/v1/agents/resolve?agent_name=urn:agent:nanda:TaxBot\"\n```\n\n### Add agent (admin)\n```bash\ncurl -H \"Authorization: Bearer admin-secret-token\" \\\n  -X POST http://localhost:8000/v1/admin/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"agent_id\": \"nanda:uuid-1111\",\n    \"agent_name\": \"urn:agent:nanda:TaxBot\", \n    \"facts_url\": \"https://nanda.com/.well-known/agent-facts/1111\",\n    \"resolver_url\": \"https://resolver.nanda.com/dispatch\",\n    \"tags\": [\"tax.calculate\", \"finance.reports\"],\n    \"ttl\": 3600,\n    \"signature\": \"ed25519:abcdef123...\",\n    \"publisher\": \"nanda\"\n  }'\n```\n\n## License\n\n[Your license here]","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidecentralized%2Fregistry-master","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faidecentralized%2Fregistry-master","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidecentralized%2Fregistry-master/lists"}