Crate aingle_cortex

Source

Expand description

§AIngle Córtex API

Complete REST/GraphQL/SPARQL API for querying and interacting with AIngle semantic graphs.

§Features (100%)

§Core APIs

✅ REST API - Full CRUD operations for RDF triples
✅ GraphQL API - Schema with queries, mutations, and subscriptions
✅ SPARQL Engine - Full SPARQL 1.1 query support with FILTER expressions

§Security & Performance

✅ Authentication - JWT-based auth with Argon2id password hashing
✅ Rate Limiting - Token bucket algorithm (100 req/min default)
✅ CORS - Configurable cross-origin resource sharing
✅ Request Tracing - Comprehensive logging and metrics

§Advanced Features

✅ Proof System - Zero-knowledge proof storage and verification
✅ Real-time Subscriptions - WebSocket-based GraphQL subscriptions
✅ Pattern Queries - Flexible triple pattern matching
✅ API Versioning - All endpoints use /api/v1/ prefix
✅ Error Handling - Structured errors with codes and details
✅ OpenAPI Spec - Complete OpenAPI 3.1 documentation

§Quick Start

§Installation

Add to your Cargo.toml:

[dependencies]
aingle_cortex = { version = "0.1", features = ["full"] }

§Basic Server

use aingle_cortex::{CortexServer, CortexConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = CortexConfig::default();
    let server = CortexServer::new(config)?;
    server.run().await?;
    Ok(())
}

§Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Córtex API Server                       │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐  ┌──────────────────┐                 │
│  │   REST API       │  │   GraphQL API    │                 │
│  │   /api/v1/*      │  │   /graphql       │                 │
│  └────────┬─────────┘  └────────┬─────────┘                 │
│           │                     │                            │
│  ┌────────┴─────────────────────┴─────────┐                 │
│  │              Query Router               │                 │
│  └────────┬─────────────────────┬─────────┘                 │
│           │                     │                            │
│  ┌────────▼─────────┐  ┌───────▼──────────┐                 │
│  │   SPARQL Engine  │  │  Proof Validator │                 │
│  └────────┬─────────┘  └───────┬──────────┘                 │
│           │                     │                            │
│  ┌────────▼─────────────────────▼─────────┐                 │
│  │    aingle_graph + aingle_logic         │                 │
│  └─────────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

§REST API

Base URL: http://localhost:8080/api/v1

§Triples

# Create triple
curl -X POST http://localhost:8080/api/v1/triples \
  -H "Content-Type: application/json" \
  -d '{"subject": "ex:Alice", "predicate": "foaf:name", "object": {"string": "Alice"}}'

# List triples
curl "http://localhost:8080/api/v1/triples?predicate=foaf:knows"

§SPARQL

curl -X POST http://localhost:8080/api/v1/sparql \
  -H "Content-Type: application/sparql-query" \
  -d 'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10'

§Proofs

# Submit proof
curl -X POST http://localhost:8080/api/v1/proofs \
  -d '{"proof_type": "plonk", "proof_data": "..."}'

# Verify proof
curl http://localhost:8080/api/v1/proofs/{id}/verify

§GraphQL API

Endpoint: http://localhost:8080/graphql

§Subscriptions

subscription {
  tripleAdded(filter: { predicate: "foaf:knows" }) {
    hash
    subject
    predicate
    timestamp
  }
}

subscription {
  validationEvent(validOnly: true) {
    hash
    valid
    proofHash
  }
}

subscription {
  agentActivity(agentId: "did:key:...") {
    action
    tripleHash
    timestamp
  }
}

§Rate Limiting

All endpoints: 100 requests per minute per IP (configurable)

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

429 Response:

{
  "error": "Rate limit exceeded. Retry after 30 seconds",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 30
}

§Error Handling

Structured error responses:

{
  "error": "Triple not found",
  "code": "NOT_FOUND",
  "details": null
}

Error codes: NOT_FOUND, INVALID_INPUT, VALIDATION_ERROR, AUTH_ERROR, FORBIDDEN, RATE_LIMIT_EXCEEDED, QUERY_ERROR, SPARQL_PARSE_ERROR, PROOF_NOT_FOUND, TIMEOUT, CONFLICT, INTERNAL_ERROR

§Testing

# All tests
cargo test --features full

# Specific suites
cargo test --test proof_system_test
cargo test --test graphql_subscriptions_test
cargo test --test rate_limiting_test

§Documentation

OpenAPI: See openapi.yaml for complete REST API specification
API Docs: https://docs.rs/aingle_cortex
GraphQL Schema: Available at /graphql with GraphQL Playground

§License

Licensed under the Apache License, Version 2.0.

§AIngle Córtex - External API Layer

High-level API server for querying and interacting with AIngle semantic graphs.

§Features

REST API: CRUD operations for triples, pattern queries, proof validation
GraphQL API: Full schema with queries, mutations, and subscriptions
SPARQL Endpoint: W3C-compliant SPARQL 1.1 query engine
Authentication: JWT-based auth with role-based access control (RBAC)
Real-time Updates: WebSocket subscriptions for graph changes
Proof Validation: Verify zero-knowledge proofs and signatures

§Security

All endpoints support:

Bearer token authentication
Rate limiting (configurable)
CORS with allowed origins
Request size limits

§Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Córtex API Server                       │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐  ┌──────────────────┐                 │
│  │   REST API       │  │   GraphQL API    │                 │
│  │   /api/v1/*      │  │   /graphql       │                 │
│  └────────┬─────────┘  └────────┬─────────┘                 │
│           │                     │                            │
│  ┌────────┴─────────────────────┴─────────┐                 │
│  │              Query Router               │                 │
│  └────────┬─────────────────────┬─────────┘                 │
│           │                     │                            │
│  ┌────────▼─────────┐  ┌───────▼──────────┐                 │
│  │   SPARQL Engine  │  │  Proof Validator │                 │
│  └────────┬─────────┘  └───────┬──────────┘                 │
│           │                     │                            │
│  ┌────────▼─────────────────────▼─────────┐                 │
│  │           aingle_graph + aingle_logic   │                 │
│  └─────────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

§Quick Start

§Basic Server

use aingle_cortex::{CortexServer, CortexConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Start server on localhost:8080
    let config = CortexConfig::default();
    let server = CortexServer::new(config)?;
    server.run().await?;
    Ok(())
}

§Custom Configuration

use aingle_cortex::CortexConfig;

let config = CortexConfig::default()
    .with_port(3000)
    .with_host("0.0.0.0");

§REST API Examples

§Add a Triple

curl -X POST http://localhost:8080/api/v1/triples \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "subject": "alice",
    "predicate": "knows",
    "object": "bob"
  }'

§Query Triples

curl "http://localhost:8080/api/v1/triples?subject=alice"

§Validate Proof

curl -X POST http://localhost:8080/api/v1/proofs/validate \
  -H "Content-Type: application/json" \
  -d '{
    "proof_type": "schnorr",
    "proof_data": "...",
    "public_key": "..."
  }'

§GraphQL Examples

Access the GraphQL playground at http://localhost:8080/graphql.

§Query

query {
  triples(filter: { subject: "alice" }) {
    subject
    predicate
    object
    timestamp
  }
}

§Mutation

mutation {
  addTriple(input: {
    subject: "alice"
    predicate: "likes"
    object: "pizza"
  }) {
    success
    hash
  }
}

§Subscription

subscription {
  tripleAdded {
    subject
    predicate
    object
  }
}

§SPARQL Examples

SELECT ?person ?friend
WHERE {
  ?person <knows> ?friend .
}

Re-exports§

pub use error::Error;
pub use error::Result;
pub use server::CortexConfig;
pub use server::CortexServer;
pub use state::AppState;

Modules§

auth: Authentication and authorization for Córtex API
error: Error types for Córtex API
middleware: Middleware for Córtex API
prelude: Re-export commonly used types
proofs: Cryptographic proof storage and verification
rest: REST API endpoints for Córtex
server: Córtex API Server
sparql: SPARQL query engine for Córtex
state: Application state for Córtex API