|
Warning
|
This is the TARGET design, not the current state. Read it as intent. Several components specified below were never built, and one contradicts a later ruling:
It also predates the estate pipeline ( |
|
Note
|
Note — which product is this?
This document describes OikosBot, the code-analysis GitHub/GitLab App.
Its Rust analysis workspace is |
Oikos Bot is an intelligent code analysis platform that acts as a consultant, advisor, regulator, and policy developer for software repositories. It complements existing tools like Dependabot, CodeQL, and Copilot by adding a dedicated ecological and economic lens to code analysis.
┌─────────────────────────────────────────────────────────────────────────────┐ │ EXISTING ECOSYSTEM (Collaborate With) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Dependabot CodeQL Copilot Renovate │ │ ─────────── ────── ─────── ──────── │ │ Dependencies Security AI Assist Updates │ │ │ │ │ │ │ │ └─────────────────┼────────────────┼──────────────────┘ │ │ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ SHARED CONTEXT LAYER │ │ │ │ - Common prompt templates for eco/econ awareness │ │ │ │ - Shared analysis results via APIs │ │ │ │ - Unified reporting dashboard │ │ │ │ - Cross-tool recommendations │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ OIKOS BOT │ │ │ │ - Ecological analysis (carbon, energy, resources) │ │ │ │ - Economic optimization (Pareto, allocative efficiency) │ │ │ │ - Quality metrics with eco/econ weighting │ │ │ │ - Policy development and learning │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘
Key Integration Principles:
-
Additive Value: Oikos Bot adds eco/econ analysis; doesn’t duplicate security/dependency work
-
Shared Prompts: Provide prompt templates that Copilot/AI tools can use for eco-aware suggestions
-
Data Exchange: Consume and produce data in formats other tools understand
-
Non-Blocking: Advisory by default; teams opt-in to enforcement
-
First-Class Thinking: Make ecological/economic reasoning as natural as security/testing
-
Ecological Criteria
-
Carbon intensity of code execution (SCI - Software Carbon Intensity)
-
Energy efficiency patterns
-
Resource utilization optimization
-
Sustainable computing practices
-
-
Economic Criteria
-
Pareto Optimality: No change can make one aspect better without making another worse
-
Allocative Efficiency: Resources allocated to maximize total value
-
Technical debt as economic liability
-
Opportunity cost of architectural decisions
-
-
Quality Metrics
-
Cyclomatic complexity
-
Coupling/cohesion analysis
-
Test coverage economics
-
Documentation completeness
-
┌─────────────────────────────────────────────────────────────────────────────┐ │ OIKOS BOT PLATFORM │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │ GitHub Bot │ │ GitLab Bot │ │ CLI Tool │ │ │ │ Integration │ │ Integration │ │ Interface │ │ │ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │ │ │ │ │ │ │ └───────────────────┼───────────────────┘ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ ORCHESTRATION LAYER (Rust) │ │ │ │ - Request routing & scheduling │ │ │ │ - Analysis pipeline coordination │ │ │ │ - Result aggregation & reporting │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────────┼───────────────────┐ │ │ ▼ ▼ ▼ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │ HASKELL │ │ OCAML │ │ PYTHON │ │ │ │ Code Analyzer │ │ Doc Analyzer │ │ ML/DeepProb │ │ │ │ │ │ │ │ │ │ │ │ - Type safety │ │ - NLP parsing │ │ - DeepProbLog │ │ │ │ - Purity check │ │ - Semantic │ │ - Pattern │ │ │ │ - Complexity │ │ extraction │ │ learning │ │ │ │ - Energy est. │ │ - Consistency │ │ - Anomaly det. │ │ │ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │ │ │ │ │ │ │ └───────────────────┼───────────────────┘ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ POLICY ENGINE (Datalog + DeepProbLog) │ │ │ │ - Rule inference & learning │ │ │ │ - Policy generation from practice │ │ │ │ - Probabilistic reasoning │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ VERISIMDB (identity-consonance octad) │ │ │ │ - Graph + Document witnesses (code relationships, history, metadata) │ │ │ │ - Semantic witness (RDF/ontology, proof blobs) │ │ │ │ - + vector / temporal / provenance witnesses │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ ECHIDNA (Math Proofs/Solvers) │ │ │ │ gitlab.com/hyperpolymath/echidna │ │ │ │ - Formal verification of optimality claims │ │ │ │ - Economic model validation │ │ │ │ - Constraint satisfaction │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘
Why Haskell?
-
Strong type system for reliable analysis
-
Pure functions = predictable behavior
-
Excellent for AST manipulation
-
Pattern matching for code pattern detection
Capabilities:
-- Core analysis types
data EcoAnalysis = EcoAnalysis
{ carbonIntensity :: CarbonScore -- Estimated CO2/execution
, energyEfficiency :: EnergyScore -- Energy patterns
, resourceAllocation :: AllocationScore -- Memory/CPU efficiency
, paretoFrontier :: [ParetoPoint] -- Optimal trade-offs
}
data QualityAnalysis = QualityAnalysis
{ complexity :: ComplexityMetrics
, coupling :: CouplingScore
, technicalDebt :: DebtEstimate
, testCoverage :: CoverageAnalysis
}Analysis Modules:
-
Eco.Carbon- Carbon intensity estimation -
Eco.Energy- Energy pattern detection -
Eco.Pareto- Multi-objective optimization analysis -
Quality.Complexity- Cyclomatic/cognitive complexity -
Quality.Coupling- Dependency analysis -
Quality.Debt- Technical debt quantification
Why OCaml?
-
Excellent for parsing and language processing
-
Strong module system for separation of concerns
-
Efficient compilation
-
Good interop with formal methods tools
Capabilities:
(* Documentation analysis pipeline *)
type doc_analysis = {
completeness: float; (* 0.0 - 1.0 *)
consistency: consistency_report; (* Internal consistency *)
semantic_coverage: semantic_map; (* Concept coverage *)
readability: readability_scores; (* Various readability metrics *)
eco_alignment: eco_alignment_report; (* Alignment with eco principles *)
}
(* Natural language processing for docs *)
module DocNLP : sig
val extract_concepts : document -> concept list
val check_consistency : document list -> inconsistency list
val assess_completeness : document -> api_surface -> float
endArchitecture:
┌─────────────────────────────────────────────────────────────┐ │ POLICY ENGINE │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ DATALOG │ │ DEEPPROBLOG │ │ │ │ (Certainties) │◄───────►│ (Uncertainties)│ │ │ │ │ │ │ │ │ │ % Hard rules │ │ % Learned rules │ │ │ │ efficient(X) :- │ │ nn(energy_net, │ │ │ │ low_carbon(X),│ │ [Code], │ │ │ │ fast(X). │ │ Score) :: │ │ │ │ │ │ efficient(X). │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ └───────────┬───────────────┘ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────┐│ │ │ PRAXIS FEEDBACK LOOP ││ │ │ Theory ──► Practice ──► Observation ──► Theory Update ││ │ └─────────────────────────────────────────────────────────┘│ │ │ └─────────────────────────────────────────────────────────────┘
Example Policies:
% Datalog: Deterministic rules
pareto_dominated(X, Y) :-
all_metrics(X, MetricsX),
all_metrics(Y, MetricsY),
dominated_by(MetricsX, MetricsY).
needs_refactor(Component) :-
technical_debt(Component, Debt),
Debt > threshold(high),
not(pareto_optimal(Component)).
% DeepProbLog: Probabilistic learned rules
nn(carbon_estimator, [CodeFeatures], CarbonScore) ::
high_carbon(Code) :- CarbonScore > 0.7.
0.8 :: eco_friendly(Code) :-
low_carbon(Code),
efficient_memory(Code).VeriSimDB (Veridical Simulacrum Database) is a single identity-consonance engine
in which one identity is an octad of eight modal witnesses — graph, vector,
tensor, semantic, document, temporal, provenance, spatial. It subsumes the
previously-planned pair of stores. The graph + document witnesses replace
ArangoDB (code-dependency graphs, analysis history and trends, project
metadata, change tracking), and the semantic witness replaces Virtuoso
(RDF/ontology knowledge — e.g. SEON/CodeOntology — linked open data, and proof
blobs). The eco/econ ontology seed for the semantic witness lives at
databases/ontology/eco.ttl.
Interaction is via VCL (VeriSim Consonance Language, legacy name VQL), with
REST (connectors/shared/openapi/verisim-api-v1.yaml, base path /api/v1),
gRPC federation (connectors/shared/proto/verisim_federation.proto), and a Zig
FFI (ffi/zig/) client surface.
VeriSimDB is v0.1.0 and OikosBot’s runtime client is deferred/gated — the data layer is retargeted in design and config now; runtime wiring lands later (it depends on VeriSimDB maturing and on the AffineScript transport).
-
Answers questions about code efficiency
-
Provides alternative implementations
-
Explains trade-offs
-
Proactive suggestions on PRs/commits
-
Best practice recommendations
-
Learning resource suggestions
-
Enforces policy compliance
-
Blocks PRs that violate eco-standards
-
Generates compliance reports
1. TRIGGER └─► PR opened / Push / Schedule / Manual 2. FETCH └─► Clone/fetch repository content 3. PARSE ├─► Haskell: Parse code ASTs └─► OCaml: Parse documentation 4. ANALYZE ├─► Carbon intensity estimation ├─► Energy pattern detection ├─► Complexity metrics ├─► Pareto frontier calculation └─► Documentation completeness 5. REASON ├─► Datalog: Apply deterministic rules └─► DeepProbLog: Probabilistic inference 6. VERIFY (optional) └─► Echidna: Formal verification of claims 7. STORE └─► VeriSimDB octad: store results into the graph/document/semantic/temporal/provenance witnesses 8. REPORT ├─► Generate findings report ├─► Create PR comments ├─► Update dashboards └─► Suggest improvements 9. LEARN └─► Feed outcomes back to policy engine
EcoScore = w1*CarbonScore + w2*EnergyScore + w3*ResourceScore Where: - CarbonScore: Based on SCI specification (ISO/IEC 21031:2024) - EnergyScore: Energy efficiency patterns - ResourceScore: Memory/CPU utilization efficiency
EconScore = w1*ParetoScore + w2*AllocationScore + w3*DebtScore Where: - ParetoScore: Distance from Pareto frontier - AllocationScore: Allocative efficiency measure - DebtScore: Inverse of technical debt burden
| Component | Language | Purpose |
|---|---|---|
Orchestrator |
Rust |
High-performance coordination |
Code Analyzer |
Haskell |
AST analysis, type checking |
Doc Analyzer |
OCaml |
NLP, semantic extraction |
Policy Engine |
Python + Datalog |
Rule inference, ML |
DeepProbLog |
Python |
Probabilistic logic learning |
Bot Interface |
AffineScript |
GitHub/GitLab webhook receiver (bot-integration-affine/) |
Datastore |
VeriSimDB |
Identity-consonance octad (graph/vector/tensor/semantic/document/temporal/provenance/spatial) |
Math Proofs |
Echidna (external) |
Formal verification |
GitHub Actions/Apps Integration:
# .github/workflows/oikos.yml
name: Oikos Analysis
on: [pull_request, push]
jobs:
eco-analysis:
runs-on: ubuntu-latest
steps:
- uses: hyperpolymath/oikosbot-action@v1
with:
mode: advisor # consultant | advisor | regulator
eco-threshold: 60
econ-threshold: 50
# Oikos Bot results feed into other tools
- uses: actions/upload-artifact@v3
with:
name: eco-analysis
path: .oikos-bot/results.jsonIntegration Points:
-
Dependabot: Oikos Bot can add eco-scores to dependency update PRs
-
CodeQL: Share SARIF format results for unified security+eco view
-
Copilot: Provide context via
.github/copilot-instructions.md
Shared Prompt Templates (the Copilot template now lives at .github/copilot-instructions.md; the prompts/ directory was removed):
Oikos Bot provides prompt templates that AI coding assistants can use:
<!-- .github/copilot-instructions.md (auto-generated by oikos-bot) -->
## Ecological Code Guidelines
When writing or reviewing code in this repository, consider:
1. **Carbon Efficiency**: Prefer algorithms with lower computational complexity
2. **Energy Patterns**: Avoid busy-waiting, prefer event-driven designs
3. **Resource Allocation**: Release resources promptly, use pooling
4. **Pareto Optimality**: When making trade-offs, document the decision
Current repo eco-score: 72/100
Areas needing attention: Memory allocation in /src/processing/*SARIF Extension for Eco-Metrics:
{
"$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
"runs": [{
"tool": {
"driver": {
"name": "oikos-bot",
"version": "1.0.0",
"informationUri": "https://oikos-bot.dev"
}
},
"results": [{
"ruleId": "eco/high-carbon-loop",
"message": { "text": "Loop has O(n³) complexity, consider optimization" },
"properties": {
"ecoScore": 35,
"carbonEstimate": "high",
"paretoStatus": "dominated",
"alternatives": ["Use memoization", "Consider parallel processing"]
}
}]
}]
}OpenTelemetry Integration:
oikos_bot_analysis_score{type="ecological",repo="myrepo"} 72
oikos_bot_analysis_score{type="economic",repo="myrepo"} 68
oikos_bot_carbon_intensity{repo="myrepo"} 0.34
oikos_bot_pareto_distance{repo="myrepo"} 0.12
┌─────────────────────────────────────────────────────────────────────────┐ │ INTEGRATED ANALYSIS WORKFLOW │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ PR Opened │ │ │ │ │ ├──► Dependabot: Check dependencies ────────────────┐ │ │ │ │ │ │ │ │ └──► Oikos Bot: Score eco-impact ◄────────┤ │ │ │ of new dependencies │ │ │ │ │ │ │ ├──► CodeQL: Security scan ─────────────────────────┤ │ │ │ │ │ │ │ │ └──► Oikos Bot: Security + Eco ◄──────────┤ │ │ │ combined risk score │ │ │ │ │ │ │ ├──► Copilot: Review suggestions ───────────────────┤ │ │ │ │ │ │ │ │ └──► Oikos Bot: Enhance suggestions ◄─────┤ │ │ │ with eco/econ context │ │ │ │ ▼ │ │ │ ┌─────────────────┐ │ │ └──────────────────────────────────────────► UNIFIED REPORT │ │ │ └─────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────┐
│ PRAXIS FEEDBACK LOOP │
└─────────────────────────────────────┘
│
┌────────────────────────────┼────────────────────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ THEORY │ │ PRACTICE │ │ LEARNING │
│ │ │ │ │ │
│ Economic │──────────────► Code │──────────────► Observe │
│ models │ Apply to │ changes │ Measure │ outcomes │
│ Eco rules │ real code │ PRs │ results │ patterns │
│ │ │ │ │ │
└─────┬─────┘ └───────────┘ └─────┬─────┘
│ │
│ ┌───────────┐ │
│ │ UPDATE │ │
└────────────────────│ THEORY │◄───────────────────┘
│ │
│ DeepProb- │
│ Log learns│
│ new rules │
└───────────┘
Consonance, Not Cross-Database Sync:
There is no longer any cross-database synchronization to maintain. VeriSimDB keeps the eight witnesses of one identity in consonance internally, with built-in drift detection and self-normalization — so the old ArangoDB↔Virtuoso two-store synchronization problem disappears entirely.
VERISIMDB (one identity, eight witnesses)
─────────────────────────────────────────
graph · document · semantic · temporal ·
vector · tensor · provenance · spatial
internal consonance maintenance
(drift detection + self-normalize)
│
▼
┌───────────────┐
│ ECHIDNA │
│ (Proofs) │
│ │
│ Verify claims │
│ Solve optim. │
└───────────────┘