Section 1: General Questions¶
Welcome to the OSA (Open-Source Advisor) FAQ! This section covers the most common questions about what OSA is, who it's for, and how to get started.
1.1 What is OSA (Open-Source Advisor)?¶
OSA (Open-Source Advisor) is an LLM-based multi-agent tool designed to automatically improve open-source repositories and make them easier to understand, run, and reuse.
What OSA does:
| Feature | Description |
|---|---|
| π README Generation | Creates clear, structured README files (standard or article-style for research papers) |
| π Documentation | Generates docstrings for Python code and builds web documentation with MkDocs |
| π§ CI/CD Setup | Automates workflow creation for testing, code quality, and deployment |
| π Repository Analysis | Provides actionable reports on project strengths and weaknesses |
| π€ Automated PRs | Creates pull requests with all proposed improvements |
| π Community Files | Adds contribution guidelines, Code of Conduct, issue/PR templates |
OSA was originally developed for researchers (biologists, chemists, etc.) who lack software engineering experience but need to share reproducible code with their publications. However, it works on any repository, not just scientific ones.
1.2 Who should use OSA?¶
OSA is designed for multiple audiences:
| Target Audience | Primary Use Case |
|---|---|
| Researchers & Scientists | Make research code reproducible and publication-ready with minimal effort |
| Academic Labs | Standardize documentation across multiple research repositories |
| Open-Source Developers | Save time on documentation and CI/CD setup for personal or team projects |
| Students | Learn best practices for open-source project maintenance |
| Organizations | Improve quality and security scores across dozens of repositories |
Ideal scenarios:
- β You have a repository linked to a research paper but no README
- β Your code lacks docstrings and documentation
- β You need CI/CD pipelines but don't know where to start
- β You maintain multiple repositories and need consistent quality
- β You want to improve your repository's security scorecard rating
1.3 What problems does OSA solve?¶
OSA addresses critical challenges in open-source project maintenance:
Scientific Open-Source Challenges:¶
| Problem | Impact | OSA Solution |
|---|---|---|
| β Code shared without README | Others can't understand or use it | β Auto-generates structured README |
| β No documentation/docstrings | Code is unreadable | β Generates comprehensive docstrings |
| β Missing CI/CD pipelines | No automated testing or quality checks | β Creates customizable workflows |
| β No license file | Legal uncertainty for users | β Adds appropriate license |
| β Poor repository structure | Confusing navigation | β Reorganizes tests/examples folders |
| β Low security scorecard rating | Reduced trust and adoption | β Improves score from ~2.2 to ~3.7+ |
General Developer Challenges:¶
| Problem | OSA Solution |
|---|---|
| β Procrastinating on documentation | β Automates it in minutes |
| β Maintaining dozens of repos | β Standardizes across all projects |
| β Missing contribution guidelines | β Generates community files |
| β No time for best practices | β Implements them automatically |
Key Advantage: Unlike tools that focus on individual components (e.g., Readme-AI only generates README, RepoAgent only generates code docs), OSA considers the repository holistically to make it easier to understand and ready to run.
1.4 Is OSA free to use?¶
Yes! OSA is completely free and open-source software.
| Aspect | Details |
|---|---|
| License | BSD 3-Clause "New" or "Revised" License |
| Cost | Free for personal and commercial use |
| Modification | You can modify and redistribute |
| LLM Costs | β οΈ Some providers (OpenAI, etc.) charge for API usage |
| Free Options | β ITMO-hosted models, Ollama (local), OpenRouter (free tier) |
What's included at no cost:
- β Full OSA tool functionality
- β All features (README, docs, CI/CD, reports)
- β Community support via Telegram
- β Regular updates and improvements
1.5 What license does OSA use?¶
OSA is protected under the BSD 3-Clause "New" or "Revised" License.
Permissions:
| β Allowed |
|---|
| Commercial use |
| Modification |
| Distribution |
| Private use |
| Sublicensing |
Conditions:
| β οΈ Required |
|---|
| Include original copyright notice |
| Include license text |
| No endorsement using contributor names |
No restrictions on:
- Using OSA for commercial projects
- Modifying the source code
- Distributing your modifications
For full details, see the LICENSE file.
1.6 Who developed OSA?¶
OSA was developed by researchers and developers at ITMO University (Saint Petersburg, Russia) as part of the AI Initiative Research Project (RPAII). Core Authors:
- Nikolay Nikitin
- Andrey Getmanov
- Zakhar Popov
- Ekaterina Ulyanova
- Ilya Sokolov
The project is tested and supported by the ITMO OpenSource community.
1.7 Where can I find publications about OSA?¶
OSA has been published and presented at several venues:
| Language | Publication | Link |
|---|---|---|
| π¬π§ English | Automate Your Coding with OSA β ITMO-Made AI Assistant for Researchers | ITMO News |
| π¬π§ English | An LLM-Powered Tool for Enhancing Scientific Open-Source Repositories | ICML 2025 Workshop |
| π¬π§ English | An End-to-End Guide to Beautifying Your Open-Source Repo with Agentic AI | Towards Data Science |
| π·πΊ Russian | OSA: ΠΠ-ΠΏΠΎΠΌΠΎΡΠ½ΠΈΠΊ Π΄Π»Ρ ΡΠ°Π·ΡΠ°Π±ΠΎΡΡΠΈΠΊΠΎΠ² Π½Π°ΡΡΠ½ΠΎΠ³ΠΎ open source ΠΊΠΎΠ΄Π° | Habr |
For citation formats, see How do I cite OSA in my research?
1.8 What is the OSA community and how do I join?¶
The OSA community consists of developers, researchers, and users who contribute to and support the project.
Ways to Connect:
| Platform | Purpose | Link |
|---|---|---|
| π GitHub Repository | Report issues, contribute code, view PRs | github.com/aimclub/OSA |
| π Documentation | Learn about API, features, and usage | aimclub.github.io/OSA |
| π¬ Video Demo | Watch OSA in action | YouTube |
| π Open-source-ops | Related tools, content, and best practices | github.com/aimclub/open-source-ops |
| π¬ Telegram Chat | Ask questions, get help, share news | @OSA_helpdesk |
Community Benefits:
- π Get help from developers directly
- π’ Stay updated on new features
- π€ Connect with other OSA users
- π‘ Share your use cases and improvements
1.9 What languages and platforms does OSA support?¶
OSA's current support matrix:
| Feature | Support Level | Details |
|---|---|---|
| Code Documentation | π Python | Docstrings for functions, methods, classes, modules |
| README Generation | π Any | Text-based, works with any project type |
| CI/CD Workflows | π Python | Tests, formatting, PEP8, PyPI publication |
| Repository Platforms | β GitHub, GitLab, Gitverse | Cloud and self-hosted instances |
| Interface Languages | π¬π§ English, π·πΊ Russian | Documentation and CLI |
| LLM Providers | β Multiple | OpenAI, Ollama, OpenRouter, VseGPT, Gigachat, ITMO |
Future Plans:
| Coming Soon | Description |
|---|---|
| π RAG System | Compare repos with best-practice references |
| π Multi-Language | Support for JavaScript, Java, etc. |
| π€ Conversational Mode | Natural language improvement requests |
| π Smart Detection | Skip already-high-quality components |