aingle_cortex/
lib.rs

1#![doc = include_str!("../README.md")]
2//! # AIngle Córtex - External API Layer
3//!
4//! High-level API server for querying and interacting with AIngle semantic graphs.
5//!
6//! ## Features
7//!
8//! - **REST API**: CRUD operations for triples, pattern queries, proof validation
9//! - **GraphQL API**: Full schema with queries, mutations, and subscriptions
10//! - **SPARQL Endpoint**: W3C-compliant SPARQL 1.1 query engine
11//! - **Authentication**: JWT-based auth with role-based access control (RBAC)
12//! - **Real-time Updates**: WebSocket subscriptions for graph changes
13//! - **Proof Validation**: Verify zero-knowledge proofs and signatures
14//!
15//! ## Security
16//!
17//! All endpoints support:
18//! - Bearer token authentication
19//! - Rate limiting (configurable)
20//! - CORS with allowed origins
21//! - Request size limits
22//!
23//! ## Architecture
24//!
25//! ```text
26//! ┌─────────────────────────────────────────────────────────────┐
27//! │                      Córtex API Server                       │
28//! ├─────────────────────────────────────────────────────────────┤
29//! │  ┌──────────────────┐  ┌──────────────────┐                 │
30//! │  │   REST API       │  │   GraphQL API    │                 │
31//! │  │   /api/v1/*      │  │   /graphql       │                 │
32//! │  └────────┬─────────┘  └────────┬─────────┘                 │
33//! │           │                     │                            │
34//! │  ┌────────┴─────────────────────┴─────────┐                 │
35//! │  │              Query Router               │                 │
36//! │  └────────┬─────────────────────┬─────────┘                 │
37//! │           │                     │                            │
38//! │  ┌────────▼─────────┐  ┌───────▼──────────┐                 │
39//! │  │   SPARQL Engine  │  │  Proof Validator │                 │
40//! │  └────────┬─────────┘  └───────┬──────────┘                 │
41//! │           │                     │                            │
42//! │  ┌────────▼─────────────────────▼─────────┐                 │
43//! │  │           aingle_graph + aingle_logic   │                 │
44//! │  └─────────────────────────────────────────┘                 │
45//! └─────────────────────────────────────────────────────────────┘
46//! ```
47//!
48//! ## Quick Start
49//!
50//! ### Basic Server
51//!
52//! ```rust,ignore
53//! use aingle_cortex::{CortexServer, CortexConfig};
54//!
55//! #[tokio::main]
56//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
57//!     // Start server on localhost:8080
58//!     let config = CortexConfig::default();
59//!     let server = CortexServer::new(config)?;
60//!     server.run().await?;
61//!     Ok(())
62//! }
63//! ```
64//!
65//! ### Custom Configuration
66//!
67//! ```rust,ignore
68//! use aingle_cortex::CortexConfig;
69//!
70//! let config = CortexConfig::default()
71//!     .with_port(3000)
72//!     .with_host("0.0.0.0");
73//! ```
74//!
75//! ## REST API Examples
76//!
77//! ### Add a Triple
78//!
79//! ```bash
80//! curl -X POST http://localhost:8080/api/v1/triples \
81//!   -H "Content-Type: application/json" \
82//!   -H "Authorization: Bearer YOUR_TOKEN" \
83//!   -d '{
84//!     "subject": "alice",
85//!     "predicate": "knows",
86//!     "object": "bob"
87//!   }'
88//! ```
89//!
90//! ### Query Triples
91//!
92//! ```bash
93//! curl "http://localhost:8080/api/v1/triples?subject=alice"
94//! ```
95//!
96//! ### Validate Proof
97//!
98//! ```bash
99//! curl -X POST http://localhost:8080/api/v1/proofs/validate \
100//!   -H "Content-Type: application/json" \
101//!   -d '{
102//!     "proof_type": "schnorr",
103//!     "proof_data": "...",
104//!     "public_key": "..."
105//!   }'
106//! ```
107//!
108//! ## GraphQL Examples
109//!
110//! Access the GraphQL playground at `http://localhost:8080/graphql`.
111//!
112//! ### Query
113//!
114//! ```graphql
115//! query {
116//!   triples(filter: { subject: "alice" }) {
117//!     subject
118//!     predicate
119//!     object
120//!     timestamp
121//!   }
122//! }
123//! ```
124//!
125//! ### Mutation
126//!
127//! ```graphql
128//! mutation {
129//!   addTriple(input: {
130//!     subject: "alice"
131//!     predicate: "likes"
132//!     object: "pizza"
133//!   }) {
134//!     success
135//!     hash
136//!   }
137//! }
138//! ```
139//!
140//! ### Subscription
141//!
142//! ```graphql
143//! subscription {
144//!   tripleAdded {
145//!     subject
146//!     predicate
147//!     object
148//!   }
149//! }
150//! ```
151//!
152//! ## SPARQL Examples
153//!
154//! ```sparql
155//! SELECT ?person ?friend
156//! WHERE {
157//!   ?person <knows> ?friend .
158//! }
159//! ```
160
161#[cfg(feature = "auth")]
162pub mod auth;
163pub mod client;
164pub mod error;
165#[cfg(feature = "graphql")]
166pub mod graphql;
167pub mod middleware;
168pub mod proofs;
169pub mod rest;
170pub mod server;
171#[cfg(feature = "sparql")]
172pub mod sparql;
173pub mod state;
174
175pub use client::{CortexClientConfig, CortexInternalClient};
176pub use error::{Error, Result};
177pub use server::{CortexConfig, CortexServer};
178pub use state::AppState;
179
180/// Re-export commonly used types
181pub mod prelude {
182    pub use crate::error::{Error, Result};
183    pub use crate::proofs::{ProofStore, ProofType, StoredProof};
184    pub use crate::rest::TripleDto;
185    pub use crate::server::{CortexConfig, CortexServer};
186    pub use crate::state::AppState;
187}
aingle_cortex/lib.rs

aingle_cortex/
lib.rs
