Symbiont is an open-source, neuro-symbolic framework that fuses the creative power of generative AI with the structured, domain-specific knowledge of human scientists. It transforms generative AI from a blunt instrument into a precise, steerable partner, enabling a new era of co-creative scientific discovery.

graph LR
    subgraph "Define Constraints"
        A[Scientific Rules<br/>& Requirements]
    end

    subgraph "Compile to Logic"
        B[Differentiable<br/>Constraint Tree]
    end

    subgraph "Guide Generation"
        C[Gradient-Steered<br/>Output]
    end

    subgraph "Validate & Refine"
        D[Constraint<br/>Satisfaction]
    end

    A -->|DSL| B
    B -->|Loss Function| C
    C -->|Backprop| D
    D -->|Iterate| C

    style A fill:#e8f5e9
    style B fill:#fff9c4
    style C fill:#e3f2fd
    style D fill:#fce4ec

Generative AI models have demonstrated a remarkable ability to create novel scientific designs, but their practical application is hampered by a critical flaw: a lack of steerability and constraint adherence.

• The "Black Box" Problem: Current models generate outputs probabilistically, with little to no control for the scientist beyond the initial prompt.
• High Failure Rate: This leads to a costly "generate-and-filter" workflow, where a majority of generated candidates are invalid, unstable, or physically impossible, wasting massive computational and experimental resources.
• Untapped Human Expertise: The invaluable, hard-won knowledge of domain scientists has no direct mechanism for influencing the AI's creative process.

This impasse is a major bottleneck, preventing generative AI from reaching its full potential as a transformative tool for science.

Symbiont introduces a neuro-symbolic architecture that acts as an intelligent bridge between the human scientist and the generative AI. It allows scientists to define the non-negotiable rules, physical laws, and design principles of their domain as a "symbolic scaffold." The generative AI then explores the vast design space within those boundaries.

This transforms the workflow from "generate-and-filter" to "guided-generation," ensuring every output is not just novel, but also valid, feasible, and aligned with the scientist's strategic goals.

Symbiont is composed of four key components that work in a continuous, interactive loop:

graph TB
    subgraph "Human Scientist"
        DSL[Constraint DSL]
    end

    subgraph "Symbiont Framework"
        Compiler[Differentiable<br/>Compiler]
        Bridge[Neuro-Symbolic<br/>Bridge]
    end

    subgraph "AI Model"
        Generator[Generative<br/>Model]
    end

    DSL -->|Rules & Constraints| Compiler
    Compiler -->|Differentiable Loss| Bridge
    Bridge -->|Gradient Guidance| Generator
    Generator -->|Generated Output| Bridge
    Bridge -->|Satisfaction Score| DSL

    style DSL fill:#e1f5fe
    style Compiler fill:#fff3e0
    style Bridge fill:#fce4ec
    style Generator fill:#f3e5f5

1. The Generative Engine: A pluggable backend for state-of-the-art generative models (Transformers, GNNs, Diffusion Models).
2. The Symbolic Scaffolding Engine: An intuitive Python DSL for scientists to declare rules and constraints in a human-readable format.
3. The Neuro-Symbolic Bridge: The core of the framework. It translates the symbolic rules into a differentiable loss function that can steer the generative model via backpropagation.
4. The Interactive Discovery Dashboard: A web-based UI for defining rules, visualizing results in real-time, and creating a rapid, iterative discovery loop.

For a complete technical breakdown, please see our full Project Vision Document. For the theoretical foundations and detailed framework design, see our Conceptual Paper.

(This section will be updated as the project matures.)

To get started with Symbiont, you will need Python 3.9+ and PyTorch.

1. Clone the repository:

   git clone https://github.com/dilee/symbiont-core.git
   cd symbiont-core

2. Install the required dependencies:

   poetry install

3. Run the example script:

   poetry run python examples/toy_sequence.py

from symbiont import Rules, MockSequenceGenerator
from symbiont.utils import ProgressReporter

# Define constraints using intuitive DSL
rules = Rules()
rules.enforce(StartCodon())              # Must start with ATG
rules.constrain(GCContent(0.4, 0.6))     # GC content between 40-60%
rules.forbid(Contains("AAAA"))           # No poly-A sequences
rules.prefer(Contains("GAATTC"))         # Prefer EcoRI site

# Generate with constraints
generator = MockSequenceGenerator()
sequence = generator.constrained_generate(
    rules.compile(),
    length=100
)

# Track progress during iterative refinement (NEW!)
progress = ProgressReporter(rules.constraints, target_threshold=0.7)
progress.initialize(sequences, max_iterations=20)
for i in range(20):
    sequences = refine_step(sequences)  # Your refinement logic
    progress.update(sequences, iteration=i+1)
summary = progress.finalize()

Symbiont now includes a comprehensive template library for common molecular biology applications:

from symbiont.templates import PrimerDesignTemplate, CRISPRGuideTemplate

# PCR primer design with best practices built-in
primer_template = PrimerDesignTemplate(
    target_length=(18, 25),
    gc_content=(0.4, 0.6),
    avoid_hairpins=True
)
rules = primer_template.build()

# CRISPR guide RNA design
crispr_template = CRISPRGuideTemplate(
    pam_type="NGG",  # SpCas9
    length=20
)
rules = crispr_template.build()

# Discover available templates
from symbiont import registry
print(registry.search(domain="molecular_biology"))

Available Templates:

• PrimerDesignTemplate: PCR primer design with Tm, GC content, and hairpin constraints
• CRISPRGuideTemplate: Guide RNA design for Cas9/Cas12a systems
• CodonOptimizedTemplate: Codon optimization for different host organisms
• PromoterTemplate: Bacterial and mammalian promoter design
• CompositeTemplate: Combine multiple templates for complex applications

Run make template-demo to see all templates in action!

graph TD
    subgraph "Symbolic Layer"
        R1[Hard Rule:<br/>Must have X]
        R2[Soft Rule:<br/>Should have Y]
        R3[Forbidden:<br/>Must not have Z]
    end

    subgraph "Compilation"
        C1[Fuzzy Logic<br/>t-norms]
        C2[Weight<br/>Assignment]
        C3[Differentiable<br/>Operations]
    end

    subgraph "Neural Layer"
        L[Constraint Loss<br/>Function]
        G[Gradient<br/>Computation]
        O[Optimized<br/>Output]
    end

    R1 --> C1
    R2 --> C2
    R3 --> C1
    C1 --> C3
    C2 --> C3
    C3 --> L
    L --> G
    G --> O

    style R1 fill:#ffebee
    style R2 fill:#e8f5e9
    style R3 fill:#fce4ec

• Conceptual Paper - Theoretical foundations and framework design
• Project Vision - Long-term vision and strategic direction
• Development Roadmap - Phased development plan from prototype to production

We are actively looking for collaborators! Symbiont is an ambitious project, and its success depends on a diverse community of contributors. Whether you are an AI developer, a software engineer, a domain scientist, or a technical writer, there is a place for you here.

Please read our CONTRIBUTING.md file to learn about our development process, roadmap, and how you can get involved.

This project is licensed under the MIT License. See the LICENSE file for details.